SAML federation in IG/OpenIG

This book provides information on SAML federation in IG/OpenIG and includes help on configuring federation and debug logging.


Configuring Federation


How do I set up signing and encryption for IG/OpenIG (All versions) when it is acting as the SAML 2.0 SP?

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

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

IG/OpenIG signing and encryption with SAML works in the same way as the Fedlet, which is detailed in SAML v2.0 Guide › 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 under the configuration directory for AM, such as $HOME/openam/openam/ for a server instance with 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 http://openam.example.com:8080/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 same file system directory as the AM keystore.jceks file.

To set up signing and encryption in IG/OpenIG:

  1. Follow the steps detailed in the Developer's 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/OpenIG: 
    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/OpenIG 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/OpenIG:
      $ echo <encodedValue> > .keypass
      $ echo <encodedValue> > .storepass
      
    6. Restart IG/OpenIG.
Note

You could use AM/OpenAM'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/OpenAM encryption key outside of AM/OpenAM, which is not recommended in production for security reasons.

Setting up signing and encryption key passwords - via scripting

By making use of IG/OpenIG'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/OpenAM federation and shared libraries are included in the IG/OpenIG 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/OpenIG, for example:
    -Dam.encryption.pwd=yeOsKiuSuSreqfe1AXvisuqquJZTBs6Y
    This value must match the value used in the FederationConfig.properties file (located in the $HOME/.openig/ SAMLdirectory) to ensure that the IG/OpenIG 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 to run 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/OpenIG 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/OpenIG host, for example:
    http://host1.example.com:8080/encode
    This 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/OpenIG

Gateway Guide › Acting As a SAML 2.0 Service Provider

Gateway Guide › Acting As a SAML 2.0 Service Provider › Configuring IG As an SP

Related Training

N/A

Related Issue Tracker IDs

OPENIG-399 (Encapsulate SAML configuration for common use cases)


How do I change the algorithm used to sign SAML requests in IG (All versions) and OpenIG 4.5?

The purpose of this article is to provide information on changing the signature algorithm used to sign SAML requests in IG/OpenIG. By default, SAML requests are signed by rsa-sha1.

Overview

IG/OpenIG signing and encryption with SAML works in the same way as the Fedlet, which is detailed in SAML v2.0 Guide › Enabling Signing and Encryption in a Fedlet

If you have not already done so, you should configure signing and encryption in IG/OpenIG per How do I set up signing and encryption for IG/OpenIG (All versions) when it is acting as the SAML 2.0 SP?

Supported signature algorithms

The following signature algorithms are supported:

Signature algorithm Corresponding value to use in FederationConfig.properties file
rsa-sha1 http://www.w3.org/2000/09/xmldsig#rsa-sha1
rsa-sha256 http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
rsa-sha384 http://www.w3.org/2001/04/xmldsig-more#rsa-sha384
rsa-sha512 http://www.w3.org/2001/04/xmldsig-more#rsa-sha512
dsa-sha1 http://www.w3.org/2000/09/xmldsig#dsa-sha1
ecdsa-sha1 http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha1
ecdsa-sha256 http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256
ecdsa-sha384 http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha384
ecdsa-sha512 http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha512

Changing the signing algorithm

You can change the signing algorithm in IG/OpenIG as follows:

  1. Update the FederationConfig.properties file (located in the $HOME/.openig/SAML directory) and set the following property to the required algorithm value (per the table in the Overview section):
    org.forgerock.openam.saml2.query.signature.alg.rsa=
    For example, to use the rsa-sha256 algorithm, you would set this property as follows:
    org.forgerock.openam.saml2.query.signature.alg.rsa=http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
  2. Restart IG/OpenIG to apply these changes. 

See Also

How do I set up signing and encryption for IG/OpenIG (All versions) when it is acting as the SAML 2.0 SP?

FAQ: SAML federation in IG/OpenIG

How do I collect debug logs in IG/OpenIG (All versions) for troubleshooting?

Gateway Guide › Acting As a SAML 2.0 Service Provider

Related Training

N/A

Related Issue Tracker IDs

OPENAM-1900 (Provide support for more XML signatures types in SAML query string verification process)


Debug Logging


How do I collect debug logs in IG/OpenIG (All versions) for troubleshooting?

The purpose of this article is to provide information on collecting debug logs in IG/OpenIG for troubleshooting. This includes collecting message level SAML logs if you are using IG/OpenIG for SAML federation.

Overview

Logging in IG 5 has changed and is now solely based on a Logback implementation of the Simple Logging Facade for Java® (SLF4J) API. Configurations will require updating if they are based on earlier versions of the product, see IG 5 Release Notes › Important Changes to Existing Functionality for an overview of the logging and other key changes. 

This article covers collecting the following debug logs:

Collecting IG 5 and later logs

