How To
ForgeRock Identity Platform
ForgeRock Identity Cloud

How do I set up signing and encryption for IG 6.x and 7 when it is acting as the SAML 2.0 SP?

Last updated Sep 22, 2021

The purpose of this article is to provide information on configuring signing and encryption in IG when it is acting as the Service Provider (SP) for SAML federation. You can either do this via the fedletEncode.jsp or scripting.


Overview

In IG 7.1 and later, you can use the Commons Secrets Service for signing and encryption when AM provides signed or encrypted SAML assertions. See Set Up Federation With Signed/Encrypted Assertions for further information.

Pre-IG 7.1 

IG signing and encryption with SAML works in the same way as the Fedlet, which is detailed in Enabling Signing and Encryption in a Fedlet. The key information to note is you should use the fedletEncode.jsp to create the .keypass and .storepass files. From the SAML v2.0 Guide:

On the Fedlet side, set up a JCEKS keystore used for signing and encryption. For evaluation, you can use copy the keystore.jceks file delivered with AM. You can find the file in the $HOME/openam/security/keystores/ directory for a server instance with the base URI openam. The built-in keystore includes the test certificate.

You must also set up the .storepass and .keypass files using the fedletEncode.jsp page, such as https://openam.example.com:8443/fedlet/fedletEncode.jsp, to encode passwords on the Fedlet side.

The passwords for the test keystore and private key are recorded in the AM .storepass and .keypass files. These files are located in the /path/to/openam/security/secrets/defaults/ directory.

You can either use the fedletEncode.jsp page directly to set up signing and encryption, or you can use scripting to emulate the fedletEncode.jsp page. 

Setting up signing and encryption key passwords - via fedletEncode.jsp

To set up signing and encryption in IG:

  1. Follow the steps detailed in the SAML v2.0 Guide for setting up signing and encryption for the Fedlet. Where it details encrypting the keypass and storepass using fedletEncode.jsp, you should follow these steps instead since this tool is not available in IG:
    1. Deploy the fedlet.war application temporarily.
    2. Copy the value of the am.encryption.pwd property from the FederationConfig.properties file (located in the $HOME/.openig/SAML directory) and paste this into the FederationConfig.properties file for the Fedlet (located in the $HOME/fedlet directory). This means the Fedlet is now using the encryption key from your IG deployment.
    3. Restart the Fedlet.
    4. Navigate to the fedletEncode.jsp and encode your password, for example: http://host1.example.com:8080/fedlet/fedletEncode.jsp
    5. Copy the encoded value you generated in the previous step to the .keypass and .storepass files in IG: $ echo <encodedValue> > .keypass $ echo <encodedValue> > .storepass
    6. Restart IG.
Note

You could use AM's encryption key instead by copying it from the am.encryption.pwd property and using this to update the value in the FederationConfig.properties file (located in the $HOME/.openig/SAML directory). However, this approach means having your AM encryption key outside of AM, which is not recommended in production for security reasons.

Setting up signing and encryption key passwords - via scripting

By making use of IG's scripting handler, you can emulate the fedletEncode.jsp page with a combination of a simple route and Groovy script file. This leverages the fact that the AM federation and shared libraries are included in the IG WAR as part of supporting the SAML 2.0 SP functionality. This requires the following high level steps:

  1. Add the am.encryption.pwd property and value as a JVM property of the container running IG, for example: -Dam.encryption.pwd=yeOsKiuSuSreqfe1AXvisuqquJZTBs6YThis value must match the value used in the FederationConfig.properties file (located in the $HOME/.openig/ SAMLdirectory) to ensure that the IG SAML functionality can decode the password when it needs access to either the signing or encryption keys.
  2. Create a groovy script file called Encode.groovy in the $HOME/.openig/scripts/groovy directory, for example: import com.iplanet.services.util.Crypt; import com.sun.identity.configuration.FedLibSystemProperties; import com.sun.identity.shared.Constants; FedLibSystemProperties props = new FedLibSystemProperties(); if (props.get(Constants.ENC_PWD_PROPERTY) == null) { props.initializeProperties(System.getProperties()); } response = new Response(Status.OK); response.headers.add("Content-Type", "text/html; charset=utf-8"); String[] password = request.form['password']; if (password == null || password[0] == null) { response.entity = "<html><body><p> <form name='frm' action='encode' method='post'> Enter the password to encode <input type='text' name='password' autocomplete='off' /> <input type='submit' value='Encode' /> </form> </p></body></html>"; } else { response.entity = "<html><body><p> Encoded password is: " + Crypt.encode(password[0]) + "</p><a href='encode'>Encode Another Password</a></body></html>"; } return response;
Warning

This script is provided as-is and is not something we would recommend running in a production deployment but more something that would be used on a development instance. Encoded passwords for different environments can be generated by altering the value used in the am.encryption.pwd JVM property and restarting the IG container.

  1. Create a route file to reference the Encode.groovy script, for example 01-encode.json, in the $HOME/.openig/config/routes directory, for example: { "handler": {  "type": "ScriptableHandler",   "config": { "type": "application/x-groovy", "file": "Encode.groovy"   } }, "condition": "${matches(request.uri.path, '^/encode')}" }
  2. Access the new route using the /encode URI of the IG host, for example: http://host1.example.com:8080/encodeThis URI generates a very simple HTML form where you can enter the password you want to encode, the result of posting the form will be the encoded password that you can copy into either the .keypass or .storepass file, as shown in the section above. If you adjust the condition of the route, you should change the URI accordingly.

See Also

FAQ: SAML federation in IG

Acting As a SAML 2.0 Service Provider

Set Up SAML 2.0 SSO and Federation

Related Training

N/A

Related Issue Tracker IDs

N/A


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.