10 Configuring Authentication

This chapter describes how to configure authentication. OWSM provides security policies that provide authentication only, and authentication with message protection.

For a summary of the authentication policies available in the current release, see "Authentication Only Policies" and "Message Protection and Authentication Policies" in Chapter 3, "Determining Which Predefined Policies to Use." For more information on authentication, see "Understanding Authentication" in Understanding Oracle Web Services Manager.

This chapter includes the following sections:

• Overview of Authentication Configuration

• Configuring an Authentication Provider in WebLogic Server

• Configuring Digest Authentication

• Configuring SAML

• Propagating Identity Context with OWSM

• Configuring Kerberos Tokens

• Configuring WS-Trust

10.1 Overview of Authentication Configuration

Authentication means verifying that the user is who they claim to be. A user's identity is verified based on the credentials presented by that user, such as username/password, digital certificate, standard Security Assertion Markup Language (SAML) token, or Kerberos token.

Both SAML and Kerberos policies require some configuration on both the service and the client side. In addition to policies, SAML and Kerberos have associated login modules. These modules, which are typically configured through Fusion Middleware Control, control access to the web service.

In SAML tokens, user attributes, user roles, and issuer name can be added to verify against the policy. These attributes are verified by the Oracle Platform Security Services (OPSS). For more information, see "Configuring SAML".

In Kerberos, you initialize and configure a Key Distribution Center (KDC) for use by the web service client and web service. You create principals in the KDC user registry and configure the service and the client to use the correct KDC. "Configuring Kerberos Tokens".

For a list of all of the policies that pertain to authentication, see "Authentication Only Policies", "Message Protection and Authentication Policies", and "WS-Trust Policies".

10.2 Configuring an Authentication Provider in WebLogic Server

Policies that use any of the supported token types—including username, X.509, Kerberos, SAML, HTTP BASIC, and so forth—require you to configure an authentication provider, such as the WebLogic Default Authentication provider, in WebLogic Server. For configuration details, see "Configuring Authentication Providers" in Administering Security for Oracle WebLogic Server.

For a list of the authentication policies available in the current release, see "Authentication Only Policies" and "Message Protection and Authentication Policies" in Chapter 3, "Determining Which Predefined Policies to Use."

For details about WebLogic Server security, see the following documents:

• Administering Security for Oracle WebLogic Server

• Oracle WebLogic Server Administration Console Online Help

You can configure any of the following WebLogic Server Authentication providers for use with OWSM, regardless of the token type used in the OWSM policy:

• The WebLogic Authentication provider, also known as the DefaultAuthenticator.

• Oracle Internet DirectoryAuthenticator or Oracle Virtual Directory Authenticator.

• LDAP Authenticator or Open LDAP Authenticator.

• RDBMS Authentication providers.

Note:

If you use an RDBMS authentication provider, or any other non-LDAP-based provider, there is a limitation that you cannot specify custom attributes to be added to the SAML assertion that OWSM generates. This limitation does not exist for any of the LDAP-based providers.

With OWSM, you do not need to configure a WebLogic Server provider for specific token types, such as SAML, Kerberos, and X.509 tokens. Specifically, the OWSM runtime does not use any other WebLogic Server providers, including but not limited to:

• X509 providers—OWSM policies based on an X509 token do not use the WebLogic Server X509 Identity Assertion provider.

• SAML providers—OWSM policies based on a SAML token do not use the WebLogic Server SAML providers.

• Credential Mapper providers

• Authorization providers

• Role Mapper providers

• Certification Path provider

• Auditing provider

10.3 Configuring Digest Authentication

As described in "Digest Authentication" in Understanding Oracle Web Services Manager, digest authentication is an authentication mechanism in which a Web application authenticates itself to a web service by sending the server a digest, which is a cryptographic hash of the password, nonce, and timestamp.

OWSM supports digest based authentication for all of the username-token authentication policies.

10.3.1 Prerequisites for Configuring Digest Authentication

The host system on which the web service is deployed must be a WebLogic Server system configured with the embedded LDAP authentication provider (Default Authenticator). This is because the web service client sends a password in the form of a digest and, in order to authenticate it at the service side, the authentication provider must recreate the digest using the clear-text password, the nonce, and timestamp. The Default Authenticator is able to get the password in the required clear text.

There is no limitation for the digest-based client policies. The web service client to which they are attached can be run from all supported platforms.

10.3.2 Configure the Default Authenticator and Identity Asserter

Perform the following steps from the WebLogic Server Administration Console to configure the Default Authenticator and Default Identity Asserter for the security realm:

1. Set the Enable Password Digests checkbox on the provider-specific page of the Default Authenticator. See Configure Authentication and Identity Assertion providers for more information.

2. Set wsse:PasswordDigest as an active type on the common page of the DefaultIdentityAsserter, as shown in Figure 10-1. See Configure Authentication and Identity Assertion providers for more information.

   Figure 10-1 wsee:PasswordDigest as Active Type

   
   Description of "Figure 10-1 wsee:PasswordDigest as Active Type"
   
   

3. Restart WebLogic Server.

4. Users created after you configure digest authentication can be authenticated using the digest based mechanism.

   However, users created before you configure digest authentication cannot be authenticated using the digest based mechanism because the WebLogic Server security runtime has already stored the password digests (rather than cleartext passwords) for the already-created users.

   You must recreate these users so that their cleartext password, and not their digest, is stored in the password database.

10.3.3 Attach a Policy and Enable Digest Authentication

To attach a policy and enable digest authentication, perform the following steps:

1. If you have not already done so, attach a copy of one of the web service policies that support digest authentication. See Chapter 4, "Attaching Policies" for information about how to copy and attach a policy.

2. Open the policy and change the Password Type drop-down menu to Digest, as shown in Figure 10-2.

   Figure 10-2 Selecting Digest From the Password Type Drop-Down Menu

   
   Description of "Figure 10-2 Selecting Digest From the Password Type Drop-Down Menu"
   
   

3. Set the Creation Time Required control.

4. Set the Nonce Required control.

5. Repeat steps one through four for the client version of the policy.

Note:

You must select Digest as the password type and set both the Creation Time Required and Nonce Required controls for the policy to be valid.

10.4 Configuring SAML

The SAML standard defines a common XML framework for creating, requesting, and exchanging security assertions between software entities on the Web. The SAML Token profile is part of the core set of WS-Security standards, and specifies how SAML assertions can be used for web services security. SAML also provides a standard way to represent a security token that can be passed across the multiple steps of a business process or transaction, from browser to portal to networks of web services.

The predefined SAML policies include saml in their name and are listed in Chapter 17, "Predefined Policies".

Note:

You cannot edit the predefined SAML policies. To modify any of the settings or configuration properties, you must either clone the policy to edit it, or set the configuration properties using a configuration override after attaching the policy.

The following sections provide more information about SAML configuration:

• How the SAML Token is Validated

• How to Configure SAML Web Service Client at Design Time

• Including User Attributes in the Assertion

• Including User Roles in the Assertion

• How to Configure Oracle Platform Security Services (OPSS) for SAML Policies

• Adding an Additional SAML Assertion Issuer Name

• Configuring SAML Web Service Clients for Identity Switching

• Defining Trusted Issuers and Trusted Distinguished Names List for SAML Signing Certificates

• Using Anonymous Users with SAML Policies

10.4.1 How the SAML Token is Validated

The SAML login module verifies the SAML tokens on behalf of the web service. The SAML login module then extracts the username from the verified token and (indirectly) passes it to Oracle Platform Security Services (OPSS) to complete the authentication.

Depending on the types of SAML assertions and the mechanisms used to protect the messages, one or more of the following steps are used to validate a SAML assertion:

1. Verify the signature on the SAML assertion:

   1. Obtain the signing certificate included or referenced in the signature for the SAML assertion.

   2. Verify the certificate is trusted against the certificate chain present in the key store.

   3. Verify the SAML assertion signature with the public key in the signing certificate.

2. Validate the SAML assertion conditions:

   • Not before and not after.

   • SAML audience restriction.

3. Validate the trust for the SAML assertion issuer:

   1. Validate if the issuer is trusted.

   2. Validate if the DN of the signing certificate is trusted.

   3. Token attribute rule.

4. Authenticate the user in the SAML assertion.

Note:

Typically, the entire message is signed and encrypted. Consider for example the oracle/wss10_saml_token_with_message_protection_client_policy. By default, when using this policy the entire message is signed and encrypted. However, as described in Section 7.5, "Configuring Partial Encryption with Fusion Middleware Control", the assertion templates support partial signing and encryption as well as full signing and encryption of the message body.

If you do not sign or encrypt any part of the message body, then only the SAML token is signed.

In the previous example of the oracle/wss10_saml_token_with_message_protection_client_policy policy, for SAML sender vouches the SAML token is signed by the client's private certificate.

Table 10-1 lists combinations of different SAML types with different security mechanisms and how a SAML assertion is validated in each case.

Table 10-1 SAML Token Validation

Use Case	Description	How Validated
SAML sender vouches with message protection.	SAML sender vouches over message protection has signing, but in this case the message body and the SAML token are signed together in one signature with the client's private certificate.	Steps: 1-4
SAML sender vouches with 2-way-SSL. For example, oracle/wss_saml20_token_over_ssl_service_policy	Message protection is via SSL only. The SAML token is signed by the client's private certificate.	Steps: 1b. Validate that the client SSL certificate is trusted. 2, 3, 4
SAML sender vouches with no security. For example, oracle/wss10_saml20_token_service_policy	This policy is not secure and is provided for demonstration purposes only. Although the SAML issuer name is present, the SAML token is not signed. The credentials in the SAML 2.0 token are authenticated against a SAML 2.0 login module.	Steps: 2, 3a, 4
SAML token bearer with 1-way-SSL. For example, oracle/wss_saml20_token_bearer_over_ssl_service_policy	In the case of SAML bearer, the SAML tokens are signed and the signature is present inside the SAML token. This is independent of whether the body is signed.	Steps: 1, 2, 3, 4
SAML unsigned token bearer with 1-way-SSL. (Disabled by default, but can be turned on for backward compatibility.)	The SAML token is not signed.	Steps: 2, 3, 4
SAML holder of key with message protection. The entire body is signed with the HOK.	The SAML tokens are signed and the signature is present inside the SAML token. The body is also signed with the HOK.	Steps: 1, 2, 3, 4 Additional step 5. Validate that the sender has the secret key by verifying the signature with the key.
SAML holder of key with timestamp signing only. The message body is not signed.	The SAML tokens are signed and the signature is present inside the SAML token. The timestamp is also signed with the HOK.	Steps: 1, 2,3,4 Additional step 5. Validate that the sender has the secret key by verifying the signature with the key.