The default logging configuration of IG 5 and later is detailed in Gateway Guide › Default Logging Behavior. IG creates log entries on a per-route basis in the $HOME/.openig/logs/ directory and to standard-out at level INFO. Without any additional configuration, a log file called route-system.log is created with entries that cover the startup of IG and the loading of any routes defined in the routes configuration sub-directory.

You can enable capturing entries for a particular route by adding a capture decorator alongside any handlers of interest.

Simple example in the default route

{
  "handler": "ClientHandler",
  "capture": "all"
}

Example Logging output

09:29:49:349 | INFO  | qtp630669831-13 | o.f.o.d.c.C.c.top-level-handler | 

--- (request) id:5c4776e5-22be-4a3d-bee9-6bcc5e5af58e-44 --->

GET http://localhost:8080/examples/servlets/ HTTP/1.1
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
Accept-Encoding: gzip, deflate, sdch, br
Accept-Language: en-US;q=1,en;q=0.9,fr;q=0.8
Cache-Control: max-age=0
Connection: keep-alive
Host: localhost:7070
Upgrade-Insecure-Requests: 1
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.98 Safari/537.36

09:29:49:356 | INFO  | I/O dispatcher 2 | o.f.o.d.c.C.c.top-level-handler | 

<--- (response) id:5c4776e5-22be-4a3d-bee9-6bcc5e5af58e-44 ---

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Length: 5343
Content-Type: text/html
Date: Sun, 09 Apr 2017 21:29:49 GMT
ETag: W/"5343-1357811674000"
Last-Modified: Thu, 10 Jan 2013 09:54:34 GMT
Server: Apache-Coyote/1.1

[entity]

Capturing additional details

To change the default behavior of the CaptureDecorator, either override the default for all routes by adding a customized version in the heap of the config.json file or add an entry to the heap of a specific route, see Configuration Reference › CaptureDecorator. For example:

{
    "name": "capture",
    "type": "CaptureDecorator",
    "config": {
        "captureContext": true,
        "captureEntity": true
    }
}

To change the behavior of the Logback configuration, override the default settings by creating a new logback.xml file in the $HOME/.openig/config/ directory and adjust the logging level in one of the following places:

  • The global level:
      <root level="DEBUG">
        <appender-ref ref="SIFT"/>
        <appender-ref ref="STDOUT"/>
      </root>
    
  • For a specific component:
      <logger name="org.forgerock.openig.handler.ClientHandler" level="DEBUG"/>
    

Once you have reproduced the problem and captured the log output, you may want to revert the captureEntity and captureContext properties to false again and revert the log level to INFO to avoid filling up disk space.

Collecting OpenIG 3.x and 4.x logs

There are two log outputs you should collect for troubleshooting OpenIG: Entity and Context logs. The output from these logs is sent to one of the following depending on your logging configuration:

  • stdout (catalina.out if you are using Apache Tomcat™) - ConsoleLogSink. This is the default logging mechanism.
  • log file - FileLogSink.
Note

OpenIG 4.5 introduced a new option (Slf4jLogSink) to allow you to access all log messages from SLF4J loggers using the Logback implementation of the SLF4J API. See OpenIG 4.5 Gateway Guide › Logging Events in OpenIG and OpenIG 4.5 Configuration Reference › Slf4jLogSink — delegate log writing to SLF4J for further information. This has been replaced in IG 5 with the SLF4J class Logger. See IG 5 Release Notes › Important Changes to Existing Functionality for further information.

You can enable OpenIG to capture these log files as follows:

  1. Update the config.json file (located in the $HOME/.openig/config/ directory) and set the captureEntity and captureContext properties to true for the default CaptureDecorator:
     {
                "name": "capture",
                "type": "CaptureDecorator",
                "config": {
                    "captureEntity": true,
                    "captureContext": true
                }
     }
    
  2. Update the config.json file and set the level to DEBUG for the default ConsoleLogSink or FileLogSink depending on which one you are using:
    • ConsoleLogSink:
       {
                  "name": "LogSink",
                  "type": "ConsoleLogSink",
                  "config": {
                      "level": "DEBUG"
                  }
       }
      
    • FileLogSink:
       {
                  "name": "LogSink",
                  "type": "FileLogSink",
                  "config": {
                      "file": "/tmp/gateway.log",
                      "level": "DEBUG"
                  }
       }
      
  3. Restart OpenIG to apply these changes. The log details are output to stdout or the file you specified. 

Example log output

The following example log shows the type of information you will see in the stdout if the logs have been correctly generated:

INFO: Server startup in 5194 ms
...
------------------------------
THU JUL 07 11:21:02 EST 2016 (DEBUG) {Router}/handler
Added route '05-federate.json' defined in file '/home/suser/.openig/config/routes/05-federate.json'
...
--- (request) exchange:641186666 --->
GET ...

Once you have reproduced the problem and captured the log output, you may want to revert the captureEntity and captureContext properties to false again and revert the log level to INFO to avoid filling up disk space.

Collecting SAML logs

