Federation Guides › Partnership Federation Guide › Partnership Creation and Activation › Sign and Encrypt Federation Messages › Signature Configuration at the SAML 1.1 Consumer

Signature Configuration at the SAML 1.1 Consumer

The Signature step lets you define how SiteMinder uses private keys and certificates to verify SAML assertions and assertion responses.

Note: SAML 1.1 does not support encryption.

There can be multiple private keys and certificates in the certificate data store. If you have multiple federated partners, you can use a different key pair for each partner.

Note: If the system is operating in FIPS_COMPAT or FIPS_MIGRATE mode, all certificate and key entries are available from the pull-down list. If the system is operating in FIPS-Only mode, only FIPS-approved certificate and key entries are available.

Follow these steps:

1. Begin by selecting the Signature step in the partnership wizard.
2. Select an alias from the certificate data store for the Verification Certificate Alias field.

   By completing this field, you are indicating which certificate verifies signed assertions or responses or both. If there is no certificate in the certificate data store, click Import to import one. Alternatively, click Generate to create a certificate request.

Note: If you are using the product in a test environment, you can disable signature processing to simplify testing. Click the Disable Signature Processing checkbox.

Signature configuration at the SAML 1.1 consumer is complete.

Signature Configuration at a SAML 2.0 IdP

The Signature and Encryption step in the partnership wizard lets you define how the product uses private keys and certificates for the following signing functions:

• Sign and verify SAML assertions, assertion responses, and authentication requests.

  For SAML 2.0 POST binding, you are required to sign assertions.

• Sign single logout responses and requests (HTTP-Redirect and SOAP bindings).

There can be multiple private keys and certificates in the certificate data store. If you have multiple federated partners, you can use a different key pair for each partner.

Note: If the system is operating in FIPS_COMPAT or FIPS_MIGRATE mode, all certificate and key entries are available from the pull-down list. If the system is operating in FIPS-Only mode, only FIPS-approved certificate and key entries are available.

To configure signing options

1. Select the Signature and Encryption step in the partnership wizard.
2. In the Signature section, select an alias for the Signing Private Key Alias field. If there is no private key available, click Import to import one. Or, click Generate to create a certificate request.

   By completing this field, you are indicating which private key the asserting party uses to sign assertions, single logout requests and responses.

   Note: click on Help for a description of the fields.

3. Select the hash algorithm for digital signing in the Signing Algorithm field. The IdP signs assertions, responses and SLO-SOAP messages with the specified algorithm.

   Select the algorithm that best suits your application.

   RSAwithSHA256 is more secure than RSAwithSHA1 due to the greater number of bits used in the resulting cryptographic hash value.

   The system uses the algorithm that you select for all signing functions.

4. Select an alias from the certificate data store or the Verification Certificate Alias field.

   By completing this field, you are indicating which certificate verifies signed authentication requests or single logout requests or responses. If there is no certificate in the database, click Import to import one.

5. (Optional) Specify Artifact and POST signature options for the assertion or response or both.
6. (Optional) Specify an SLO SOAP signature option for the logout request, the logout response or both when you are using single logout.
7. (Optional) Select the check box for Require Signed Authentication Requests. This check box verifies that the asserting party only accepts signed requests from the relying party.

   Activate a partnership for all configuration changes to take effect and for the partnership to become available for use. Restarting the services is not sufficient.

If you are using the product in a test environment, you can disable signature processing to simplify testing. Click the Disable Signature Processing check box.

Important! Enable signature processing in a SAML 2.0 production environment.

Encryption Configuration at a SAML 2.0 IdP

The Signature and Encryption step in the Partnership wizard lets you define how the Policy Server uses private keys and certificates to do the following tasks:

• Sign and verify SAML assertions, assertion responses, and authentication requests.

  For SAML 2.0 POST binding, you are required to sign assertions.

• Sign single logout responses and requests (HTTP-Redirect and SOAP bindings).
• Encrypt and decrypt entire assertions, Name IDs and attributes.

There can be multiple private keys and certificates in the certificate data store. If you have multiple federated partners, you can use a different key pair for each partner.

To configure encryption options

1. In the Encryption section, select one or both of the following check boxes to specify the assertion data to be encrypted:
   • Encrypt Name ID
   • Encrypt Assertion
2. Select the certificate alias from the certificate data store for the Encryption Certificate Alias.

   This certificate encrypts assertion data. If no certificate is available, click Import to import one.

