Configure the client and provider policy set attachments
and bindings for the SAML holder-of-key token. This configuration
scenario uses a symmetric key.
Before you begin
This function is enabled in WebSphere® Application Server Version 7.0.0.7
and later releases. To use the function, you must first install WebSphere Application Server Version 7.0.0.7
with SAML. After installing Version 7.0.0.7, you must create one
or more new server profiles, or add SAML configuration settings to
an existing profile. For example, in a WebSphere Application Server, Network Deployment environment,
there are multiple profiles. Read about setting up the SAML configuration
for more information.
About this task
WebSphere Application Server with
SAML provides
numerous default SAML token application policy sets and several general
client and provider binding samples. Before you 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 Version 2.0 token type, while the SAML11 HoK Symmetric WSSecurity
default policy set supports the Version 1.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, you must 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.
Procedure
- Import two default policy sets: SAML20 HoK Symmetric WSSecurity
default, and the Username WSHTTPS default.
- Click Services > Policy sets > Application
policy sets.
- Click Import.
- Select From Default Repository.
- Select the two default policy sets.
- Click OK to import the policy
sets.
If you do not want the server to automatically request
a SAML token from the STS using the WS-Trust client, you can skip
steps 2, 3, and 4, and continue to step 5. For example, you can skip
steps 2, 3, and 4, if Web services acts 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.
- 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. You can skip these steps,
and go to the step that discusses configuring communication with the
STS, if you use a general binding to access the external STS.
- Select the check box for the Web services client resource.
- Click Attach Client Policy Set.
- 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 you to use the
administrative console to create or to modify the client binding document.
- Configure the trust client binding.
- Select the Web services client resource again.
- In the Service client policy sets and bindings panel,
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. Optionally, you can modify the NodeDefaultSSLSettings
settings. Click Security > SSL certificate and key management
> SSL configurations > NodeDefaultSSLSettings.
- Add the WS-Security policy
type to the binding, then modify the authentication settings.
- Click Applications > Application types >
WebSphere enterprise applications > JaxWSServicesSamples >
Service client policy sets and bindings > SamlTCSample >
Add > WS-Security > Authentication and protection > request:uname_token.
- Click Apply.
- Select Callback handler.
- Specify a user name and password (and confirm the password)
to authenticate the Web services client to the external STS.
- Click OK and Save.
- After the binding settings are
saved, return to the Service client policy sets and bindings panel
to detach the policy set and bindings.
- Click Applications > Application types >
WebSphere enterprise applications > JaxWSServicesSamples >
Service client policy sets and bindings.
- Click the check box for the Web services client resource.
- 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 you can still use the application-specific
binding you created to access the STS.
- 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 for Version 7.0 applications
topic.
- Attach the SAML20 HoK Symmetric WSSecurity default policy
set and assign the Saml HoK Symmetric Client sample binding to the
client resource.
- 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 the policy set, SAML20 HoK Symmetric
WSSecurity default.
- Select the Web services client resource again.
- In the Service client policy sets and bindings panel,
click Assign Binding.
- Select the Saml HoK Symmetric Client sample general
binding.
- Click Save.
- Configure the STS endpoint URL and the user name and password
to authenticate to the STS.
- Click Applications > Application types >
WebSphere enterprise applications > JaxWSServicesSamples >
Service client policy sets and bindings > Saml HoK Symmetric Client
sample > WS-Security > Authentication and protection.
- Click gen_saml20token in the
Protection tokens table.
- Click Callback handler.
- Modify the stsURI property and
specify the STS endpoint.
- If necessary, modify the wstrustClientPolicy property
and change the value to Username WSHTTPS default.
- 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. You can skip
this step if you do not want the server to automatically request a
SAML token from the STS using the WS-Trust client.
- 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 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
can not be located, the application server uses the default bindings.
- Optional: You 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 Version 1.1, or set
the property to the value 1.2 to change to SOAP Version
1.2.
- Click Apply and Save.
- Optional: If further modifications
to the wstrustClientBinding configuration are needed, and the wstrustClientBinding
property is pointing to an application-specific binding, 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.
- Import the SSL certificate from the
external STS.
- Click Security > SSL certificate and key
management > Manage endpoint security configurations > server_or_node_endpoint >
Keystores and certificates > NodeDefaultTrustStore > Signer certificates.
- Click Retrieve from port.
- Specify the host name and port number of the external
STS server, and assign an alias to the certificate. Use
the SSL STS port.
- Click Retrieve signer information.
- Click Apply and Save to
copy the retrieved certificate to the NodeDefaultTrustStore object.
- Restart the Web services client
application so that the policy set attachment modifications can take
effect.
- Attach the SAML20 HoK Symmetric WSSecurity default policy
set to the Web services provider.
- 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 for Version 7.0 applications
topic.
- Assign the Saml HoK Symmetric Provider sample general
binding.
- Click Applications > Application types >
WebSphere enterprise applications > JaxWSServicesSamples >
Service provider policy sets and bindings > Saml HoK Symmetric
Provider sample > WS-Security > Authentication and protection.
- Click con_saml20token in the
Authentication tokens table.
- Click the Callback handler link.
- 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.
- 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:
- Verify that the Keystore name field has
the value custom.
- Click Custom keystore configuration to
view and edit the keystore configuration.
- Verify that 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 |
- 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.
- Set the custom property trustStoreType to
match the keystore type. Supported keystore types include: jks, jceks,
and pkcs12.
- 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 WebSphere Application Server Version 7.0.0.7
is installed, so you must create the file.
- Set the custom property trustStorePassword to
the encoded value of the store password. The password is
stored as a custom property, so the administrative console does not
encode the password. You can use the PropFilePasswordEncoder utility
to encode passwords that are stored in a property file.
The trustStorePassword, keyStorePassword, and
keyPassword custom properties are automatically encoded when you save
the configuration changes to the master configuration. You can still
use the PropFilePasswordEncoder utility to manually encode passwords
that exist in other property files.
For example:
- Create a property file, myPassword.properties.
The property file contains the following property: myPassword=abcdef.
- Run the following command to encode the password:
PropFilePasswordEncoder myPassword.properties myPassword
The
output of the command is: myPassword={xor}Pj08Ozo5.
- Now you can copy and paste the encoded password as the correct
value of the trustStorePassword custom property.
For more information about the PropFilePasswordEncoder
utility, read about encoding passwords in files.
- Optional: You 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.
- Optional: You 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.
- Optional: You 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.
- Optional: You can configure the recipient
to validate either the issuer name or the certificate SubjectDN of
the issuer in the SAML assertion, or you 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"/>
- Click Apply and Save.
- 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 Applications > Application types >
WebSphere enterprise applications > JaxWSServicesSamples >
Service provider policy sets and bindings > Saml HoK Symmetric
Provider sample > WS-Security > Callers.
- 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 is the local part of the CustomToken element in the attached
WS-Security policy.
- Click Apply and Save.
- Restart the Web services provider application so that the
policy set attachment modifications can take effect.
Results
When you have completed 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.