You can enable IG/OpenIG to capture the SAML log file (libSAML2) at message level as follows:

  1. Update the FederationConfig.properties file (located in the $HOME/.openig/SAML directory) and set these two properties as follows:
    com.iplanet.services.debug.level=message 
    com.iplanet.services.debug.directory=$HOME/.openig/SAML/debug
  2. Restart IG/OpenIG to apply these changes. The libSAML2 log file is output to the debug directory you specified.

Once you have reproduced the problem and captured the libSAML2 log file, you may want to revert the com.iplanet.services.debug.level property to error again to avoid filling up the disks where the debug logs are stored. 

See Also

OpenIG 4 Configuration Reference › Decorators › CaptureDecorator

OpenIG 4 Configuration Reference › Logging Framework

Gateway Guide › Logging Events

Gateway Guide › Troubleshooting

Related Training

N/A

Related Issue Tracker IDs

N/A


Frequently Asked Questions


FAQ: SAML federation in IG/OpenIG

The purpose of this FAQ is to provide answers to commonly asked questions regarding SAML federation in IG/OpenIG.

Frequently asked questions

Q. How should IG/OpenIG work for SAML federation with AM/OpenAM as the IdP Proxy?

A. IG/OpenIG as the SP and AM/OpenAM as the IdP Proxy should work as follows:

  1. You have an endpoint to deal with SP initiated SSO for non-authenticated users; this should redirect to .../openig/SPInitiatedSSO and be dealt with by the SamlFederationHandler that sends the SAML Authentication Response to the IdP proxy.
  2. You have an endpoint that receives the Authentication Response; this contains .../openig/fedletapplication and should be dealt with by the SamlFederationHandler that uses its configuration to map the content of the assertion and redirect.
  3. You have an endpoint that deals with SP initiated SLO; this should redirect to .../openig/SPInitiatedSLO and be dealt with by the SamlFederationHandler that sends the SAML Logout Request to the IdP proxy.
  4. You have an endpoint that receives the SLO Response; this contains .../openig/fedletSloRedirect and should be dealt with by the SamlFederationHandler that uses its configuration to redirect.
  5. AM/OpenAM is in charge of logging out the external IdPs, sending logout requests to the other SPs and logging out the user from the proxy itself.
Note

No configuration on the IG/OpenIG side should have to actively log out another application that uses federation to log in.

Q. What are the expected access flows for IG/OpenIG with SAML federation using an IdP proxy?

A. The expected access flows are as follows:

IG/OpenIG does SP initiated SSO 

  1. The user is redirected to the IdP proxy.
  2. The user is redirected to the IdP.
  3. The user authenticates and gets an IdP session.
  4. The user gets an IdP proxy session.
  5. The user gets an IG/OpenIG session.

IG/OpenIG does a SP initiated SLO

  1. The IG/OpenIG initiated logout request arrives at the IdP proxy.
  2. The IdP proxy relays the request to the IdP.
  3. The IdP ends the IdP session.
  4. The IdP sends a logout response to the IdP proxy.
  5. The IdP proxy ends the IdP proxy session.
  6. The IdP proxy relays the response to IG/OpenIG.
  7. IG/OpenIG ends the session.

Q. How do I enable message level debug logging for SAML?

A. You can enable IG/OpenIG to capture the SAML log file (libSAML2) at message level as detailed in How do I collect debug logs in IG/OpenIG (All versions) for troubleshooting? (Collecting SAML logs).

Q. How do I set up signing and encryption in IG/OpenIG?

A. IG/OpenIG signing and encryption with SAML works in the same way as the Fedlet, which is detailed in SAML v2.0 Guide › Enabling Signing and Encryption in a Fedlet

See How do I set up signing and encryption for IG/OpenIG (All versions) when it is acting as the SAML 2.0 SP? for further information on setting this up in IG/OpenIG.

Q. Can IG/OpenIG be used as a Service Provider to protect multiple applications?

A. Yes, as of OpenIG 4, you can use a single IG/OpenIG server as a SAML 2 Service Provider (SP) for multiple protected applications. See Gateway Guide › SAML 2.0 and Multiple Applications for further information.

With earlier versions of OpenIG, you should consider using AM/OpenAM as a SP with a policy agent to control access and proxy to multiple applications instead. See the following chapters for further information to get you started:

See Also

Gateway Guide › Acting As a SAML 2.0 Service Provider

Related Training

N/A

Related Issue Tracker IDs

OPENIG-399 (Encapsulate SAML configuration for common use cases)

OPENIG-867 (Update the SAML documentation to include details of SLO URL changes when using multiple SPs/Applications)

OPENIG-834 (Single logout processing in SamlFederationHandler.serviceSPInitiatedSLO does not correctly pass the metaalias property)

OPENAM-5096 (Single Logout (SLO) via Proxy - active session partner in sendLastResponse())


Copyright and TrademarksCopyright © 2018 ForgeRock, all rights reserved.

This content has been optimized for printing.

Loading...