10.4.1.1 Which Authentication Provider is Used?

Any configured Authentication provider as described in "Configuring an Authentication Provider in WebLogic Server" can then be invoked.

10.4.2 How to Configure SAML Web Service Client at Design Time

Follow the steps described in this section to configure the SAML web service client at design time. (If you attach the SAML policies to the web service client at deploy time, you do not need to configure these properties and they are not exposed in Fusion Middleware Control.)

You can also include user roles in the assertion and change the SAML assertion issuer name, as described in subsequent sections.

10.4.2.1 Configure the Username for the SAML Assertion

For a JSE client application, configure the username as a BindingProvider property:

Map<String,Object>  reqContext = ((BindingProvider) proxy).getRequestContext()   reqContext.put( BindingProvider.USERNAME_PROPERTY, "jdoe")

where proxy refers to the web service proxy used for invoking the actual web service.

For a Java EE client, if the user is already authenticated and a subject is established in the container, then the username is obtained from the subject automatically and no additional configuration is required.

For example, if user jdoe is already authenticated to the Java EE application and you are making a web service call from that Java EE application, the username jdoe will be automatically propagated.

However, if the user is not authenticated, then you need to configure the username in the BindingProvider as in the JSE case.

10.4.3 Including User Attributes in the Assertion

SAML client policies include the user.attributes configuration property that you can use to add user attributes to the SAML assertion.

To do this, you specify the attributes to be included as a comma-separated list. For example, attrib1,attrib2. The attribute names you specify must exactly match valid attributes in the configured identity store.

user.attributes requires that the Subject is available and that the subject.precedence configuration property is set to true. (If subject.precedence is true, the user name to create the SAML assertion is obtained only from the Subject.)

The OWSM runtime reads the values for these attributes from the configured identity store, and then includes the attributes and their values in the SAML assertion.

The user.attributes configuration property is supported for a single identity store, and by default only the first identity store in the list is used. The user must therefore exist and be valid in the identity store used by the configured WebLogic Server Authentication provider. Authentication providers are described in "Configuring an Authentication Provider in WebLogic Server".

If you have more than one identity store configured, and you want to search for the user in all identity stores, follow these steps to enable searching in all configured identity stores.

1. In the Target Navigation pane, expand WebLogic Domain to show the domain for which you need to configure the identity store provider. Select the domain.

2. From the WebLogic Domain menu, select Security, and then Security Provider Configuration.

3. In the Identity Store Provider section of the page, click Configure to configure parameters that interact with the identity store.

   The Identity Store Configuration page is displayed, as shown in Figure 10-3.

   Figure 10-3 Identity Store Configuration Page

   
   Description of "Figure 10-3 Identity Store Configuration Page"
   
   

4. Click Add to add a custom property.

   The Add New Property window is displayed.

5. Add the property "virtualize" with a value of "true", as shown in Figure 10-4.

   Figure 10-4 Adding the virtualize property

   
   Description of "Figure 10-4 Adding the virtualize property"
   
   

6. Click OK to submit the changes.

7. Click OK on the Identity Store Configuration page.

8. Restart the server.

10.4.4 Including User Roles in the Assertion

You can pass the user's role as an attribute statement in the SAML assertion. To do this at post-deploy time, configure the user.role.include property to "true." The default value in the policy is "false."

To configure the user's role at design time, set the user.role.include property to "true" in the BindingProvider.

10.4.5 How to Configure Oracle Platform Security Services (OPSS) for SAML Policies

Follow these steps to configure OPSS for the predefined SAML policies:

1. Configure the SAML login module, as described in "Configuring the SAML and SAML2 Login Modules Using Fusion Middleware Control".

   By default, the SAML assertion issuer name is www.oracle.com. The saml.issuer.name client property must be www.oracle.com if you are using the predefined SAML policies (or assertions) on both the web service client and web service sides. Therefore, you can generally use the defaults and not configure any issuer.

   See "Adding an Additional SAML Assertion Issuer Name" for information on adding an additional issuer.

2. Configure the Authentication provider in the WebLogic Server Administration Console.

3. If you will be using policies that involve signatures related to SAML assertions (for example, SAML holder-of-key policies) where a key referenced by the assertion is used to sign the message, or sender-vouches policies where the sender's key is used to sign the message, you need to configure keys and certificates for signing and verification, as described in "Configuring Keystores for Message Protection".

4. If you will be using policies that require SSL, you need to configure SSL, as described in "Configuring Keystores for SSL".

10.4.6 Adding an Additional SAML Assertion Issuer Name

If you are using the predefined SAML policies (or assertions) on both the web service client and web service sides, the SAML issuer name is specified as www.oracle.com. Therefore, you can generally use the defaults and not configure any issuer.

There are three scenarios in which you need to add additional issuers to the trusted issuers list:

• You specified a trusted issuer using the saml.trusted.issuers configuration override property in a SAML predefined web service policy or assertion. Trusted issuers defined here will apply at the application level and will override trusted issuers defined at the domain level.

• You specified a SAML issuer using the saml.issuer.name configuration property in a SAML predefined web service client policy or assertion.

• If a different client, for instance .NET/STS, is talking to a web service protected by a predefined SAML policy.

The preferred method for adding SAML issuers is to use domain-level configuration, as described in the following sections:

• "Configuring SAML Trusted Issuers and DN Lists Using Fusion Middleware Control"

• LINK TO WLST Section

Note that when you add an issuer as described above, it applies to all services in the domain and a server restart is not required.

For backward compatibility, you can also add an issuer in Fusion Middleware Control by configuring the SAML or SAML2 login module in the security provider, although the preferred method is to use the domain level configuration. If you do define the SAML issuers in the SAML login module, the issuers are persisted in jps-config.xml, and you must restart the servers in the domain for the changes to take effect.

Note:

OWSM uses the following hierarchy to determine the trusted issuers to be used at runtime:

• First, the list of trusted issuers configured at the policy level is checked and used. This will override trusted issuers at the domain level.

• If no trusted issuers are defined at the policy level, the domain level configuration is checked and used.

• Lastly, if no trusted issuers are defined at either the policy or domain level, then the issuers list defined in the SAML login module is checked and used.

To add an additional SAML assertion issuer to the Issuers list in the SAML login module:

1. In the Target Navigation pane, expand WebLogic Domain to show the domain for which you need to add the issuer. Select the domain.

2. In the content pane, select WebLogic Domain, then Security, and then Security Provider Configuration.

3. In the Login Modules section, select the SAML or SAML2 login module as appropriate and click Edit.

   The Edit Login Module page is displayed.

4. In the SAML Specific Attributes section of the page, click Add.

5. In the Add Issuer window, enter the issuer name in the Issuer field and click OK.

6. Restart the server.

7. Configure the issuer in the client policy as follows:

   • Post-deployment, specify a configuration override value for the saml.issuer.name property in an attached SAML client policy. If you cloned a predefined Oracle SAML client policy, you can set the value in the saml.issuer.name configuration property before attaching the policy.

   • At design time, set the saml.issuer.name property in the BindingProvider.

10.4.7 Configuring SAML Web Service Clients for Identity Switching

OWSM includes the wss11_saml_token_identity_switch_with_message_protection_client_policy policy that enables identity switching. Identity switching means that the policy propagates a different identity than the one based on the authenticated Subject.

You might have a scenario in which your SOA application needs to specify which user identity to use in client-side web service policies, and then dynamically switch the user associated with the SAML token in the outbound web service request. Instead of using the username from the Subject, this policy allows you to set a new user name when sending the SAML web service request.

The wss11_saml_token_identity_switch_with_message_protection_client_policy policy creates the SAML token based on the user ID set via the property javax.xml.ws.security.auth.username.

Consider the following use case in which a web service client calls a SOA application, which in turn becomes the client for a web service.

client -> SOA -> web service

In this use case:

• The client is secured with the wss11_username_with_message_protection_client_policy policy. It communicates with the SOA entry point as user end_user1.

• The SOA entry point is protected by wss11_username_with_message_protection_service_policy. The SOA application authenticates the end user and establishes the Subject based on end_user1. However, it wants to propagate a different identity to the external web service.

  Therefore, to do identity switching, attach the wss11_saml_identity_switch_message_protection_client_policy policy to the SOA reference binding component.

• The username that is propagated is determined dynamically by the BPEL process, which is a component in the SOA application. The username is set as BPEL property javax.xml.ws.security.auth.username with the dynamically determined username value. The external web service can be protected by wss11_saml_with_message_protection_service_policy. It receives the switched user and not end_user1.

• A similar scenario can be used by a Java EE application (replacing SOA in this scenario with the Java EE application) that establishes the Subject based on an end user but then needs to propagate a different identity. In the case of Java EE, you can set the user name programmatically as follows:

  ((BindingProvider) port).getRequestContext().put(BindingProvider.USERNAME_PROPERTY, config.get(USERNAME));
  

• Use Fusion Middleware Control to add the WSIdentityPermission permission to the SOA reference binding component.

  The wss11_saml_token_identity_switch_with_message_protection_client_policy policy requires that an application to which the policy is attached must have the WSIdentityPermission permission. That is, applications from which OWSM accepts the externally-supplied identity must have the WSIdentityPermission permission.

  This is to avoid potentially rogue applications from providing an identity to OWSM.

