WAS v8.5 > Secure applications > Secure web services > Secure web services > Administer Web Services Security > Administer message-level security for JAX-WS web services > Secure messages using SAML

SAML holder-of-key symmetric key token

Configure the client and provider policy set attachments and bindings for the SAML holder-of-key token. This configuration scenario uses a symmetric key.

After installing, create one or more new server profiles, or add SAML configuration settings to an existing profile. For example, in a network deployment environment, there are multiple profiles. Read about setting up the SAML configuration for more information.

WebSphere Application Server with SAML provides numerous default SAML token application policy sets and several general client and provider binding samples. Before we can configure the client and provider bindings for the SAML holder-of-key token, you must import one of these default policy sets: SAML20 HoK Symmetric WSSecurity default or SAML11 HoK Symmetric WSSecurity default. The SAML11 policy sets are almost identical to the SAML20 policy sets, except that SAML20 HoK Symmetic WSSecurity default policy set supports the SAML v2.0 token type, while the SAML11 HoK Symmetric WSSecurity default policy set supports the v1.1 token type.

The SAML token policy is defined by a CustomToken extension in the application server. To create the CustomToken extension, define the SAML token configuration parameters in terms of custom properties in the client and provider binding document. The Saml HoK Symmetric Client sample and the Saml HoK Symmetric Provider sample general bindings contain the essential configuration for the custom properties. The client and provider sample bindings contain both SAML11 and SAML20 token type configuration information and therefore can be used with both SAML11 and SAML20 policy sets. Depending on how you plan to implement the SAML tokens, modify the property values in the installed binding samples. Examples of the properties and property values are provided in the procedure.

