Authenticate web service clients with a SAML (Security Markup Assertion Language) Token

Web Services Security SAML Token Profile 1.1 defines how to use Security Assertion Markup Language (SAML) V1.1 and V2.0 assertions with the Web Services Security (WSS): SOAP Message Security V1.1 specification. Liberty supports Web Services Security SAML Token Profile 1.1 for SAML v2.0 assertion with bearer confirmation method.

About this task

Liberty supports SAML v2.0 with bearer confirmation method (<SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">). A web services client propagates a SAML token to the web services provider as a means of identifying the requester, and the web services provider can use this SAML token information to authenticate the requester.

The requirement of a SAML token is expressed as one of the supporting tokens in the WS-Security policy. You can add a SamlToken requirement as a required token in one of the supporting token assertions, including SupportingTokens, SignedSupportingTokens, SignedEncryptedSupportingTokens, and EncryptedSupportingTokens.

Procedure

  1. Configure a web services client to propagate the SAML token.

    It is required that a Saml20Token (com.ibm.websphere.security.saml2.Saml20Token) exists in the RunAs Subject. If a SamlToken policy assertion is configured, the Liberty WS-Security runtime will automatically extract the Saml20Token from the RunAs Subject, and attach a SAML assertion to the <wsse:Security> SOAP header. The following steps are required:

    1. Add wsSecuritySaml-1.1 to the featureManager in the server.xml file.
      <featureManager>
              <feature>wsSecuritySaml-1.1</feature>
      </featuremanager>
    2. The application must specify the SAML token as a supporting token (including SupportingTokens, SignedSupportingTokens, SignedEncryptedSupportingTokens, and EncryptedSupportingTokens token assertion) in the policy in the .wsdl file.
      <wsp:Policy wsu:Id="CallerHttpPolicy">
      	<sp:SupportingTokens>
      		<wsp:Policy>
      			<sp:SamlToken
      				sp:IncludeToken="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
      				<wsp:Policy>
      					<sp:WssSamlV20Token11 />
      				</wsp:Policy>
      			</sp:SamlToken>
      		</wsp:Policy>
      	</sp:SupportingTokens>
      
      </wsp:Policy>
  2. Authenticate the Web Service with a SAML token.

    When the web services provider receives the SOAP message with the SAML token, it validates the token first and then uses the SAML token attributes to complete the authentication process. The following are the steps that are involved in validating the SAML token:

    1. Add wsSecuritySaml-1.1 to the featureManager in the server.xml file.
      <featureManager>
              <feature>wsSecuritySaml-1.1</feature>
      </featuremanager>
    2. The application must specify the SAML token as a supporting token in the policy inside the .wsdl file.
    3. The following attributes in the server configuration are used when validating the token.
      <wsSecurityProvider id="default"
                ..
                ..
                <samltoken
                     wantAssertionsSigned="true"
                     clockSkew="5m"
                     timeToLive="30m"
                     requiredSubjectConfirmationMethod="bearer"
                     audienceRestrictions="https://../aud1"
                     audienceRestrictions="aud2" ..          />
                      
                      
      </wsSecurityProvider>
    • wantAssertionsSigned - Specify whether the <saml:Assertion> element in the SOAP message received by the WS-Security provider is signed.
    • clockSkew - The time difference that is allowed between systems that generated the SAML token and received the SAML token. The default is 5 minutes.
    • timeToLive - The life time of a SAML Assertion. This setting is required when the NoOnOrAfter condition is missing in the SAML assertion. The default is 30 minutes.
    • requiredSubjectConfirmationMethod - Subject confirmation method in the SAML assertion. The default is bearer.
    • audienceRestrictions - The allowed audiences of the SAML assertion. The default is all audiences allowed.

    For further details on the steps involved in authenticating, see Creating a WS-Security SAML caller configuration.


Icon that indicates the type of topic Task topic

File name: twlp_auth_saml_token.html