WebSphere® Application Server supports
two policy set caller binding configuration options to establish client
security context using SAML security tokens in web services SOAP request
messages. The two configuration options are mapping SAML tokens to
a user entry in a local user repository and, asserting SAML tokens
based on a trust relationship.
Before you begin
This task assumes that you are familiar with
WebSphere Application Server SAML technology.
About this task
This task describes setting the
WebSphere Application Server policy set caller
binding configuration option to establish client security context
using SAML security tokens in web services SOAP request messages.
You can either map SAML tokens to a user entry in a local user repository
or assert SAML tokens based on a trust relationship. The second configuration
option does not require accessing the local user repository. Instead,
the WS-Security runtime environment populates the client security
context entirely using the contents of SAML security tokens. This
process is based on a trust relationship to the SAML token issuer.
If a SAML tokens specifies the sender-vouches subject confirmation
method. the process is based on a trust relationship to the message
sender.
Procedure
- Configure a policy set caller binding and select the SAML
token type to represent a web services client request.
- Click .
- Click New to create the caller
configuration.
- Specify a Name, such as caller.
- 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 must match the local part of the CustomToken element
in the attached WS-Security policy.
- Click Apply and Save.
- Optional: Map SAML security tokens to a user
entry in a local user repository. Mapping to a user entry
is the default behavior when you configure a caller binding without
specifying a configuration option. Alternatively and optionally, you
can select this configuration option explicitly using the following
steps:
- On the caller binding configuration page, add a Callback
handler: com.ibm.websphere.wssecurity.callbackhandler.SAMLIdAssertionCallbackHandler.
- Add a Callback handler custom property, crossDomainIdAssertion,
and set its value to false.
- Optional: Assert SAML security tokens based
on trust relationship.
- On the caller binding configuration page, add a Callback
handler: com.ibm.websphere.wssecurity.callbackhandler.SAMLIdAssertionCallbackHandler.
- Add a Callback handler custom property, crossDomainIdAssertion,
and set its value to true.
In WebSphere Application Server Version
7.0 Fix Pack 7 and later releases, the WS-Security runtime environment
takes a SAML token Issuer name to represent the foreign security realm
name. WS-Security takes the NameID element in the
case of SAML 2.0 security tokens or the NameIdentifier element
in the case of SAML 1.1 security tokens to represent user security
name. Alternatively, you can explicitly specify which SAML token attribute
to use to represent user security name. Moreover, you can also specify
which SAML token attribute to use to represent user group membership.
Read about SAML assertions across WebSphere Application Server security domains
for a detailed discussion of the SAML token assertion trust model
and binding configuration.Version 8.x can propagate the contents
of com.ibm.websphere.security.cred.WSCredential in
a SAML token. You must set a tokenRequest custom
property with an issueByWSCredential property value
in the WS-Security binding configuration of the web services client.
Read about propagating SAML tokens for a detailed description of
this binding option. When the crossDomainIdAssertion property
is set to true in Version 8.x, WS-Security
checks whether a SAML token contains a SAML Attribute UniqueSecurityName with
a NameFormat element with a value of com.ibm.websphere.security.cred.WSCredential.
If found, WS-Security uses the NameQualifier attribute
value of the NameID element or NameIdentifier element
to represent the user security realm name. WS-Security also uses the UniqueSecurityName attribute
value and the GroupIds attribute value to represent
a unique user name and group membership. This default behavior is
different between Version 7 and Version 8.x of the product. You can
add a CallbackHandler property, IssuerNameForRealm,
and set its value to true to configure Version
8.x to preserve the Version 7 behavior. Alternatively, you can add
a CallbackHandler property, NameQualifierForRealm,
and set its value to true to configure Version
8.x to always use the NameQualifier attribute to
represent the user security realm name.
Results
You have configured a web service to establish a client security
context using the SAML security token in the web services SOAP request
messages.
Example
The following example illustrates the
NameIdentifier and
Attribute elements
from a self-issued SAML 1.1 assertion based on
WSCredential:
<saml:AttributeStatement>
<saml:Subject>
<saml:NameIdentifier NameQualifier="ldap.example.com:9080">uid=alice,dc=example,dc=com</saml:NameIdentifier>
<saml:SubjectConfirmation>
<saml:ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:bearer</saml:ConfirmationMethod>
</saml:SubjectConfirmation>
</saml:Subject>
<saml:Attribute AttributeName="UniqueSecurityName" AttributeNamespace="com.ibm.websphere.security.cred.WSCredential">
<saml:AttributeValue>uid=alice,dc=example,dc=com</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute AttributeName="GroupIds" AttributeNamespace="com.ibm.websphere.security.cred.WSCredential">
<saml:AttributeValue>cn=development,dc=example,dc=com</saml:AttributeValue>
<saml:AttributeValue>cn=deployment,dc=example,dc=com</saml:AttributeValue>
<saml:AttributeValue>cn=test,dc=example,dc=com</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
The following example
illustrates the
NameID and
Attribute elements
from a self-issued SAML 2.0 assertion based on
WSCredential:
<saml2:AttributeStatement>
<saml2:Attribute Name="UniqueSecurityName" NameFormat="com.ibm.websphere.security.cred.WSCredential" />
<saml2:AttributeValue>uid=alice,dc=example,dc=com</saml2:AttributeValue>
<saml2:Attribute>
<saml2:Attribute AttributeName="GroupIds" NameFormat="com.ibm.websphere.security.cred.WSCredential" />
<saml2:AttributeValue>cn=development,dc=example,dc=com</saml2:AttributeValue>
<saml2:AttributeValue>cn=deployment,dc=example,dc=com</saml2:AttributeValue>
<saml2:AttributeValue>cn=test,dc=example,dc=com</saml2:AttributeValue>
</saml2:Attribute>
<saml2:AttributeStatement>
<saml2:NameID NameQualifier="ldap.example.com:9060">alice</saml2:NameID>