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.
You can configure the client and provider policy set attachments and
bindings for the SAML bearer token.
About this task
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, you must 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, you must 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.
- 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.
- 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 administrative 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.
- In the administrative console, click Applications >
Application types > WebSphere enterprise applications > JaxWSServicesSamples
> Service client policy sets and bindings.
- Select the web services client resource (JaxWSServicesSamples).
- Click Attach Client Policy Set.
- Select the policy set Username WSHTTPS default.
- Create the trust client binding.
- Select the web services client resource again (JaxWSServicesSamples).
- Click Assign Binding.
- Click New Application Specific Binding to
create an application-specific binding.
- Specify a binding configuration name for the new application-specific
binding. In this example, the binding name is SamlTCSample.
- Add the SSL transport policy type to the binding,
Click Add > SSL transport and then
click OK.
- Add the WS-Security policy type to the binding, then
modify the authentication settings for the trust client.
- 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.
- Click Add > WS-Security > Authentication and protection
> request:uname_token.
- Click Apply.
- Select Callback handler
- Specify a user name and password for the web services client to
authenticate to the external STS.
- Click OK, and then click Save.
- After the binding settings are saved, return to the Service
client policy sets and bindings panel, and detach the
policy set and bindings.
- 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.
- 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, you can still use the application-specific
binding you created to access the STS with the trust client.
- Attach the SAML policy set and bindings to the client application
- Attach the desired SAML policy set to the web services
client application.
- 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
- Select the web services client resource.
- Click Attach Client Policy Set.
- Select your appropriate SAML policy for the web services client.
- Attach the Saml Bearer Client sample general binding
to the client.
- Select the web services client resource again.
- Click Assign Binding.
- Select Saml Bearer Client sample.
- Configure the web services client
bindings.
Configure the STS endpoint URL in the sample
binding.
- Click Applications > Application types >
WebSphere enterprise applications > JaxWSServicesSamples > Service
client policy sets and bindings > Saml Bearer Client sample > WS-Security
> Authentication and protection.
- Click either gen_saml11token or gen_saml20token in
the Authentication tokens table.
- Click Callback handler.
- 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.
- Verify that 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
- Optional: If you want to change how the
application server searches for the binding, you 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 that contains general
binding documents.
When the value is set to application, the
application server searches for the wstrustClientBinding at the file
system location that contains 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.
- Optional: If you want 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 Version 1.1.
Set the wstrustClientSoapVersion
custom property to 1.2 to change to SOAP Version 1.2.
- 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,
you must attach the application-specific binding to the web services
client before you can complete the modifications. The attachment is
temporary. As detailed in the previous steps, you can detach the modified
application-specific binding from the web service client after the
modification is completed.
Before proceeding to the next step,
verify that the SSL certificate from the external STS exists in the
NodeDefaultTrustStore. See the Before you begin section for more
information.
- Restart the web services client application so that 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.
- Attach the SAML policy set and bindings to the provider
application.
- Attach the appropriate SAML policy set to the web services
provider.
- In the administrative console, click Applications >
Application types > WebSphere enterprise applications > JaxWSServicesSamples
> Service provider policy sets and bindings.
- Select the web services provider resource (JaxWSServicesSamples).
- Click Attach Policy Set.
- Select the appropriate SAML policy for the web services provider.
- Assign the Saml Bearer Provider sample general binding.
- Select the web services provider resource again.
- Click Assign Binding.
- Select Saml Bearer Provider sample.
- Configure the web services provider bindings.
- 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.
- Click WS-Security > Authentication and protection.
- In the Authentication tokens table, click either con_saml11token,
or con_saml20token.
- Click Callback handler.
The
Callback handler page of the administrative console is used to configure
the SAML token issuer digital signature validation binding data for
the external STS.
- Optional: Set the signatureRequired custom
property to false if you want to waive digital
signature validation.
You can set the signatureRequired
custom property to false, if you want 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.
- Optional: Set the trustAnySigner
custom property to true if you want 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.
- 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 administrative 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.
- Optional: Configure the recipient
to validate either the issuer name or the certificate SubjectDN of
the issuer in the SAML assertion, or both.
You can create
a list of trusted issuer names, or a list of trusted certificate SubjectDNs,
or you 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"/>
- 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, you must
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 |
- Optional: You 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.
- Click .
- Click New to create the caller
configuration
- Specify a Name, such as caller.
- 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.1For
SAML 2.0 tokens enter:
http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV2.0
- Click Apply and Save.
- 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.
You 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
When you have completed 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.