The procedure for modifying the binding sample begins with configuring the web services client policy set attachment, then configuring the web services provider policy set attachment. The example presented in the procedure uses the sample web services application JaxWSServicesSamples.

  1. Import two default policy sets: SAML20 HoK Symmetric WSSecurity default, and the Username WSHTTPS default.

    1. Click Services > Policy sets > Application policy sets.

    2. Click Import.

    3. Select From Default Repository.

    4. Select the two default policy sets.

    5. Click OK to import the policy sets.

    If we do not want the server to automatically request a SAML token from the security token service (STS) using the WS-Trust client, we can skip steps 2, 3, and 4, and continue to step 5. For example, we can skip steps 2, 3, and 4, if web services act as a client and self-issues a SAML token based on the original SAML token, or the web services client has already acquired a SAML token and cached the SAML token in the RequestContext.

  2. Attach a policy set for the trust client. Click Applications > Application types > WebSphere enterprise applications > JaxWSServicesSamples > Service client policy sets and bindings. The steps which pertain to attaching and detaching the policy set, and configuring the trust client binding, are required only if an application-specific binding is used to access the external STS. We can skip these steps, and go to the step that discusses configuring communication with the STS, if we use a general binding to access the external STS.

    1. Select the check box for the web services client resource.

    2. Click Attach Client Policy Set.

    3. Select the policy set, Username WSHTTPS default.

    This step attaches the policy set to the web services trust client, as you would do to use this policy set for the application client to access the target web services. However, since you plan to use the Username WSHTTPS default policy set to access an external STS instead, the policy set is only temporarily attached to the Web services client. The purpose of this step is to allow us to use the dmgr console to create or to modify the client binding document.

  3. Configure the trust client binding.

    1. Select the web services client resource again.
    2. In the Service client policy sets and bindings panel, click Assign Binding.

    3. Click New Application Specific Binding to create an application-specific binding.

    4. Specify a binding configuration name for the new application-specific binding. In this example, the binding name is SamlTCSample.

    5. Add the SSL transport policy type to the binding. Optionally, we can modify the NodeDefaultSSLSettings settings. Click Security > SSL certificate and key management > SSL configurations > NodeDefaultSSLSettings.

  4. Add the WS-Security policy type to the binding, then modify the authentication settings.

    1. Click Applications > Application types > WebSphere enterprise applications > JaxWSServicesSamples > Service client policy sets and bindings > SamlTCSample > Add > WS-Security > Authentication and protection > request:uname_token.

    2. Click Apply.

    3. Select Callback handler.

    4. Specify a user name and password (and confirm the password) to authenticate the web services client to the external STS.

    5. Click OK and Save.

  5. After the binding settings are saved, return to the Service client policy sets and bindings panel to detach the policy set and bindings.

    1. Click Applications > Application types > WebSphere enterprise applications > JaxWSServicesSamples > Service client policy sets and bindings.

    2. Click the check box for the web services client resource.

    3. Click Detach client policy set.

    The application-specific binding configuration you created in the previous steps is not deleted from the file system when the policy set is detached. This means that we can still use the application-specific binding you created to access the STS.

  6. Download the unrestricted jurisdiction policy file. The SAML20 HoK Symmetric WSSecurity default security policy uses the 256 bit encryption key size, which requires the unrestricted Java Cryptography Extension (JCE) policy file. For more information, read the section Using the unrestricted JCE policy files in the Tuning Web Services Security topic.
  7. Attach the SAML20 HoK Symmetric WSSecurity default policy set and assign the Saml HoK Symmetric Client sample binding to the client resource.

    1. Click Applications > Application types > WebSphere enterprise applications > JaxWSServicesSamples > Service client policy sets and bindings.

    2. Select the web services client resource.

    3. Click Attach Client Policy Set.

    4. Select the policy set, SAML20 HoK Symmetric WSSecurity default.

    5. Select the web services client resource again.
    6. In the Service client policy sets and bindings panel, click Assign Binding.

    7. Select the Saml HoK Symmetric Client sample general binding.

    8. Click Save.

  8. Configure the STS endpoint URL and the user name and password to authenticate to the STS.

    1. Click Applications > Application types > WebSphere enterprise applications > JaxWSServicesSamples > Service client policy sets and bindings > Saml HoK Symmetric Client sample > WS-Security > Authentication and protection.

    2. Click gen_saml20token in the Protection tokens table.

    3. Click Callback handler.

    4. Modify the stsURI property and specify the STS endpoint. If we do not use an external STS, and you want the application server to self-issue a holder-of-key assertion with a symmetric key, do not complete this step and go to step 8i.

    5. If necessary, modify the wstrustClientPolicy property and change the value to Username WSHTTPS default.

    6. Modify the wstrustClientBinding property and change the value to match the application-specific binding created in the previous steps. For this example, the value is SamlTCSample. This step attaches the WS-Trust client policy set. We can skip this step if we do not want the server to automatically request a SAML token from the STS using the WS-Trust client.

    7. Change the value of the wstrustClientBindingScope property, which controls how the application server searches for the binding. Set the property value to either application or domain. When the value is set to domain, the application server searches for the wstrustClientBinding at the file system location containing general binding documents. When the value is set to application, the application server searches for the wstrustClientBinding at the file system location containing application-specific binding documents. When the wstrustClientBindingScope property is not specified, the default behavior of the application server is to search for application-specific bindings and then search for general bindings. If the wstrustClientBinding can not be located, the application server uses the default bindings.
    8. Verify the value of the confirmationMethod property is Holder-of-key.
    9. Verify the value of the keyType property value is http://docs.oasis-open.org/ws-sx/ws-trust/200512/SymmetricKey or the symmetrickey alias. The wstrustClientWSTNamespace property determines how the symmetrickey alias is interpreted. In this case it is assumed that it is set to the WS-Trust 1.3 namespace. If it had a value of WS-Trust 1.2, the symmetrickey alias is interpreted as http://schemas.xmlsoap.org/ws/2005/02/trust/SymmetricKey.

    10. Optional: We can modify the default trust client SOAP version, which is the same as the application client. Set the custom property wstrustClientSoapVersion to the value 1.1 to change to SOAP v1.1, or set the property to the value 1.2 to change to SOAP v1.2.

    11. Optional: If you are not using an external STS, and you want the application server to self-issue a holder-of-key assertion with a symmetric key, set the custom property recipientAlias to the value of the key alias of the target service. Specifying this property protects the symmetric key for the target service. This alias must be a valid key alias contained in the configured trust store of the SAML issuer. The TrustStorePath property specifies the location of the trust store file. The TrustStorePath property is defined in the SAMLIssuerConfig.properties file for the application server. For example, the location of the SAMLIssuerConfig.properties file at the server level on a WebSphere Application server is:

        app_server_root/profiles/$PROFILE/config/cells/$CELLNAME/nodes/$NODENAME/servers/$SERVERNAME/SAMLIssuerConfig.properties
      The location of this file at the cell level on a WebSphere Application server is:

        app_server_root/profiles/$PROFILE/config/cells/$CELLNAME/sts/SAMLIssuerConfig.properties

    12. Click Apply and Save.

  9. Optional: If further modifications to the wstrustClientBinding configuration are needed, and the wstrustClientBinding property is pointing to an application-specific binding, attach the application-specific binding to the web services client before we can complete the modifications. The attachment is temporary. As detailed in the previous steps, we can detach the modified application-specific binding from the web service client after the modification is completed.
  10. Import the SSL certificate from the external STS.

    1. Click Security > SSL certificate and key management > Manage endpoint security configurations > server_or_node_endpoint > Keystores and certificates > NodeDefaultTrustStore > Signer certificates.
    2. Click Retrieve from port.

    3. Specify the host name and port number of the external STS server, and assign an alias to the certificate. Use the SSL STS port.

    4. Click Retrieve signer information.

    5. Click Apply and Save to copy the retrieved certificate to the NodeDefaultTrustStore object.

  11. Restart the web services client application so the policy set attachment modifications can take effect.
  12. Attach the SAML20 HoK Symmetric WSSecurity default policy set to the web services provider.
  13. Download the unrestricted jurisdiction policy file. The SAML20 HoK Symmetric WSSecurity default security policy uses the 256 bit encryption key size, which requires the unrestricted Java Cryptography Extension (JCE) policy file. For more information, read the section Using the unrestricted JCE policy files in the Tuning Web Services Security applications topic.
  14. Assign the Saml HoK Symmetric Provider sample general binding.

  15. Click Applications > Application types > WebSphere enterprise applications > JaxWSServicesSamples > Service provider policy sets and bindings > Saml HoK Symmetric Provider sample > WS-Security > Authentication and protection.

    1. Click con_saml20token in the Authentication tokens table.

    2. Click the Callback handler link.

    3. Use this panel to configure the embedded symmetric key decryption configuration, and the SAML token issuer digital signature validation to the external STS, as described in the following step.

  16. Configure the binding data to decrypt the embedded secret key, or the SAML assertion that is protected by the public key from the recipient. The STS must have access to the public key of the recipient. There are two options to configure the keys for decryption:

    • Option 1: Configure the keystore and a private key, as follows:

      1. Verify the Keystore name field has the value custom.

      2. Click Custom keystore configuration to view and edit the keystore configuration.
      3. Verify the initial value for the key file is app_server_root/etc/ws-security/samples/enc-service.jceks.

    • Option 2: Set the custom properties in the callback handler as follows:
      Custom property Value
      keyStorePath Keystore location
      keyStoreType Matching keystore type

      Supported keystore types include: jks, jceks, and pkcs12

      keyStorePassword Password for the keystore
      keyAlias The alias of the public key used for SAML encryption
      keyName The name of the public key used for SAML encryption
      keyPassword The password for the key name

  17. Add the external STS signing certificate to the truststore. This step is required if the SAML assertions are signed by the STS and the signatureRequired custom property is not specified, or has a value of true. This truststore is configured for the service provider.

    1. Set the custom property trustStoreType to match the keystore type. Supported keystore types include: jks, jceks, and pkcs12.

    2. Set the custom property trustStorePath to the keystore file location. For example, app_server_root/etc/ws-security/samples/dsig-issuer.jceks.

      The file dsig_issuer.jceks is not provided when WAS is installed, so create the file.

    3. Set the custom property trustStorePassword to the encoded value of the store password. The password is stored as a custom property and is encoded by the dmgr console.

    4. Optional: We can set the custom property trustedAlias to a value such as samlissuer. Do not set the trustedAlias property if the SAML token is signed by different signers, for example, if the STS delegates token requests to different token providers, and each provider signs with a certificate. If this custom property is not specified, the web services runtime environment uses the signing certificate password in the SAML assertions to validate the signature and then verifies the certificate against the configured truststore.

    5. Optional: We can set the custom property trustAnySigner to the value true to allow no signer certificate validation. The Trust Any certificate configuration setting is ignored for the purposes of SAML signature validation.

    6. Optional: We can set the custom property signatureRequired to false, which waives digital signature validation. However, a good security practice is to require SAML assertions to be signed and always require issuer digital signature validation.

    7. Optional: We can configure the recipient to validate either the issuer name or the certificate SubjectDN of the issuer in the SAML assertion, or we can validate both. Create a list of trusted issuer names, or a list of trusted certificate SubjectDNs, or both types of lists. If you create both issuer name and SubjectDN lists, both issuer name and SubjectDN are verified. If the received SAML issuer name or signer SubjectDN is not in the trusted list, SAML validation fails, and an exception is issued. This example shows how to create a list of trusted issuers and trusted SubjectDNs.

      For each trusted issuer name, use trustedIssuer_n where n is a positive integer. For each trusted SubjectDN, use trustedSubjectDN_n where n is a positive integer. If you create both types of lists, the integer n must match in both lists for the same SAML assertion. The integer n starts with 1, and increments by 1.

      In this example, you trust a SAML assertion with the issuer name WebSphere/samlissuer, regardless of the SubjectDN of the signer, so you add the following custom property:

        <properties value="WebSphere/samlissuer" name="trustedIssuer_1"/>

      In addition, you trust a SAML assertion issued by IBM/samlissuer, when the SubjectDN of the signer is ou=websphere,o=ibm,c=us, so you add the following custom properties:

        <properties value="IBM/samlissuer" name="trustedIssuer_2"/> <properties value="ou=websphere,o=ibm,c=us" name="trustedSubjectDN_2"/>

      By default, WAS trusts all SAML issuers when we do not define a trustedIssuer_n value. Without knowing this default behavior, you might mistakenly accept SAML assertions issued by an authorized STS

    8. Optional: We can add a list of non-root certificate authority (CA) certificates that can be used to check the signature of the SAML token. To add non-root certificates, add a custom property named X509PATH_n where n is a non-negative integer as the value for the non-root certificates.

    9. Optional: We can add a list of certificate revocation lists (CRLs) that can be used to validate the signature of the SAML token. To add CRLs, add a custom property named CRLPATH_n where n is a non-negative integer as the value for the CRLs.

    10. Click Apply and Save.

  18. Optional: We can configure the caller binding to select a SAML token to represent the requester identity. The Web Services Security runtime environment uses the specified JAAS login configuration to acquire the user security name and group membership data from the user registry using the SAML token NameId or NameIdentifier as the user name.

    1. Click Applications > Application types > WebSphere enterprise applications > JaxWSServicesSamples > Service provider policy sets and bindings > Saml HoK Symmetric Provider sample > WS-Security > Callers.

    2. Click New to create the caller configuration

    3. Specify a Name, such as caller.

    4. Enter a value for the Caller identity local part. For example, http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0, which is the local part of the CustomToken element in the attached WS-Security policy.

    5. Click Apply and Save.

  19. Restart the web services provider application so the policy set attachment modifications can take effect.


Results

After completing the procedure, the JaxWSServicesSamples web services application is ready to use the SAML20 HoK Symmetric default policy set, the Saml HoK Symmetric Client sample, and the Saml HoK Symmetric Provider sample general bindings.


Subtopics


Related


Communicate with STS
Tune Web Services Security for v8.5 applications


Reference:

SAMLIssuerConfig.properties file


+

Search Tips   |   Advanced Search