Note:

The wss11_saml_token_identity_switch_with_message_protection_client_policy policy disables local optimization (see "Using Local Optimization with OWSM Policies (SOA Composites)" for SOA to SOA interactions on the same server.)

This policy is compatible with the wss11_saml_token_with_message_protection_service_policy policy on the web service.

10.4.7.1 Set the javax.xml.ws.security.auth.username Property

For SOA:

The SOA composite has a BPEL process as one SOA service component. A BPEL process provides process orchestration and storage of synchronous and asynchronous processes.

You can define a BPEL property with the exact name javax.xml.ws.security.auth.username. The value for this property can be the identity that the SOA application wants to propagate, which could potentially be determined dynamically by the BPEL process.

For Java EE:

Set the BindingProvider.USERNAME_PROPERTY property.

10.4.7.2 Set the WSIdentityPermission Permission

The web service client (for example, the SOA reference binding component) to which you attached the wss11_saml_token_identity_switch_with_message_protection_client_policy policy must have the oracle.wsm.security.WSIdentityPermission permission.

To use Fusion Middleware Control to add the oracle.wsm.security.WSIdentityPermission permission to the SOA reference binding component as a System Grant, perform the following steps:

1. In the Target Navigation pane, expand WebLogic Domain to show the domain for which you need to configure the application. Select the domain.

2. Using Fusion Middleware Control, click WebLogic Domain, then Security, and then System Policies. System policies are the system-wide policies applied to all applications deployed to the current WebLogic Domain.

3. From the System Policies page, select the arrow icon in the Permission field to search the system security grants.

4. Select one of the codebase permissions to use as a starting point and click Create Like.

5. In the Grant Details section of the page, enter file:${common.components.home}/modules/oracle.wsm.common_${jrf.version}/wsm-agent-core.jar in the Codebase field.

   Note:

   When defining the grant details, Oracle recommends that you avoid using product version numbers in the directory or JAR names. This will minimize impact when upgrading to a new release in the future.

6. In the Permissions section of the page, select the starting point permission class and click Edit.

7. Enter oracle.wsm.security.WSIdentityPermission in the Permission Class field. The resource name is the composite name for SOA, and the application name for a Java EE client. The action is always assert, as shown in Figure 10-5.

   Figure 10-5 Editing the WSIdentityPermission

   
   Description of "Figure 10-5 Editing the WSIdentityPermission"
   
   

To use WLST to add the oracle.wsm.security.WSIdentityPermission permission, execute the following command:

grantPermission(codeBaseURL="file:${common.components.home}/modules/
oracle.wsm.common_${jrf.version}/wsm-agent-core.jar",
     permClass="oracle.wsm.security.WSIdentityPermission",
     permTarget="resource=yourAppName",
     permActions="assert")

In this command:

• codeBaseURL must point to wsm-agent-core.jar.

• permTarget syntax is "resource=yourAppName/compositeName". The resource name is the composite name for SOA, and the application name for a Java EE client.

• permActions is always "assert".

10.4.8 Defining Trusted Issuers and Trusted Distinguished Names List for SAML Signing Certificates

For additional security, you can define a list of trusted distinguish names (DNs) for SAML signing certificates.

By default, OWSM checks the incoming issuer name against the list of configured issuers, and checks the SAML signature against the configured certificates in the OWSM keystore. If you define a trusted DNs list, OWSM also verifies that the SAML signature is signed by the particular certificate(s) that is associated with that issuer.

Configuration of the trusted DNs list is optional; it is available for users that require more fine-grained control to associate each issuer with a list of one or more signing certificates. If you do not define a list of DNs for a trusted issuer, then OWSM allows signing by any certificate, as long as that certificate is trusted by the certificates present in the OWSM keystore.

For more information about defining a trusted DNs list for SAML signing certificates, see "Configuring SAML Trusted Issuers and DN Lists Using Fusion Middleware Control".

10.4.9 Using Anonymous Users with SAML Policies

All SAML policies allow anonymous users to be propagated. For example if you have an ADF application that can work with either authenticated users or an anonymous user, and this ADF application needs to make a call to a web service and propagate the current user, then you can propagate both the authenticated users and the anonymous user using any of the SAML policies. From the security perspective, propagating the anonymous user over SAML is equivalent to the client not sending any authentication tokens to the service.

Allowing anonymous users over SAML is provided as a convenience so that you can have one policy that supports both authenticated and anonymous users. Note, however, that anonymous propagation over SAML is non-standard and will not interoperate with other vendors. It should only be used when both the client and the web service are using OWSM.

10.5 Propagating Identity Context with OWSM

Identity Context allows organizations to meet growing security threats by using the context-aware policy management and authorization capabilities built into the Oracle Access Management platform. Identity Context secures access to resources using traditional security controls (such as roles and groups) and as dynamic data established during authentication and authorization (such as authentication strength, risk levels, device trust, and so on).

For example, an application could use Identity Context to:

• Disable a particular business function if the user is not authenticated using a strong credential such as smart card.

• Secure access to a transaction based on the identity data supplied by a business partner (by using Identity Federation) with whom the organization does business.

• Request additional authentication credentials if it detects that access is originating from a location known for fraudulent activities.

• Limit the scope of administrative authority if the Administrator's industry certification (as maintained by a third party) has expired.

• Disable certain business functions if it detects that access is originating from an unknown device.

OWSM can propagate the Identity Context from the web service client to the web service, and then make it available ("publish it") to other components for authentication and authorization purposes.

The Identity Context is opaque to your web service client and web service, and you need not perform any additional coding or processing in your web service client or web service to support it once you enable Identity Context propagation for your policies.

Note:

Identity Context propagation is not supported for SOA, WebCenter, and Java EE (WebLogic) web service applications.

For more information on Identity Context, configuring the Identity Context Service, and using the Identity Context API, see "Using Identity Context" in Administrator's Guide for Oracle Access Management.

10.5.1 Using SAML Policies to Propagate Identity Context

To use this feature, you must specifically enable identity context propagation by using the propagate.identity.context configuration property for both the web service client policy and the web service policy. That is, OWSM can propagate the Identity Context only if you specifically allow both the web service client policy and web service policy to do so.

OWSM propagates the Identity Context from web service clients to web services via SAML 1.1 or SAML 2.0 assertions. Therefore, only SAML policies include the propagate.identity.context configuration property.

The OWSM policies that support identity context are listed in "Which OWSM Policies Are Supported for Identity Context?".

10.5.2 Configuring Identity Context Propagation: Main Steps

You can specify a value for propagate.identity.context on the Configurations page in the policy as described in this section, or override it when you attach the policy.

Note:

If you choose to set this property in the policy, you need to make copies (both client and server) of the desired predefined SAML policies listed in "Which OWSM Policies Are Supported for Identity Context?". For details about creating a new policy from a predefined policy, see "Cloning a Web Service Policy". Once you have created the policies, you can edit them and set the propagate.identity.context property as described in this section.

For information about overriding the propagate.identity.context property when you attach the policy, see Chapter 5, "Overriding Policy Configuration Properties."

By default, the propagate.identity.context configuration property is not set, which is equivalent to false. To use identity context propagation, you must specifically set the propagate.identity.context to true.

To configure identity propagation using a cloned policy:

1. In the Target Navigation pane, expand WebLogic Domain and select the domain for which you need to configure identity context propagation.

2. From the WebLogic Domain menu, select Web Services, then WSM Policies.

3. Select the cloned SAML policy for which you want to enable identity context propagation and click Open.

   Remember that you have to enable identity context propagation for both the web service client and web service policies.

4. Select the Assertions tab.

5. Click Configuration.

   The Configuration page displays a list of the configuration properties for the policy.

6. Enter true in the Value field for the propagate.identity.context property.

7. Click OK.

   Figure 10-6 Setting the propagate.identity.context Property to True

   
   Description of "Figure 10-6 Setting the propagate.identity.context Property to True"
   
   

8. Click Save to submit the changes.

9. Repeat Steps 3 and 8 for the corresponding client or service policy, as appropriate.

10. Attach the policy to the desired endpoints as described in Chapter 4, "Attaching Policies."

10.6 Configuring Kerberos Tokens

For information on the Kerberos authentication protocol, see "Understanding the Kerberos Protocol" in Understanding Oracle Web Services Manager.

The predefined Kerberos policies include kerberos in their name and are listed in Chapter 17, "Predefined Policies". The predefined Kerberos assertion templates include kerberos in their name and are listed in Chapter 18, "Predefined Assertion Templates".

Follow the steps described in this section to configure Kerberos for use by the web service client and web service.

• "Using MIT Kerberos"

• "Using Microsoft Active Directory with Key Distribution Center"

• "Setting the Service Principal Name In the Web Service Client"

• "Configuring the Web Service to Use the Correct KDC"

• "Using the Correct Keytab File in Enterprise Manager"

• "Authenticating the User Corresponding to the Service Principal"

• "Creating a Ticket Cache for the Web Service Client"

• "Configuring Kerberos Over SSL"

• "Configuring Kerberos With SPNEGO Negotiation"

• "Configuring Credential Delegation"

10.6.1 Using MIT Kerberos

This section describes the following tasks when using MIT Kerberos as your KDC:

• Initializing and Starting the MIT Kerberos KDC

• Creating Principals

• Configuring the Web Service Client to Use the Correct KDC

10.6.1.1 Initializing and Starting the MIT Kerberos KDC

Initialize KDC database. For example, on UNIX you might run the following command as root, where example.com is your default realm:

root# /usr/kerberos/sbin/krb5_util -r example.com -s

Start the kerberos service processes. For example, on UNIX you might run the following commands as root.:

root# /usr/kerberos/sbin/krb5kdc &
root# /usr/kerberos/sbin/kadmind &

10.6.1.2 Creating Principals

Create two accounts in the KDC user registry. The first account is for the end user; that is, the web service client principal. The second account is for the web service principal.