3. Select values for the Encryption Block Algorithm and Encryption Key Algorithm fields.

   For the following block/key algorithm combinations, the minimum key size that is required for the certificate is 1024 bits.

   • Encryption Block Algorithm: 3DES

     Encryption Key Algorithm: RSA-OEAP

   • Encryption Block Algorithm: AES-256

     Encryption Key Algorithm: RSA-OEAP

     Note: To use the AES-256 bit encryption block algorithm, install Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files. You can download these files from http://java.sun.com/javase/downloads/index.jsp.

The encryption configuration is complete.

Signature Configuration at a SAML 2.0 SP

The Signature and Encryption step in the partnership wizard lets you define how the Policy Server uses private keys and certificates to do the following tasks:

• Verify SAML assertions signatures and assertion responses and sign authentication requests.

  Note: For SAML 2.0 POST binding, the IdP is required to sign assertions.

• Sign single logout responses and requests (HTTP-Redirect and SOAP bindings).

There can be multiple private keys and certificates in the certificate data store. If you have multiple federated partners, you can use a different key pair for each partner.

Note: If the system is operating in FIPS_COMPAT or FIPS_MIGRATE mode, all certificate and key entries are available from the pull-down list. If the system is operating in FIPS-Only mode, only FIPS-approved certificate and key entries are available.

To configure signing options

1. Begin by selecting the Signature and Encryption step in the partnership wizard.
2. In the Signature section, select an alias from the certificate data store for the Signing Private Key Alias field. If there is no private key in the database, click Import to import one. Or, click Generate to create a key pair and generate a certificate request.

   By completing this field, you are indicating which private key the relying party uses to sign authentication requests and single logout requests and responses.

   Note: Click Help for a description of fields, controls, and their respective requirements.

3. Select the hash algorithm for digital signing in the Signing Algorithm field. The SP signs authentication requests and SLO-SOAP messages with the specified algorithm.

   Select the algorithm that best suits your application.

   RSAwithSHA256 is more secure than RSAwithSHA1 due to the greater number of bits used in the resulting cryptographic hash value.

   SiteMinder uses the algorithm that you select for all signing functions.

4. Select an alias from the certificate data store for the Verification Certificate Alias field.

   By completing this field, you are indicating which certificate the relying party uses to verify signed assertions or single logout requests and responses. If there is no certificate in the database, click Import to import one.

5. (Optional) For the SP to sign all authentication requests, select the Sign Authentication Requests. If the remote asserting party requires the authentication requests to be signed, check this option.

   Activate a partnership for all configuration changes to take effect and for the partnership to become available for use. Restarting the services is not sufficient.

If you are using SiteMinder in a test environment, you can disable signature processing to simplify testing. Click the Disable Signature Processing check box to disable the feature.

Important! Enable signature processing in a SAML 2.0 production environment.

Encryption Configuration at a SAML 2.0 SP

The Signature and Encryption step lets you configure how the SP uses private keys and certificates, including encrypting and decrypting assertions, Name IDs, and attributes.

There can be multiple private keys and certificates in the certificate data store. If you have multiple federated partners, you can use a different key pair for each partner.

Note: If the system is operating in FIPS_COMPAT or FIPS_MIGRATE mode, all certificate and key entries are available from the pull-down list. If the system is operating in FIPS-Only mode, only FIPS-approved certificate and key entries are available.

To configure encryption options

1. In the Encryption section, select one or both of the following check boxes so that the correct data is encrypted in the assertion:
   • Require encrypted Name ID
   • Require encrypted Assertion

   Note: To use the AES-256 bit encryption block algorithm, install the Sun Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files. You can download these files from http://java.sun.com/javase/downloads/index.jsp.

2. Select the alias from the certificate data store for the Decryption Private Key Alias.

   This private key decrypts any encrypted assertion data. If no certificate available, click Import to import one or click Generate to create a key pair and generate a certificate request.

The encryption configuration is complete.

Relying Party Interaction with Applications

The Application Integration step of the partnership wizard is applicable only at the relying party. This step lets you define various aspects of federated operation for resolving user identities and directing users to the target application.

The features that you can configure in the Application Integration step are:

• User redirection to the target application
• Mapping assertion attributes to application attributes (SAML only)
• Provisioning a user identity
• User redirection in case of an authentication failure

Redirecting a User to the Target Application

The Target Application section in the Application Integration step lets you define how a user gets redirected to the target application. The redirection method that you select depends on the type of data you want to pass with the user to the target application.

Follow these steps:

