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 bearer token

A SAML bearer token is a SAML token that uses the Bearer subject confirmation method. In a bearer subject confirmation method, a sender of SOAP messages is not required to establish correspondence that binds a SAML token with contents of the containing SOAP message. We can configure the client and provider policy set attachments and bindings for the SAML bearer token.

WebSphere Application Server with SAML provides numerous default SAML token application policy sets and several general client and provider binding samples.

Before configuring the client and provider bindings for the SAML bearer token...

  1. Create one or more new server profiles that include SAML configuration settings, or add the settings to an existing profile.

  2. Import one of the following default policy sets:

    • SAML20 Bearer WSHTTPS default
    • SAML20 Bearer WSSecurity default
    • SAML11 Bearer WSHTTPS default
    • SAML11 Bearer WSSecurity default

The SAML11 policy sets are almost identical to the SAML20 policy sets, except the SAML20 policy sets support the SAML v2.0 token type, while the SAML11 policy sets support the v1.1 token type.

Two default policy sets are required. Therefore, you must import the Username WSHTTPS default policy set, and one of the following bearer policy sets. Verify the bearer policy set you import corresponds to your scenario; for example SAML 1.1 or 2.0 and HTTPS or non-HTTPS.

To import these policy sets, in the dmgr console:

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

  2. Click Import.

  3. Select From Default Repository.

  4. Select the two desired default policy sets.

    The SAML default policy set chosen in this step will be referred to as your appropriate SAML policy in the following procedure steps.

  5. Click OK to import the policy sets, and then click Save to save your changes.

  • If the SAML assertions will be signed by the STS and you will require trust evaluation of the issuer (the signer), a keystore file that can be used for trust evaluation of the issuer's X.509 certificate must be available. This keystore can either contain the issuer's public certificate or all the information required to build the certificate's path. Supported keys store types include: jks, jceks, and pkcs12. This file will be referred to as the trust store file in the following procedure.
  • The Username WSHTTPS default policy will be used to communicate with the STS. If the STS issuer certificate for use with SSL has not been imported into NodeDefaultSSLSettings, see the topic Retrieving signers from a remote SSL port for a description of how import this certificate. You also might want to review the topic Secure installation for client signer retrieval in SSL for more general information about STS issuer certificates.

    A SAML token policy is defined by a CustomToken extension in the application server. To create the CustomToken extension, you must define the SAML token configuration parameters in terms of custom properties in the client and provider binding document. The Saml Bearer Client sample and the Saml Bearer Provider sample for 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. These samples 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 following procedure.

    As the following procedure indicates, to modifying the binding sample, first configure the web services client policy set attachment, and then modify the web services provider policy set attachment. The example provided in the procedure uses the sample web services application JaxWSServicesSamples.

    1. Configure the trust client

      If you will be using general bindings to access the external STS, skip to Attach the policy set and bindings to the client application step.

      If you will be using application specific bindings to access the external STS, complete the following substeps.

      1. Temporarily Attach a policy set for the trust client to the web services client application so that bindings can be configured.

        Attaching a policy set for the trust client allows you to use the dmgr console to create, and then modify the client binding document bindings. You only have to complete this action if an application-specific binding is used to access the external STS.

        1. In the dmgr console, click Applications > Application types > WebSphere enterprise applications > JaxWSServicesSamples > Service client policy sets and bindings.

        2. Select the web services client resource (JaxWSServicesSamples).

        3. Click Attach Client Policy Set.

        4. Select the policy set Username WSHTTPS default.

      2. Create the trust client binding.

        1. Select the web services client resource again (JaxWSServicesSamples).

        2. 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.

      3. Add the SSL transport policy type to the binding,

        Click Add > SSL transport and then click OK.

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

        1. If the he WS-Security policy type is not already in the SamlTCSample binding definition, click Applications > Application types > WebSphere enterprise applications > JaxWSServicesSamples > Service client policy sets and bindings > SamlTCSample.

        2. Click Add > WS-Security > Authentication and protection > request:uname_token.

        3. Click Apply.

        4. Select Callback handler

        5. Specify a user name and password for the web services client to authenticate to the external STS.

        6. Click OK, and then click Save.

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

        1. Click either Service client policy sets and bindings in the navigation for this page, or Applications > Application types > WebSphere enterprise applications > JaxWSServicesSamples > Service client policy sets and bindings.

        2. Select the web services client resource (JaxWSServicesSamples), and then click Detach client policy set.

        The application-specific binding configuration you just created is not deleted from the file system when the policy set is detached. Therefore, we can still use the application-specific binding you created to access the STS with the trust client.

    2. Attach the SAML policy set and bindings to the client application

      1. Attach the desired SAML policy set to the web services client application.

        1. If the SAML policy is not already on the Service client policy sets and bindings page for JaxWSServicesSamples, 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 your appropriate SAML policy for the web services client.

      2. Attach the Saml Bearer Client sample general binding to the client.

        1. Select the web services client resource again.

        2. Click Assign Binding.

        3. Select Saml Bearer Client sample.

    3. Configure the web services client bindings.

      Configure the STS endpoint URL in the sample binding.

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

      2. Click either gen_saml11token or gen_saml20token in the Authentication tokens table.

      3. Click Callback handler.

      4. Modify the stsURI property to specify the STS endpoint.

        This property is not required for the self-issuer in an intermediate server. However if the property is specified for the self-issuer in an intermediate server, it is set to www.websphere.ibm.com/SAML/Issuer/Self.

      5. Verify the following properties are set to the required values.

        If any of these properties are set to some other value, you must change the property setting to the required value.

        • The confirmationMethod property must be set to Bearer.
        • The keyType property must be set to http://docs.oasis-open.org/ws-sx/ws-trust/200512/Bearer.
        • The wstrustClientPolicy property must be set to Username WSHTTPS default.
        • The value specified for the wstrustClientBinding property must match the name of application specific binding of your trust client created in the previous steps. For example, in the previous steps, we created an application specific binding named SamlTCSample. In this scenario SamlTCSample must be specified as the value for the wstrustClientBinding property

      6. Optional: To change how the application server searches for the binding, we can specify the wstrustClientBindingScope property and set its 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 cannot be located, the application server uses the default bindings.

      7. Optional: To modify the default trust client SOAP version, which is the same as the application client, specify a new value for the wstrustClientSoapVersion custom property.

        Set the wstrustClientSoapVersion custom property to 1.1 to change to SOAP v1.1.

        Set the wstrustClientSoapVersion custom property to 1.2 to change to SOAP v1.2.

      8. Click Apply and then click Save.

      If further modifications to the wstrustClientBinding configuration are needed, and the wstrustClientBinding property is pointing to an application-specific binding, for example in this case, SamlTCSample, 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.

      Before proceeding to the next step, verify the SSL certificate from the external STS exists in the NodeDefaultTrustStore. See the Before beginning section for more information.

    4. Restart the web services client application so the policy set attachment modifications can take effect.

      The policy set and binding attachment information are updated when the application restarts, but the updated information in the general binding is not reflected at run time until all the general bindings are refreshed.

      The application must be restarted after the general bindings are reloaded to take advantage of any updates. Refer to the Reload the Client and Provider general bindings and restart the applications step that follows for more information.

    5. Attach the SAML policy set and bindings to the provider application.

      1. Attach the appropriate SAML policy set to the web services provider.

        1. In the dmgr console, click Applications > Application types > WebSphere enterprise applications > JaxWSServicesSamples > Service provider policy sets and bindings.

        2. Select the web services provider resource (JaxWSServicesSamples).

        3. Click Attach Policy Set.

        4. Select the appropriate SAML policy for the web services provider.

      2. Assign the Saml Bearer Provider sample general binding.

        1. Select the web services provider resource again.

        2. Click Assign Binding.

        3. Select Saml Bearer Provider sample.

    6. Configure the web services provider bindings.

      1. If the web services provider bindings are not already on the service provider policy sets and bindings page for JaxWSServicesSamples, click WebSphere enterprise applications > JaxWSServicesSamples > Service provider policy sets and bindings > Saml Bearer Provider sample.

      2. Click WS-Security > Authentication and protection.
      3. In the Authentication tokens table, click either con_saml11token, or con_saml20token.

      4. Click Callback handler.

        The Callback handler page of the dmgr console is used to configure the SAML token issuer digital signature validation binding data for the external STS.

      5. Optional: Set the signatureRequired custom property to false to waive digital signature validation.

        We can set the signatureRequired custom property to false, to waive digital signature validation. However, a good security practice is to require SAML assertions to be signed, and always require issuer digital signature validation. False is the default value for this property.

      6. Optional: Set the trustAnySigner custom property to true to allow no signer certificate validation.

        The Trust Any certificate configuration setting is ignored for the purposes of SAML signature validation. This property is only valid if the signatureRequired custom property is set to true, which is the default value for that property.

      7. Complete the following actions if assertions are signed by the STS, the signatureRequired custom property is set to the default value of true, and the trustAnySigner custom property is set to the default value of false.

        • Add a certificate to the truststore for the provider that allows for the external STS signing certificate to pass the trust validation, such as the STS signing certificate itself or its root CA certificate.

        • Set the trustStorePath custom property to a value that matches the trust store file name. This value can be fully-qualified or use keywords such as ${USER_INSTALL_ROOT}.

        • Set the trustStoreType custom property to a value that matches the key store type. Supported keys store types include: jks, jceks, and pkcs12.

        • Set the trustStorePassword custom property to a value that matches the truststore password. The password is stored as a custom property and is encoded by the dmgr console.

        • Optional: Set the trustedAlias custom property to a value such as samlissuer. If this property is specified, the X.509 certificate represented by the alias is the only STS certificate that is trusted for SAML signature verification. If this custom property is not specified, the web services runtime environment uses the signing certificate inside the SAML assertions to validate the SAML signature and then verifies the certificate against the configured truststore.

      8. Optional: Configure the recipient to validate either the issuer name or the certificate SubjectDN of the issuer in the SAML assertion, or both.

        We can create a list of trusted issuer names, or a list of trusted certificate SubjectDNs, or we can create 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 lists, SAML validation fails, and an exception is issued.

        The following 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"/>
      9. Decrypt the SAML assertion.

        If the SAML assertion is encrypted by the STS, the SAML token appears in the SOAP Security header as an EncryptedAssertion element instead of an Assertion element. To decrypt the SAML assertion, configure the private key that corresponds to the public key that was used to encrypt the assertion on the STS.

        The following callback handler custom properties must be set to the value described in the following table for the recipient to decrypt the SAML assertion.
        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 private key used for SAML encryption
        keyName The name of the private key used for SAML encryption
        keyPassword The password for the key name

    7. 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 WebSphere enterprise applications > JaxWSServicesSamples > Service provider policy sets and bindings > Saml Bearer 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 SAML 1.1 tokens enter: http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1

        For SAML 2.0 tokens enter: http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0

      5. Click Apply and Save.

    8. Reload the Client and Provider general bindings and restart the applications.

      When the information in general bindings is updated, the new settings are not immediately reflected at run time. An updated general binding must be reloaded by the policy set manager in the application server before any updates will take effect. We can reload any updated policy sets and general bindings by stopping and restarting the application server or using the refresh command on the PolicySetManager MBean in wsadmin. For more information on refreshing the policy set manager, see the topic Refreshing policy set configurations using wsdamin scripting.

      To reload the Client and Provider general bindings and restart the applications, complete one of the following actions:

      • Restart the application serve, or
      • Refresh the PolicySetManager MBean, and then restart the Client and Provider web services applications.


    Results

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


    Related concepts:

    Secure installation for client signer retrieval in SSL
    Access the samples
    Communicate with STS
    Refreshing policy set configuration
    Encoding passwords in files
    Retrieving signers from a remote SSL port


    +

    Search Tips   |   Advanced Search