One way to create these accounts is with the kadmin.local tool, which is typically provided with MIT KDC distributions. For example:

>sudo su - # become root
>cd /usr/kerberos/sbin/kadmin.local
>kadmin.local>addprinc fmwadmin -pw password
>kadmin.local> addprinc SOAP/myhost.example.com -randkey
>kadmin.local>listprincs # to see the added principals

The web service principal name (SOAP/myhost.example.com) is shown in the example as being created with a random password. The web service principals use keytables (a file that stores the service principal name and key) to log into the Kerberos System. Using a random password increases security.

10.6.1.3 Configuring the Web Service Client to Use the Correct KDC

The web service client needs to be configured to authenticate against the right KDC.

The configuration for the KDC resides at /etc/krb5.conf for UNIX hosts, and at C:\windows\krb5.ini for Windows hosts.

A sample krb5.conf is shown in Example 10-1. Note the following:

• The file tells the kerberos runtime the realm of operation and the KDC endpoint to contact.

• For Kerberos token policies to work, three additional properties need to be specified in the libdefaults section of this file:

  • default_tkt_enctypes

  • default_tgs_enctypes

  • permitted_enctypes

  The order of cipher suites is significant and should comply with the algorithm suite used in the client-side Kerberos policy. For example, if the KDC-supported enc-types are des3-cbc-sha1, des-cbc-md5, des-cbc-crc, arcfour-hmac, then the following order of enc-types entries should be used in client's krb5.conf for the following policies:

  • wss11_kerberos_with_message_protection_client_policy:

    • default_tkt_enctypes = des3-cbc-sha1 des-cbc-md5 des-cbc-crc arcfour-hmac

    • default_tgs_enctypes = des3-cbc-sha1 des-cbc-md5 des-cbc-crc arcfour-hmac

    • permitted_enctypes = des3-cbc-sha1 des-cbc-md5 des-cbc-crc arcfour-hmac

  • wss11_kerberos_with_message_protection_basic128_client_policy:

    • default_tkt_enctypes = arcfour-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc

    • default_tgs_enctypes = arcfour-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc

    • permitted_enctypes = arcfour-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc

Example 10-1 Sample krb5.conf File

[logging]
default = FILE:/var/log/krb5libs.log
kdc = FILE:/var/log/krb5kdc.log
admin_server = FILE:/var/log/kadmind.log
 
[libdefaults]
default_realm = EXAMPLE.COM
dns_lookup_realm = false
dns_lookup_kdc = false
default_tkt_enctypes = des3-cbc-sha1 des-cbc-md5 des-cbc-crc arcfour-hmac
default_tgs_enctypes = des3-cbc-sha1 des-cbc-md5 des-cbc-crc arcfour-hmac
permitted_enctypes = des3-cbc-sha1 des-cbc-md5 des-cbc-crc arcfour-hmac
 
[realms]
example.com =
{kdc = someadminserver.com:88  admin_server = someadminserver.com:749   
 
 
default_domain = us.example.com  }
[domain_realm]
us.example.com = example.com
 
[kdc]
profile = /var/kerberos/krb5kdc/kdc.conf
 
[appdefaults]
pam =
{   debug = false    ticket_lifetime = 36000   renew_lifetime = 36000    
 
 
forwardable = true    krb4_convert = false  }

10.6.2 Using Microsoft Active Directory with Key Distribution Center

You can use Microsoft Active Directory with Key Distribution Center (KDC) as your KDC. This section describes how to configure the KDC through Active Directory for use with Kerberos and message protection.

This section assumes that you are already familiar with Active Directory. See your Active Directory documentation for additional details.

Note:

When using versions of Microsoft Active Directory earlier than 2008 as the KDC in message protection scenarios, do not use the following policies:

• oracle/wss11_kerberos_token_with_message_protection_client_policy

• oracle/wss11_kerberos_token_with_message_protection_service_policy

These policies use Triple DES encryption, which is not supported by earlier versions of Microsoft Active Directory.

Instead, use the Kerberos message protection policies that include "basic128" in the policy name, specifically:

• oracle/wss11_kerberos_token_with_message_protection_basic128_client_policy

• oracle/wss11_kerberos_token_with_message_protection_basic128_service_policy

These two policies are compatible with all supported versions of Microsoft Active Directory.

10.6.2.1 Setting Up the Web Service Client

This section describes the following tasks:

• Create a User Account

• Set the Service Principal Name

• Create a Keytab File

10.6.2.1.1 Create a User Account

Use Active Directory to create a new user account. Do not use DES encryption. By default, the user account is created with RC4-HMAC.

For example, you might create a user testpol with the user logon name test/testpol.

The user logon name should be of the form group/name.

10.6.2.1.2 Set the Service Principal Name

Use setSpn to map the Service Principal Name to the user:

setSpn -A test/testpol testpol
setSpn -L testpol (this should display the availabel mapping)

There should be only one Service Principal Name mapped to the user. If there are multiple Service Principal Names mapped to the user, remove them using setSpn -D <spname> <username>.

10.6.2.1.3 Create a Keytab File

Use ktpass to create a keytab file:

ktpass -princ test/testpol@{domain} -pass {...}  -mapuser testpol -out
 testpol.keytab -ptype KRB5_NT_PRINCIPAL  -target {domain}

where test/testpol is the Service Principal Name and it is mapped to the user testpol. Do not set /desonly or crypto as des-cbc-crc.

10.6.2.2 Set Up the Web Service

Perform the following steps to set up the web service:

1. Attach the Kerberos policy to your web service.

2. Configure the web service client to authenticate against the right KDC.

   The configuration for the KDC resides at /etc/krb5.conf for UNIX hosts, and at C:\windows\krb5.ini for Windows hosts.

   Configure the default domain and realm in the krb5.conf or krb5.ini file. Enable the RC4-HMAC encryption type (available in JDK6).

   [libdefaults]
    
   default_tkt_enctypes = rc4-hmac
   default_tgs_enctypes = rc4-hmac
   permitted_enctypes = rc4-hmac
   

3. Export the keytab file you created in "Create a Keytab File" to the system where the web service is hosted. The keytab is a binary file; if you ftp it, use binary mode.

4. Verify the keytab file using kinit:

   kinit -k -t <absolute path the the keytab file> <Service Principal Name> 
   

5. Modify the krb5 login module as described in "Configuring the Kerberos Login Module" to specify the keytab location and the Service Principal Name.

   Use the absolute path to the keytab file. Also, be sure to add @realmname to the Service Principal Name. For example:

   principal value=test/[e-mail]
   

10.6.3 Setting the Service Principal Name In the Web Service Client

The web service client that is enforcing Kerberos client-side policies needs to know the service principal name of the service it is trying to access.

You can specify a value for service.principal.name on the Configurations page, or override it on a per-client basis using the Security Configuration Details control when you attach the policy. The default (place holder) value is HOST/[e-mail].

Alternatively, you can specify the service principal name at design time by using a configuration override; for example:

JAX-WS Clients: 
((BindingProvider)port).getRequestContext().put(SecurityConstants.ClientConstants.WSS_KERBEROS_SERVICE_PRINCIPAL, 
SOAP/[e-mail]);

10.6.4 Configuring the Web Service to Use the Correct KDC

Configure the web service to authenticate against the correct KDC. The configuration for the KDC resides at /etc/krb5.conf for UNIX hosts, and at C:\windows\krb5.ini for Windows hosts.

A sample KDC configuration for a web service client is shown in Example 10-1. This example also applies to the web service KDC configuration.

10.6.5 Using the Correct Keytab File in Enterprise Manager

To use the correct keytab file, you

• Extract and install the keytab File

• Modify the krb5 login module

These tasks are described in the sections that follow.

10.6.5.1 Extract and Export the Keytab File

Extract the key table file, which is often referred to as the keytab, for the service principal account from the KDC and install on the machine where the web service implementation is hosted.

For example. you can use a tool such as kadmin.local to extract the keytab for the service principal name, as follows:

>kadmin.local>ktadd -k /tmp/krb5.keytab SOAP/myhost.example.com

Export the keytab file to the machine where the web service is hosted. The keytab is a binary file; if you ftp it, use binary mode.

10.6.5.2 Modify the krb5 Login Module to use the Keytab File

Modify the krb5 login module as described in "Configuring the Kerberos Login Module" to identify the location of the web service KDC file.

For example, assume that the keytab file is installed at /scratch/myhome/krb5.keytab. Note the changes for the keytab and principal properties:

• principal value=SOAP/[e-mail]

• useKeyTab value=true

• storeKey value=true

• keyTab value=/scratch/myhome/krb5.keytab

• doNotPrompt value=true

10.6.6 Authenticating the User Corresponding to the Service Principal

The web services runtime must be able to verify the validity of the kerberos token.

If the token is valid, Oracle Platform Security Services (OPSS) must then be able to authenticate the user corresponding to the service principal against one of the configured WebLogic Server Authentication providers. (Authentication providers are described in "Configuring an Authentication Provider in WebLogic Server".)

The user must therefore exist and be valid in the identity store used by the Authentication provider.

For example, consider a service principal such as SOAP/[e-mail]. In this example, a user with the name SOAP/myhost.example.com must exist in the identity store. Note that @domain should not be part of your user entry.

10.6.7 Creating a Ticket Cache for the Web Service Client

Perform the following steps to create a ticket cache for the web service client:

1. Log in to the Kerberos system using the user principal you created for the client.

   >kinit fmwadmin password
   

2. This creates a ticket cache on the file system with ticket granting ticket. To see this:

   >klist -e
   

   Information similar to the following is displayed:

   Credentials cache: /tmp/krb5cc_36687
   Default principal: [e-mail], 1 entry found.
   [1]  Service Principal:  krbtgt/[e-mail]
        Valid starting:  Sep 28, 2007 17:20
        Expires:         Sep 29, 2007 17:20
            Encryption type: DES3 CBC mode with SHA1-KD
   

   Make sure the encryption type reflects what is shown above.

3. Run the web service client.