1. Navigate to the Application Integration step in the partnership wizard.
2. Select a redirection method for the Redirect Mode field. Note the following information:
   • If you select Cookie Data, you can URL-encode attribute data in the cookie by selecting the URL Encode Attribute Cookie Data check box. This option is only for SAML 1.1 and 2.0.
   • If you select the open-format cookie, configure the additional required settings and optional settings.

     If the relying party receives an assertion with multiple attribute values, the Policy Server passes all values to the target application in the cookie.

   • If you select one of the FIPS-compatible algorithms (AES algorithms), use a Federation Manager SDK to generate the open-format cookie. If you use the .NET SDK, use only the AES128/CBC/PKCS5Padding encryption algorithm.

     The target application must use the same language as the SDK that creates the cookie. If you are using the Federation Manager Java SDK, the application must be in Java. If you are using the .NET SDK, the application must support .NET.

   • If you select HTTP Headers as the redirect mode, SiteMinder can deliver multiple attribute values in a single header. Separate each attribute value with a comma. This option is only for SAML 1.1 and 2.0.

     Learn more about using HTTP Headers as the redirect mode and how to protect the headers.

   Click Help for a description of the fields.

3. Enter the URL of the target application in the Target field.

   If a proxy sits in front of the server with the target resource, enter the URL for the proxy host. The proxy handles all federation requests locally. The proxy host can be any system that sits in front of the target server. The proxy host can also be SiteMinder itself, provided it is being accessed directly from the Internet. Ultimately, when operating with a proxy, the URL you specify as the target must go through SiteMinder. For example, if the base URL is fed.demo.com and the back-end server resource is mytarget/target.jsp, the value for this field is http://fed.demo.com:5555/mytarget/target.jsp.

   For SAML 2.0, you can leave this field blank if you override it with the RelayState query parameter. The RelayState query parameter can part of the URL that triggers single sign-on. To enable this override, select the Relay state overrides target check box.

Setting up redirection to the target is complete.

Using HTTP Headers to Pass Assertion Data (SAML only)

For a SAML entity, the Policy Server can use HTTP headers to pass identity attributes from an assertion to a back-end application. A backend application can be a target application for single sign-on or a user provisioning application. The system passes these headers in an encrypted cookie.

The headers have the same name as the assertion attributes. For example, if the assertion attribute is "address", the application looks for the HTTP header "ADDRESS".

Assertion attributes are case-sensitive, but HTTP headers are not. The Policy Server cannot pass the same attributes that differ only by case sensitivity and then map them to HTTP headers. For example, the system cannot pass "address" and "Address" as headers at the same time. In general, do not use the attributes with the same names that are only different because of case sensitivity or format.

The following additional values are passed as headers:

• NAMEID
• FORMAT
• AUTHNCONTEXT

Protecting HTTP Headers

If an unauthorized user knows the name of an assertion attribute, that user can set this name as a header in a browser. With the header set, the malicious user can gain access to the target application. The target application sees an expected header value and grants access to the resource without SiteMinder consuming an assertion.

Setting a value for the FedHeaderPrefix protects against the following scenario:

1. An unauthorized user learns the names of HTTP headers. These header names include prefixes.
2. The malicious user sends an incoming request, including the headers, to the Policy Server.
3. The Policy Server recognizes that the headers containing prefixes come from an incoming request and are not generated internally so it removes these headers.
4. Before the system passes its own legitimate headers to the back-end application, it adds the specified prefix to each header. The headers are then passed to the application.

Configure HTTP Headers to Pass Assertion Data (SAML only)

SiteMinder can pass assertion data using HTTP headers.

Follow these steps:

1. Verify that the SiteMinder web agent is installed on the relying party system that is handling federation traffic.
2. Navigate to web_agent_home/conf and modify the WebAgent.conf file. Uncomment the following entry so it appears as follows:

   Windows

   LoadPlugin="path\SAMLDataPlugin.dll"

   UNIX

   LoadPlugin="path/SAMLDataPlugin.so"

3. (Optional but recommended) Add the setting fedheaderprefix setting to the appropriate Agent Configuration Object for the web agent. Enter any string as a prefix.

   The fedheaderprefix setting specifies a global prefix that SiteMinder adds to HTTP headers. Setting a prefix protects HTTP headers against manipulation by an unauthorized user before the SiteMinder consumes an assertion. As a result, only legitimate headers get passed to the target application. Read more about protecting HTTP headers.

4. Do one of the following tasks in the Application Integration step of the partnership wizard:
   • Select HTTP Headers as the Redirect Mode for the target application.
   • Select HTTP Headers as the Delivery Option for user provisioning.

HTTP headers are now configured to pass attribute data.