Alternatively, you can run the web service client without first logging into the Kerberos. You are prompted for the Kerberos user name and password. Note that in this case a ticket cache is not created on the file system; it is maintained in memory.

10.6.8 Configuring Kerberos Over SSL

The two basic assertion templates for Kerberos, oracle/wss11_kerberos_token_client_template and oracle/wss11_kerberos_token_service_template, provide authentication using Kerberos tokens but do not provide any form of message protection.

OWSM provides the following assertion templates that add message protection using SSL transport-level security to the basic authentication using Kerberos tokens:

• oracle/wss11_kerberos_token_over_ssl_client_template

• oracle/wss11_kerberos_token_over_ssl_service_template

To use these assertion templates, you need to configure SSL, as described in "Configuring Keystores for SSL".

These assertions use the Kerberos token for authentication and for signing the timestamp, and rely on underlying One-Way SSL transport for message protection. They advertise the Kerberos token as an EndorsingSupportingToken.

10.6.9 Configuring Kerberos With SPNEGO Negotiation

SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) is a standard that enables a client and a service to negotiate a method to use for authentication. Because SPNEGO uses HTTP headers to perform the negotiation, it is especially useful in a cross-platform context such as the web.

For more information on using Kerberos with SPNEGO, see "Kerberos and SPNEGO" in Understanding Oracle Web Services Manager.

OWSM provides the following assertion templates to enable clients and services using SPNEGO negotiation to use Kerberos for authentication:

• oracle/http_spnego_token_client_template

• oracle/http_spnego_token_service_template

These assertion templates can be used by policies attached to SOAP or REST endpoints.

You can use these assertion templates to create a new policy, or to add a SPNEGO assertion to an existing multi-token policy. For more information about creating policies or adding an assertion to a policy, see the following sections:

• "Creating a New Web Service Policy"

• "Adding Assertions to a Policy"

10.6.10 Configuring Credential Delegation

Kerberos includes a feature called credential delegation to support scenarios where a client request demands that one service use a second service (on behalf of the client) to satisfy the request. To satisfy such scenarios, the client provides the first service with a forwarded TGT (ticket granting ticket) that the first service uses to obtain a service ticket for the second service from the KDC.

For more information on credential delegation, see "Credential Delegation in Kerberos" in Understanding Oracle Web Services Manager.

To configure credential delegation, you must perform these tasks:

• Configure Kerberos to allow credential delegation.

• Configure the domain where the client is deployed to allow OWSM to forward a Kerberos ticket to the service on behalf of the client.

• Enable credential delegation in the client policy and the service policy.

When using credential delegation with a service in active directory, you must also configure the service's SPN account to be trusted for delegation.

The following subsections describe these tasks.

10.6.10.1 Configuring Credential Delegation in Kerberos

To configure Kerberos to support credential delegation, you must set the forwardable option to true in the libdefaults section of the krb5.conf file; for example:

[libdefaults]
forwardable = true

10.6.10.2 Configuring Delegation Permission to OWSM

In order to delegate credentials, OWSM must have permission to forward a Kerberos ticket to the service on behalf of the client. To provide this permission, you use a grantPermission WLST command of this form:

grantPermission(
  codeBaseURL="file:${common.components.home}/modules/oracle.wsm.common_12.1.2/wsm-agent-core.jar",
  permClass="javax.security.auth.kerberos.DelegationPermission",
  permTarget="\"service_principal@REALM_NAME\" \"krbtgt/REALM_NAME@REALM_NAME\"")

In this command, service_principal is the service principal and REALM_NAME is the security realm.

Because grantPermission is an online command, you must first use the connect WLST command to connect to the WebLogic Server instance. For more information about the grantPermission command, see "grantPermission" in Infrastructure Security WLST Command Reference.

10.6.10.3 Enabling Credential Delegation in the Client Policy and the Service Policy

You enable credential delegation by setting the value of the credential.delegation configuration property to true in the Kerberos assertions for the client policy and the service policy. This property is available in all of the Kerberos assertion templates. By default, this value is false, indicating that credential delegation is disabled.

10.6.10.4 Configuring Credential Delegation for a Service in Active Directory

When using Kerberos credential delegation with a service in active directory, you must configure the service's SPN domain account to be trusted for delegation.

1. On the domain controller, start Active Directory Users and Computers.

2. In the left pane, click Users.

3. In the right pane, right-click the name of the domain account you used when creating the service's SPN, and then click Properties.

4. On the Delegation tab, select the Account is trusted for delegation option, and then click OK.

5. Quit Active Directory Users and Computers.

Note:

Java clients that use the standard JDK libraries for Kerberos ignore this setting in Active Directory due to a limitation in the JDK.

10.6.10.5 Credential Delegation Example

The following example demonstrates how to configure credential delegation using the following scenario:

A bank provides its customers a client application, MyBanker, that enables account holders to view information about their accounts. To get transaction information for an account, the MyBanker client calls the Transactions service. This service has direct access to transactions for an account since the account's last statement. To get information about older transactions, it calls the OldTransactions service. To get information from OldTransactions, Transactions must authenticate with the credentials of the MyBanker client.

Prerequisites This example requires that the MyBanker client and the Transactions and OldTransactions services all authenticate using the same Kerberos KDC.

Procedure In the following procedure, Steps 2, 3 and 4 are very similar to those that you would routinely perform when connecting clients and services using OWSM. Steps 1 and 5 are unique to credential delegation.

1. Configure the domain where MyBanker is deployed to permit OWSM to forward tickets to Transactions on behalf of MyBanker by adding a <grant> element to the system-jazn-data.xml file, as described in "Configuring Delegation Permission to OWSM".

2. Attach the appropriate Kerberos or SPNEGO service policy to the Transactions service. Configure the policy as you normally would; additionally:

   • Set the credential.delegation property to true.

3. Attach the corresponding Kerberos or SPNEGO client policy to the MyBanker client. Configure the policy as you normally would; additionally:

   • Set the service.principal.name property to the principal name of the Transactions service.

   • Make sure the caller.principal.name and keytab.location properties are set.

   • Set the credential.delegation property to true.

4. Attach the appropriate predefined Kerberos or SPNEGO service policy to the OldTransactions service. Configure the policy as you normally would.

5. Attach the corresponding predefined Kerberos or SPNEGO client policy to the Transactions service. Configure this policy as follows:

   • Set the service.principal.name property to the principal name of the OldTransactions service.

   • Make sure the caller.principal.name and keytab.location properties are not set.

To extend this example to accommodate additional delegations of MyBanker's credentials, you would need to perform these tasks for each additional delegation:

• Give OWSM permission to forward tickets to the service receiving the delegated credentials as described in "Configuring Delegation Permission to OWSM".

• Set the credential.delegation property to true in the service policy for the service forwarding the delegated credentials.

• Add a service policy to the service receiving the delegated credentials.

• Add the corresponding client policy to the service forwarding the delegated credentials, configuring it as described in Step 5 of the example procedure.

10.7 Configuring WS-Trust

This section describes how to configure and use the OWSM policies for WS-Trust using Security Token Services (STSes), The first subsection, Overview of Web Services WS-Trust, provides introductory information about WS-Trust and how it uses STSes to broker trust between web service clients and web services. The remaining subsections describe specific configuration topics related to WS-Trust:

• Supported STS Servers

• Token Lifetime and Token Caching

• Setting Up Automatic Policy Configuration for STS

• Configuring Web Services Federation

• SAML Holder of Key and SAML Bearer as Issued Tokens

• SAML Sender Vouches as Issued Tokens

• On Behalf Of Use Cases

• Programmatically Overriding Policy Configuration for WS-Trust Client Policies

10.7.1 Overview of Web Services WS-Trust

The WS-Trust 1.3 specification defines extensions to WS-Security that provide a framework for requesting and issuing security tokens, and to broker trust relationships. WS-Trust extensions provide methods for issuing, renewing, and validating security tokens.

To secure communication between a web service client and a web service, the two parties must exchange security credentials. As defined in the WS-Trust specification, these credentials can be obtained from a trusted Security Token Service (STS), which acts as trust broker. That is, the web service client and the web service do not explicitly trust each other; instead, they implicitly trust each other because they both trust the STS.

When using an STS as a trust broker, authentication proceeds as follows:

1. The web service client authenticates itself to the STS and requests a security token to be issued to it. This is called the RequestSecurityToken (RST) message.

2. The STS confirms the web service client's credentials and then responds to the security token request. This is called the RequestSecurityTokenResponse (RSTR) message.

3. The web service client presents to the web service the security token that the STS issued to it.

4. The web service confirms the validity of the issued security token.

Upon successful completion of this process, the web service client can make requests to the web service.

When OWSM is used to manage authentication, the actual process to achieve the preceding generic process is as follows:

1. The web service client wants to invoke a web service. The OWSM agent attempts to fetch the WSDL of the web service and extract the issued token service policy. The OWSM agent uses the local client policy (as optionally overridden) to talk to the STS identified in the WSDL.

   The web service policy can require the issued token to be from a specific STS.

2. The OWSM agent issues an RST to the STS.

3. The STS responds with an RSTR.

4. The OWSM agent processes the RSTR sent by the STS and propagates the issued token to the web service.

5. The OWSM agent servicing the web service processes and verifies the issued token and generates a response back.

Web Services Federation

In acting as a trust broker, an STS provides two main services:

• It issues tokens to authenticated web service clients

• It validates tokens as requested by web services

Additionally, an STS can accept a token issued by another STS and issue its own token based on the received token's content, provided that it trusts the other STS. This ability of STSes to trust each other and to transform issued tokens enables federated trust across security domains, which is called web services federation.

As an example, a web service client in one security domain wants to invoke a web service that is in another security domain. If the there is an STS in each domain, and they trust each other, the web service client can invoke the web service as follows:

1. The web service client authenticates itself to the STS in its security domain and requests a security token to be issued to it. This STS is called the Identity Provided STS, or IP-STS.

2. The IP-STS confirms the web service client's credentials and then responds to the security token request, providing an issued token.

3. The web service client presents the issued token from the IP-STS to the STS in the web service's security domain and request a security token be issued to it. This second STS is called the Relying Party STS, or RP-STS.

4. The RP-STS confirms the validity of the issued token from the IP-STS. Using data from the IP-STS's token, it creates its own token and provides it to the web service client.

5. The web service client presents to the web service the issued token from the RP-STS.

6. The web service confirms the validity of the issued token from the STS that it trusts, the RP-STS in its own security domain.

The preceding process shows how a web service client can communicate with a web service in a different security domain due to the trust shared between STSes in the two domains. However, this shared trust between STSes can be extended even further: if the IP-STS and the RP-STS do not trust each other directly, but share trust with the same intermediary STS, a chain of trust can be formed from the IP-STS to the intermediary STS to the RP-STS. Moreover, additional intermediary STSes can be positioned between the IP-STS and the RP-STS, provided that a chain of trust can be traced from the IP-STS to the RP-STS.

For information about using OWSM to configure web services federation, see "Configuring Web Services Federation".

10.7.1.1 How the STS Configuration is Obtained

The STS is also a web service. To communicate with the STS, the client application needs to know the STS details, such as the port-uri, port-endpoint, wsdl-uri, and the security tokens it can accept from clients trying to authenticate to it.

There are two mechanisms by which STS information becomes available to the client.

• Automatic (Client STS) Policy Configuration (see "Setting Up Automatic Policy Configuration for STS") is involved. Automatic Policy Configuration dynamically generates the information about the STS by parsing the STS WSDL document.

  Automatic Policy Configuration is triggered when the STS config policy is attached to the web service and not the client. Additionally, the only information provided in the STS config policy is the port-uri of the target STS.

  When this policy is attached to the web service along with the issued token service policy, the port-uri of the STS appears as the Issuer-Address in the IssuedToken assertion of the web service WSDL. As a result, all the other STS information (target namespace, service name, endpoint, and so forth) is obtained by accessing the STS WSDL and is saved in memory as the STS config. This information is stored only in memory and is not persisted in the OWSM repository. (For details about the repository, see Chapter 15, "Managing the OWSM Repository."

  If you specify the STS URI in the web service STS config policy and attach it to the web service, the client is forced to use that STS; it cannot override it.

• You do not use Automatic Policy Configuration and instead attach the STS config policy to the client and specify all the STS-related information (port-endpoint, port-uri, public key alias, a reference to an OWSM client policy to be used for authenticating to the STS) before invoking the web service. In this case, all the information is already available to the run time from the STS config policy.

10.7.1.2 What Token Types Are Exchanged?

Although an STS can theoretically receive any token from the client and exchange it for any other token, in practice the STS generally accepts one of the following tokens and returns a SAML assertion:

• Username token. For this token type:

  1. The web service client sends a user name and password to the STS.

  2. The STS verifies the password and returns a SAML assertion.

  3. The client sends the SAML assertion to the web service.

  This scenario is useful when the web service does not have the ability to verify passwords, so it relies on the STS to verify them.

• Kerberos token. For this token type:

  1. The client sends a user name and password to a KDC and gets a Kerberos token.

  2. The client sends the Kerberos token to the STS and gets a SAML assertion.

  3. The client sends the SAML assertion to the web service.

  This scenario is useful in Windows environments. Clients running on the Windows machine have the logged-on user context, and they can use this context to get a SAML assertion from the STS for that user.

  In this scenario, the clients do not have the password so they cannot use a username token, they can use only Kerberos.

• X509 token. For this token type the client uses a private key to authenticate itself to the STS.

In response, the STS generally returns one of the following tokens:

• SAML Holder of Key Symmetric

• SAML Holder of Key Asymmetric

• SAML Bearer

For information about these tokens, see "SAML Holder of Key and SAML Bearer as Issued Tokens".

An STS can also return SAML Sender Vouches tokens. For more information, see "SAML Sender Vouches as Issued Tokens".

10.7.2 Supported STS Servers

OWSM provides a standard WS-Trust client. This client has been certified to interoperate with the following Security Token Services:

• Oracle Security Token Service (OSTS)

• Oracle OpenSSO STS

• Microsoft ADFS 2.0 Security Token Service (STS)

10.7.3 Token Lifetime and Token Caching

The RSTR response message from an STS may contain a lifetime element (<trust:Lifetime>) indicating the validity of the returned token. If the lifetime element is present, OWSM validates the timestamp and rejects the message if the response has expired.

Additionally, OWSM supports caching of returned tokens. Two configuration properties, issued.token.caching and issued.token.lifetime, in issued token client policies control caching of returned tokens.

When issued.token.caching is set to true in a policy, OWSM requests a lifetime for returned tokens for the period specified by issued.token.lifetime in the RST request message to an STS. When it is set to false, OWSM does not request a lifetime for returned tokens.

If the STS returns a token lifetime value different from the requested issued.token.lifetime value, OWSM uses the return value as the period for caching returned tokens. It the STS returns an empty token expiry value, OWSM does not cache returned tokens despite issued.token.caching being set to true.

Thus, the issued.token.lifetime property is used only to request a particular lifetime for returned tokens. The STS is not obligated to honor the value, and OWSM performs token caching based on the actual lifetime value returned by the STS.

If you set issued.token.caching to true but do not provide a value for issued.token.lifetime, OWSM uses the domain default value of 28800000 milliseconds (eight hours). To change this domain default value, see "Configuring the Lifetime for the Issued Token Using Fusion Middleware Control".

10.7.4 Setting Up Automatic Policy Configuration for STS

Automatic Policy Configuration dynamically generates the information about the STS by parsing the STS WSDL document.

When the STS config policy is attached to the web service (and not to the client) Automatic Policy Configuration happens at run time on the first connect from client to server.

The only information you provide in the STS config policy (oracle/sts_trust_config_service_policy) is the port URI of the target STS. When this policy is attached to the web service (along with the issued token service policy) the port-uri of the STS appears as the Issuer-Address in the IssuedToken assertion of the web service WSDL.

As a result, OWSM obtains the other STS information (target namespace, service name, endpoint, and so forth) by accessing the STS WSDL and is saved in memory as the STS config. This information is saved in memory but is not persisted in MDS.

This section describes the following topics:

• Requirements for Automatic Policy Configuration

• Setting Up Automatic Policy Configuration: Main Steps

• Manually Configuring the STS Config Policy From the Web Service Client: Main Steps

10.7.4.1 Requirements for Automatic Policy Configuration

There are several requirements for successfully communicating with the STS using Automatic Policy Configuration:

• Automatic Policy Configuration does not work with JSE clients. If you are using JSE clients in a WS-TRUST scenario, you need to provide all the STS configuration information to the client by attaching both the sts_trust_config_client_policy and the issued token client policy.

• The oracle/sts_trust_config_service_policy policy must be attached to the web service. If it is not, you cannot use Automatic Policy Configuration and must instead manually configure the oracle/sts_trust_config_client_policy policy for the client, as described in "Manually Configuring the STS Config Policy From the Web Service Client: Main Steps".

• Automatic Policy Configuration cannot be used for SAML sender vouches confirmation because the trust is between the web service and the client. The web service WSDL will not have any information about the STS.

• The certificate and public key alias of the STS must be in the keystore. The default alias name is sts-csf-key. See "Configuring Keystores for Message Protection" for information on how to do this.

• The client's public key must be available in the STS keystore.

10.7.4.2 Setting Up Automatic Policy Configuration: Main Steps

Perform the following steps to use Automatic Policy Configuration.

1. Configure a Policy for Automatic Policy Configuration

2. Configure a Web Service Client for Automatic Policy Configuration

3. Configure a Web Service for Automatic Policy Configuration

10.7.4.2.1 Configure a Policy for Automatic Policy Configuration

Perform the following steps to configure a policy for automatic policy configuration:

1. Decide which STS your web service trusts and import that STS's public certificate into the OWSM keystore.

2. Optionally, add the Distinguished Name of the STS to the Trusted STS list, as described in "Defining Trusted Issuers and Trusted Distinguished Names List for SAML Signing Certificates".

3. If you want to use SAML HOK symmetric, you need to add an entry in the STS configuration for your web service and the certificate of your web service. The STS encrypts symmetric keys using this certificate.

4. Make a copy of the sts_trust_config_service_policy policy.

5. Edit the Port URI setting to add the port URI of the STS.

   An STS usually exposes multiple URI points for different input and output token types; use the URI corresponding to the token that you want.

10.7.4.2.2 Configure a Web Service Client for Automatic Policy Configuration

Perform the following steps to configure a web service client for automatic policy configuration:

1. Attach the issued token policy to your web service client, depending on what type of token the web service requires.

   The following predefined issued token policies are provided:

   • oracle/wss11_sts_issued_saml_hok_with_message_protection_client_policy for SAML HOK.

   • oracle/wss_sts_issued_saml_bearer_token_over_ssl_client_policy for SAML Bearer.

2. Set or override the following properties of the issued token policy depending on the use case. See "Assertion Template Configuration Properties" for descriptions of these properties.

   • sts.auth.user.csf.key

   • sts.auth.x509.csf.key

   • sts.keystore.recipient.alias

   • sts.auth.keytab.location

   • sts.auth.caller.principal.name

   • sts.auth.service.principal.name

   • sts.auth.on.behalf.of.csf.key

   • on.behalf.of

   sts.keystore.recipient.alias is used for the client to STS communication for message protection and is sufficient if the client to STS communication is using wss11 message protection.

   However, if it is using wss10 message protection, you need to additionally set up the signing key and encryption key for the client, and then import the trust for these keys into the STS configuration.

3. Make sure the STS public certificate and credentials are present in the keystore and the client's public key is available in the STS keystore. See "Configuring Keystores for Message Protection" for information on how to do this.

10.7.4.2.3 Configure a Web Service for Automatic Policy Configuration

1. Attach the edited sts_trust_config_service_policy to the web service.

   Note:

   You must attach both the sts_trust_config_service_policy policy and an STS issued-token service policy. The policies work as a pair.

2. Attach the issued-token service policy (corresponding to the one attached to the client). There are two predefined issued token policies:

   • oracle/wss11_sts_issued_saml_hok_with_message_protection_service_policy -- Use this when you want your service to accept SAML HOK asymmetric or symmetric. Do not use SSL for this policy.

     As with all other wss11 message protection policies, you must set up an encryption key.

     You can modify some options in the policy. For example, whether you want SAML 1.1 or 2.0, and whether you want asymmetric or symmetric keys.

   • oracle/wss_sts_issued_saml_bearer_token_over_ssl_service_policy -- Use this when you want SAML Bearer. However, you must set up your web service for SSL to use this policy.

     You can specify whether you want SAML 1.1 or 2.0.

3. Override keystore.enc.csf.key in the issued-token service policy, if required.

4. Make sure the client's public key is available in the OWSM keystore.

10.7.4.3 Manually Configuring the STS Config Policy From the Web Service Client: Main Steps

You are encouraged to configure the STS config policy from the web service, as described in "Setting Up Automatic Policy Configuration for STS". However, in the following situations you must configure it from the web service client:

• You did not configure the STS config policy from the web service

• You are using the SAML sender vouches confirmation method

• You are using a JSE client. Automatic Policy Configuration does not work with JSE clients.

Perform the following steps to configure the STS config policy from the web service client using Fusion Middleware Control.

Note:

The predefined policies that are provided with OWSM are read-only and cannot be edited. To edit a predefined policy you can clone it and then edit the cloned version.

1. Create a new STS trust config policy. You can do so using either of the following methods:

   • Create a new policy and add the oracle/sts_trust_config_client_template assertion template. For more information, see "Creating a New Web Service Policy".

   • Clone the oracle/sts_trust_config_client_policy policy. For more information, see "Cloning a Web Service Policy".

2. Edit your new or cloned policy as follows:

   1. In the WSM Policies page, select your new policy from the list and click Open.

   2. Select the Assertions tab.

   3. In the STS Configuration section, click No in the WSDL Exist? field and, at a minimum, provide the following information:

   • In the Port URI field, enter the actual endpoint URI of the STS port. For example http://host:port/context-root/service1.

   • In the Port Endpoint field, enter the endpoint of the web service, specified as target-namespace#wsdl.endpoint(service-name/port-name).

   • In the Client Policy URI field, select the OWSM client policy that will be used by the client to communicate with the STS. The policy you choose depends on the authentication requirements of the STS, as identified in its WSDL.

     The policy that you specify here determines what you must later set or override in the issued token client policy:

     • If Client Policy URI references a username-based policy, then you later configure the sts.auth.user.csf.key parameter to authenticate to STS and create a username token. You also configure sts.auth.x509.csf.key to specify the signature and encryption key alias.

     • If the Client Policy URI references an x509-based policy, then you later configure the sts.auth.x509.csf.key parameter to specify the X509 certificate for authenticating to the STS.

   • In the Keystore Recipient Alias field, specify the alias of the STS certificate that you added to the keystore. The default alias name is sts-csf-key.

3. Save your changes.

4. If you have not already done so, select an issued token client policy.

5. Attach both web service client policies to your web service client, as described in Chapter 4, "Attaching Policies." You must attach the policies in this order:

   1. The STS trust config client policy that you created in step 1.

   2. Issued token client policy.

   If you attach multiple instances of the sts_trust_config_client_policy, no error is generated. However, only one instance is enforced, and you cannot control which instance that is.

6. Use Fusion Middleware Control to edit the configuration overrides in your chosen issued token client policy. For more information, see Chapter 5, "Overriding Policy Configuration Properties."

7. Save your changes.

10.7.5 Configuring Web Services Federation

The following sections describe how to configure web services, web service clients and STSes for web services federation.

10.7.5.1 Configuring a Web Service for Web Services Federation

To configure a web service for web services federation, perform these steps:

1. Attach the desired issued token service policy to the service. OWSM provides the following predefined policies:

   • oracle/wss_sts_issued_saml_bearer_token_over_ssl_service_policy

   • oracle/wss11_sts_issued_saml_hok_with_message_protection_service_policy

2. Optionally, attach the oracle/sts_trust_config_service_policy policy and configure it to refer to the RP-STS. Attaching and configuring this policy enables automatic policy configuration for the RP-STS, which permits any web service clients using the service to avoid having to attach an oracle/sts_trust_config_client_policy policy for the RP-STS. For more information, see "Setting Up Automatic Policy Configuration for STS".

3. Import the signing certificate for the RP-STS into the OWSM keystore.

4. Define the RP-STS as a trusted issuer and a trusted DN, as described in "Defining Trusted Issuers and Trusted Distinguished Names List for SAML Signing Certificates".

10.7.5.2 Configuring a Web Client for Web Services Federation

How you configure a web client for web services federation depends on whether issuer information is provided in the WSDLs for the web service and for the RP-STS.

10.7.5.2.1 Issuer Is in the Service WSDL and Is Not in the RP-STS WSDL

This is the most common use case, and is the use case when the web service is configured for automatic policy configuration of the RP-STS.

For this use case, perform these steps configure the web client:

1. Attach the issued token client policy corresponding to the issued token service policy that is attached to the web service and configure it to refer to the web service. In addition, if you are using the message protection policy, set the sts.keystore.recipient.alias configuration property to the certificate alias of the RP-STS; if you are using the SSL policy, do not set this property.

2. Attach the attach the oracle/sts_trust_config_client_policy policy and configure it to refer to the IP-STS.

10.7.5.2.2 Issuer Is Not in the Service WSDL and Is Not in the RP-STS WSDL

This is a less common use case, and is the use case when the web service is not configured for automatic policy configuration of the RP-STS.

For this use case, perform these steps configure the web client:

1. Attach the issued token client policy corresponding to the issued token service policy that is attached to the web service and configure it to refer to the web service. Additionally, set the sts.in.order configuration property to the endpoint URI of the RP-STS followed by the endpoint URI of the IP-STS. Separate the two URIs with a semicolon (;). For example:

   http://m2.example.com:14100/sts/wssbearer;
   http://http://m1.example.com/adfs/services/trust/13/usernamemixed
   

2. Attach the oracle/sts_trust_config_client_policy policy and configure it to refer to the IP-STS.

3. Attach the oracle/sts_trust_config_client_policy policy and configure it to refer to the RP-STS.

10.7.5.2.3 Issuer Is in the Service WSDL and Is in the RP-STS WSDL

This is a rare use case.

For this use case, perform these steps configure the web client:

1. Attach the issued token client policy corresponding to the issued token service policy that is attached to the web service and configure it to refer to the web service. In addition, if you are using the message protection policy, set the sts.keystore.recipient.alias configuration property to the certificate alias of the RP-STS; if you are using the SSL policy, do not set this property.

2. Attach the attach the oracle/sts_trust_config_client_policy policy and configure it to refer to the IP-STS.

10.7.5.2.4 Issuer Is Not in the Service WSDL and Is in the RP-STS WSDL

This is a rare use case.

For this use case, perform these steps configure the web client:

1. Attach the issued token client policy corresponding to the issued token service policy that is attached to the web service and configure it to refer to the web service. Additionally, if you are using the message protection policy, set the sts.in.order configuration property to the endpoint URI of the RP-STS followed by the endpoint URI of the IP-STS; if you are using the SSL policy, do not set this property.

2. If you are using the message protection policy, attach the oracle/sts_trust_config_client_policy policy and configure it to refer to the IP-STS; if you are using the SSL policy, do not perform this step.

3. Attach the oracle/sts_trust_config_client_policy policy and configure it to refer to the RP-STS.

10.7.5.3 Configuring an STS for Web Services Federation

The following steps to configure an STS as an RP-STS or an IP-STS are general, high-level steps. For detailed steps, refer to the documentation for the particular STS. For Oracle STS, see http://www.oracle.com/technetwork/middleware/id-mgmt/overview/oraclests-166231.html.

For Microsoft ADFS 2.0 STS, see http://technet.microsoft.com/en-us/library/adfs2(v=ws.10).aspx.

To configure the RP-STS for web services federation, use the administrative interface of the RP-STS to perform these steps:

1. Add the web service as a relying party.

2. Add the IP-STS as a trusted identity provider.

   In Oracle STS, a trusted identity provider is called an Issuing Authority.

   In Microsoft ADFS 2.0 STS, a trusted identity provider is called a Claim Provider.

To configure the IP-STS for web services federation, use the administrative interface of the IP-STS to perform this step:

• Add the RP-STS as a relying party.

10.7.6 SAML Holder of Key and SAML Bearer as Issued Tokens

In general, an STS generally returns one of the following kinds of tokens in the SAML assertion:

• SAML Holder of Key Symmetric. The SAML assertion that is returned by the STS is meant only for the particular client that sent its client token (username token, Kerberos, X509, etc) to the STS.

  A rogue client should not be allowed to steal this SAML assertion and use it. This is accomplished by a "proof key," which can be either symmetric or asymmetric.

  A symmetric proof key is generated on the STS side, or on the client side, or by taking inputs from both sides, as described in "How the Proof Key is Determined (SAML HOK Only)".

  The STS puts this symmetric proof key in the SAML HOK assertion in an encrypted form that only the web service can decrypt. Then, it signs the entire SAML assertion (including the encrypted proof key) and sends it to the client.

  When the client sends this SAML assertion to the server, it also needs to sign something with this proof key. The web service will at first verify the STS signature of the SAML assertion, extract the proof key from the SAML assertion, and then decrypt it and verify the client's signature. This client's signature "proves" to the server that the client has the proof key.

  Because this proof key is never sent in clear text, a rogue client cannot get it by network sniffing. Even if a rogue client gets the SAML assertion by network sniffing, it cannot make use of it, because it does not have the proof key and cannot sign with it. Therefore, the rogue client cannot prove to the server that it is allowed to use the SAML assertion.

• SAML Holder of Key Asymmetric. The asymmetric proof key works as follows.

  1. The client generates a public/private key pair.

  2. It keeps the private key and securely sends the public key to the STS along with its token (username token, Kerberos, X509, and so forth.)

  3. The STS verifies the client's token, and returns a SAML assertion containing the public key. The entire SAML assertion (including the public key) is signed by the STS and returned to the client.

  4. The client then sends a SAML HOK asymmetric assertion to a web service, and it signs something with the private key of that public-private key pair.

  5. The web service verifies the STS's signature of the SAML assertion, then extracts the public key from the SAML assertion and uses it to verify the client's signature.

     This client's signature proves to the web service that the SAML assertion is being used correctly, and was not stolen and replayed.

  Note:

  Unlike in the case of SAML HOK symmetric key, this public key in SAML HOK is not encrypted. This reduces the amount of configuration required on the STS side.

  For SAML HOK symmetric, the STS must be configured with each web service's certificate so that it can encrypt the symmetric key for that web service. This is not required for SAML HOK asymmetric.

  Also, the same SAML HOK asymmetric token can be sent to any web service because it is not encrypted with a particular web service's key.

  Note:

  Even though there is a public/private key pair, there is no certificate involved. That is, the public key is not sent to a Certificate Authority to request a certificate.

  Instead, the STS acts similar to a CA. A CA takes in a public key and returns a certificate. In this case, the STS takes in a public key and returns a SAML assertion.

  However, unlike a certificate whose lifetime is usually in many years, the SAML assertion issued by the STS usually has a lifetime of a few hours, after which the client would have to generate a new key pair and request a new SAML assertion.

  Because of this short life, there is no need for the revocation checking that is required for certificates. This makes it attractive on the client side, because there are no client keys to manage.

• SAML Bearer. The SAML bearer key has no proof key associated with it. Therefore, it must be used over SSL to prevent any rogue client from stealing and replaying it.

10.7.6.1 How the Proof Key is Determined (SAML HOK Only)

For SAML Holder of Key (HOK), a proof key is required to protect communications between the client and the web service. The proof key indicates proof of possession of the token associated with the requested security token.

You specify the requirements for the proof key type in the oracle/wss11_sts_issued_saml_hok_with_message_protection_service_policy policy in the <key-type> entry in the <sp:IssuedToken> policy assertion. For example,

<orasp:request-security-token-templateorasp:key-type = "Symmetric"

or

orasp:key-type = "Public"

Symmetric, asymmetric, and no proof key (not defined) are supported.

These possible values of <key-type> are contained in the WS-Trust 1.3 specifications:

• http://docs.oasis-open.org/ws-sx/ws-trust/200512/PublicKey

• http://docs.oasis-open.org/ws-sx/ws-trust/200512/SymmetricKey

10.7.6.1.1 Calculating a Symmetric Proof Key

If a symmetric proof key is required by the web service's security policy, the requestor can pass some key material (entropy) that can be included in the calculation of the proof key. The web service policy can indicate whether client entropy, STS entropy, or both are required.

However, the STS determines what to use for the proof key. When processing the token request, the STS can:

• Accept the client entropy as the sole key material for the proof key. In this case, there is no <wst:RequestedProofToken> element present in RSTR; the proof key is implied.

  The OWSM agent uses the client entropy as the key material for signing and encryption.

• Accept the client entropy as partial key material and contribute additional STS server-side entropy as partial key material to compute the proof key as a function of both partial key materials.

  There is a <wst:Entropy> element containing the STS-supplied entropy in the RSTR. The <wst:RequestedProofToken> element is also present in RSTR and it contains the computed key mechanism. The default value for the algorithm is http://docs.oasis-open.org/ws-sx/ws-trust/200512/CK/PSHA1.

  The OWSM agent and the STS compute the proof key by combining both entropies using the specified computed key mechanism.

• Reject the client-side entropy and use the STS server-side entropy as the sole key material for the proof key.

  There is a <wst:RequestedProofToken> element present in RSTR that contains the proof key. The OWSM agent uses the STS entropy as the key material for signing and encryption.

10.7.6.1.2 Requesting an Asymmetric Proof Key

An asymmetric proof key uses private/public key pairs, and is termed "asymmetric" because the public and private keys are different.

When requesting an asymmetric key token, the RST includes the wst:KeyType element with the following URI: http://docs.oasis-open.org/ws-sx/ws-trust/200512/PublicKey.

10.7.7 SAML Sender Vouches as Issued Tokens

An STS typically returns a SAML HOK or SAML Bearer token. However, an STS can also return SAML sender vouches tokens.

SAML sender vouches has a completely different trust model. In HOK and Bearer the SAML assertion is issued by an STS and is signed by the STS. In this case, the web service does not trust the client directly, but it trusts the STS. When the web service receives an HOK or Bearer token, it verifies the signature against the trusted STS.

This indirect trust model greatly simplifies the trust store management. That is, if there are five clients talking to five web services using message protection, then each of the web services must know the five client public keys. However, if there an STS in between, the web services need to know only the public key of the STS.

For SAML sender vouches, the web service trusts the client directly. A SAML sender vouches token is typically directly generated by a client and signed by the client private key. However a client may choose to ask the STS to generate the token. The STS does not sign the SAML assertion in this case, and simply returns it to the client. The client signs the SAML sender vouches token as before and sends it to the web service. The web service is not aware that the client obtained the SAML sender vouches token from an STS and it checks the client signature.

10.7.7.1 Configuring SAML Sender Vouches with WS-Trust

To set up SAML sender vouches with WS-Trust, configure the web service without an issued token policy; that is, use the oracle/wss11_saml_token_with_message_protection_service_policy policy.

Configure the client with an issued token policy. Use the oracle/wss11_sts_issued_saml_with_message_protection_client_policy, which is meant for SAML sender vouches, and also an STS config policy.

The Automatic Policy Configuration feature (see "Setting Up Automatic Policy Configuration for STS") cannot be used for SAML sender vouches because the web service WSDL will not have information about the STS.

10.7.8 On Behalf Of Use Cases

"On Behalf Of" is an identity propagation use case, in which the web service client requests the STS token on behalf of another entity.

Consider the following scenario:

1. The web service client invokes the STS to get a token for another entity. This entity can be the end user or any other external entity. The entity's credentials are included in the RST in the onBehalfOf element.

2. The STS verifies the credentials presented by the web service client and issues a security token for the entity identified in the onBehalfOf element.

3. The web service client verifies the RSTR, extracts the token, and passes it to the web service.

4. The web service receives the SAML assertion for the end user and verifies that the token was issued by a trusted STS.

The "On Behalf Of" use case relies on the sts.auth.on.behalf.of.csf.key and on.behalf.of properties described in Chapter 18, "Predefined Assertion Templates." If the "On Behalf Of" username is obtained from the Subject, it is a username without a password.

If sts.auth.on.behalf.of.csf.key identifies a CSF key for the "On Behalf Of" user entity, the identity established using that CSF key is sent on behalf of the other entity. It can be a username with or without a password.

10.7.9 Programmatically Overriding Policy Configuration for WS-Trust Client Policies

Table 5-1 shows the properties you can set via programmatic configuration overrides for a given policy.

The following list shows how to override STS properties programmatically for a set of sample use cases.

Token exchange username token – SAML with symmetric proof key

(BindingProvider)port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_USER_CSF_KEY, "my-user-csf-key");
(BindingProvider)port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_X509_CSF_KEY, "my-x509-csf-key");

Token exchange x509 token – SAML with symmetric proof key

(BindingProvider)port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_X509_CSF_KEY, "my-x509-csf-key");

Token exchange username token – SAML with asymmetric proof key

(BindingProvider)port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_USER_CSF_KEY, "my-user-csf-key");
(BindingProvider)port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_X509_CSF_KEY, "my-x509-csf-key");

Token exchange x509 token – SAML with asymmetric proof key

(BindingProvider)port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_X509_CSF_KEY, "my-x509-csf-key");

On Behalf Of token exchange with On Behalf Of username from Subject, requestor token username – SAML with symmetric proof key

(BindingProvider)port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_USER_CSF_KEY, "my-user-csf-key");

on.behalf.of must be set to true.

On Behalf Of token exchange with On Behalf Of username, requestor token username – SAML with symmetric proof key

(BindingProvider)port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_ON_BEHALF_OF_CSF_KEY, "my-on-behalf-of-csf-key");
(BindingProvider)port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_X509_CSF_KEY, "my-x509-csf-key");

on.behalf.of must be set to true.

On Behalf Of token exchange with On Behalf Of username, with requestor token x509 – SAML with symmetric proof key

(BindingProvider)port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_ON_BEHALF_OF_CSF_KEY, "my-on-behalf-of-csf-key");
(BindingProvider)port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_X509_CSF_KEY, "my-x509-csf-key");

on.behalf.of must be set to true.

On Behalf Of token exchange with On Behalf Of username from Subject, with requestor token username – SAML with asymmetric proof key

(BindingProvider)port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_USER_CSF_KEY, "my-user-csf-key");

on.behalf.of must be set to true.

On Behalf Of token exchange with On Behalf Of username, with requestor token username – SAML with asymmetric proof key

(BindingProvider)port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_ON_BEHALF_OF_CSF_KEY, "my-on-behalf-of-csf-key");
(BindingProvider)port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_USER_CSF_KEY, "my-user-csf-key");

on.behalf.of must be set to true.

On Behalf Of token exchange with On Behalf Of username, with requestor token x509 - SAML with asymmetric proof key

(BindingProvider)port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_ON_BEHALF_OF_CSF_KEY, "my-on-behalf-of-csf-key");
(BindingProvider)port).getRequestContext().put(SecurityConstants.ClientConstants.WSM_STS_AUTH_X509_CSF_KEY, "my-x509-csf-key");

on.behalf.of must be set to true.