Fusion Middleware Documentation
Advanced Search


Securing Web Services and Managing Policies with Oracle Web Services Manager
Close Window

Table of Contents

Show All | Collapse

14 WS-Trust Use Cases

The use cases in this chapter demonstrate the use of the three security token services that OWSM supports: Oracle STS, Microsoft ADFS 2.0 STS and OpenSSO STS. The use cases also demonstrate both simple trust and web services federation, and demonstrate the different types of SAML policies.

This chapter contains the following sections:

14.1 Web Services Federation with Oracle STS and Microsoft ADFS 2.0 STS

The following sections provide two high-level use case examples of web services federation using Oracle STS and Microsoft ADFS 2.0 STS.

In the first example, Microsoft ADFS 2.0 STS is used as the IP-STS and Oracle STS is used as the RP-STS. Transport security with SSL is used to protect the service, the RP-STS and the IP-STS.

In the second example, the STSes are reversed, with Oracle STS being used as the IP-STS and Microsoft ADFS 2.0 STS being used as the RP-STS. SAML holder-of-key (HOK) message security is used to protect the endpoints.

Note:

In the following sections, high-level configuration tasks for Oracle STS and Microsoft ADFS 2.0 STS are provided. For detailed information on how to perform these tasks, refer to the documentation for the particular STS:

14.1.1 Federation with Microsoft ADFS 2.0 STS as the IP-STS and Oracle STS as the RP-STS

In this high-level use case example, Microsoft ADFS 2.0 STS is used as the IP-STS and Oracle STS is used as the RP-STS. Transport security with SSL is used to protect the service, the RP-STS and the IP-STS.

14.1.1.1 Configure the Service

Follow these steps to configure the service:

  1. Attach the following policy to the service:

    oracle/wss_sts_issued_saml_bearer_token_over_ssl_service_policy
    
  2. Import the signing certificate for the Oracle STS /wssbearer endpoint into the OWSM keystore.

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

14.1.1.2 Configure Oracle STS as the RP-STS

Follow these steps to configure Oracle STS as the RP-STS.

(For detailed information about performing the following Oracle STS configuration tasks, see the Oracle STS documentation at http://www.oracle.com/technetwork/middleware/id-mgmt/overview/oraclests-166231.html.)

  1. Configure WebLogic Server to enable 1-way SSL on port 14101.

  2. Configure the Oracle STS /wssbearer endpoint as follows:

    • Attach the policy with the URI sts/wss_sts_issued_saml_bearer_token_over_ssl_service_policy.

    • Create an OWSM LRG SAML Validation validation template to validate the incoming SAML token and apply it to the endpoint.

  3. Add the service as a replying party partner in Oracle STS.

  4. Add the Microsoft ADFS 2.0 STS instance acting as the IP-STS as a trusted identity provider:

    1. Configure an issuing authority partner profile for the Microsoft ADFS 2.0 STS instance.

    2. Add the Microsoft ADFS 2.0 STS instance as an issuing authority partner, giving as the partner name the issuer of the SAML assertion for the instance.

    3. Import the signing certificate for the Microsoft ADFS 2.0 STS instance into the OWSM keystore.

14.1.1.3 Configure Microsoft ADFS 2.0 STS as the IP-STS

Follow these steps to configure Microsoft ADFS 2.0 STS as the IP-STS:

(For detailed information about performing the following Microsoft ADFS 2.0 STS configuration tasks, see the Microsoft ADFS 2.0 STS documentation at http://technet.microsoft.com/en-us/library/adfs2(v=ws.10).aspx.)

  1. Confirm that the /usernamemixed endpoint is enabled.

  2. Using the ADFS 2.0 management console, add the Oracle STS instance acting as the IP-STS as a relying party.

  3. Configure ADFS 2.0 STS to issue SAML bearer tokens for the RP-STS.

14.1.1.4 Configure the Client

Follow these steps to configure the client:

  1. Attach the policy oracle/wss_sts_issued_saml_bearer_token_over_ssl_client_policy and configure it to refer to the service.

    Additionally, set sts.in.order to the URI of the Oracle STS endpoint followed by the ADFS 2.0 STS endpoint; for example:

    http://m2.example.com:14100/sts/wssbearer;
    http://http://m1.example.com/adfs/services/trust/13/usernamemixed
    
  2. Create a policy from oracle/sts_trust_config_client_template, change it as follows, and attach it to the client:

    • Set Port URI to the ADFS 2.0 STS endpoint; for example:

      http://m1.example.com/adfs/services/trust/13/usernamemixed
      
    • Set Client Policy URI oracle/wss_sts_issued_saml_bearer_token_over_ssl_client_policy.

  3. Create a policy from oracle/sts_trust_config_client_template, change it as follows, and attach it to the client:

    • Set Port URI to the Oracle STS endpoint; for example:

      http://m2.example.com:14100/sts/wssbearer
      

14.1.2 Federation with Oracle STS as the IP-STS and Microsoft ADFS 2.0 STS as the RP-STS

In this high-level use case example, Oracle STS is used as the IP-STS and Microsoft ADFS 2.0 STS is used as the RP-STS. SAML holder-of-key (HOK) message security is used to protect the endpoints.

14.1.2.1 Configure the Service

Follow these steps to configure the service:

  1. Attach the following policy to the service:

    oracle/wss11_sts_issued_saml_hok_with_message_protection_service_policy
    
  2. Import the signing certificate for the ADFS 2.0 STS /issuedtokensymmetricbasic256 endpoint into the OWSM keystore.

  3. Define the ADFS 2.0 STS endpoint as a trusted issuer and a trusted DN, as described in "Defining Trusted Issuers and Trusted Distinguished Names List for SAML Signing Certificates".

14.1.2.2 Configure Microsoft ADFS 2.0 STS as the RP-STS

Follow these steps to configure Microsoft ADFS 2.0 STS as the RP-STS:

(For detailed information about performing the following Microsoft ADFS 2.0 STS configuration tasks, see the Microsoft ADFS 2.0 STS documentation at http://technet.microsoft.com/en-us/library/adfs2(v=ws.10).aspx.)

  1. Confirm that the /issuedtokensymmetricbasic256 endpoint is enabled.

  2. Using the ADFS 2.0 management console, add the service as a relying party.

  3. Using the ADFS 2.0 management console, add the Oracle STS instance acting as the IP-STS as a trusted claim provider.

14.1.2.3 Configure Oracle STS as the IP-STS

Follow these steps to configure Oracle STS as the IP-STS:

(For detailed information about performing the following Oracle STS configuration tasks, see the Oracle STS documentation at http://www.oracle.com/technetwork/middleware/id-mgmt/overview/oraclests-166231.html.)

  1. Configure the Oracle STS /wss11user endpoint as follows:

    • Attach the policy with the URI sts/wss11_username_token_with message_protection_service_policy

    • Create an OWSM LRG UN Validation validation template to validate the incoming token and apply it to the endpoint.

  2. In Oracle STS, add the Microsoft ADFS 2.0 STS instance acting as the RP-STS as a relying partner party.

  3. Enable the Audience Restriction Condition in Oracle STS.

    This step is necessary because ADFS 2.0 requires the SAML assertion for a claim provider to have AudienceRestrictionUri set, and assertions issued by Oracle STS do not have this set by default.

  4. Configure a separate issuance template that issues 256 byte proof keys for Oracle STS to use.

14.1.2.4 Configure the Client

Follow these steps to configure the client:

  1. Create a policy from oracle/wss11_sts_issued_saml_hok_with_message_protection_client_policy and change it as follows:

    • Set Algorithm Suite to Basic256 instead of Basic128.

    • Set Derived Keys to enabled.

    • Set sts.in.order to the URI of the ADFS 2.0 STS endpoint followed by the Oracle STS endpoint; for example:

      http://m1.example.com/adfs/services/trust/13/issuedtokensymmetricbasic256;
      http://m2.example.com:14100/sts/wss11user
      
  2. Create a policy from oracle/sts_trust_config_client_template and change it as follows:

    • Set Port URI to the ADFS 2.0 STS endpoint; for example:

      http://m1.example.com/adfs/services/trust/13/issuedtokensymmetricbasic256
      
    • Set Client Policy URI to the policy you created in Step 1.

      oracle/wss11_sts_issued_saml_hok_with_message_protection_client_policy_adfs
      
  3. Create a policy from oracle/sts_trust_config_client_template and change it as follows:

    • Set Port URI to the Oracle STS endpoint; for example:

      http://m2.example.com:14100/sts/wss11user
      

14.2 WS-Trust with OpenSSO STS

The following sections provide end-to-end examples using WS-Trust with Open SSO Security Token Service (STS) server to configure various security scenarios.

14.2.1 Configuring OpenSSO STS

The following procedure describes the steps required to configure OpenSSO STS for use with each of the example scenarios described in this section.

  1. Log in to the OpenSSO STS instance.

  2. Navigate to Configuration > Global > Security Token Service.

  3. Under Security: Security Mechanism: Security Token Accepted by STS Services enable all options.

  4. Under the Credential for User Token section, add a new credential for the token with the name and password set as required. Set this to test/test.

  5. Under the On Behalf of Token section, select ldapService from the Authentication Chain for On Behalf of Token drop-down list.

  6. Under the Signing section, enable the following options:

    - Is Request Signature Verified

    - Is Response Signed Enabled (select Body and Timestamp)

  7. Under the Encryption section, enable the following options:

    - Is Request Decrypted (select Body and Header)

    - Is Response Encrypted

  8. Select AES from the Encryption Algorithm drop-down list, and select 128 from the Encryption Strength drop-down list.

  9. To support the WS-Security 1.1 Kerberos token with message protection requestor token, under the Kerberos Configuration section and configure the following values:

    Table 14-1 OpenSSO STS Kerberos Token With Message Protection Configuration

    Configure this property . . . To specify . . .

    Kerberos Domain Server

    Fully qualified hostname of the domain server.

    Kerberos Domain

    Domain name.

    Kerberos Service Principal

    Service principal name in the following format: <host>/<machine name>@<REALM NAME>

    Kerberos Key Tab File

    Location of the key tab file created for the STS.

    Is Verify Kerberos Signature

    Enable only when JDK 7 or later is used.


  10. To support SSL, perform the following steps:

    1. In the Token Issuance Attributes section, edit the SSL Endpoint based on your OpenSSO instance.

    2. Under Signing, enable the Disable signature validation when transport is secured with SSL option.

    3. Under Encryption, enable the Disable decryption when transport is secured with SSL option.

  11. To support SSL on the server hosting the OpenSSO STS:

    • On the WebLogic Server hosting the OpenSSO STS, to configure SSL, perform the steps described in "Configuring Keystores for SSL".

    • On Glassfish server hosting the Open SSO STS, perform the following steps:

      1. Generate a new key pair for the application server by issuing the following command:

        keytool -genkey -keyalg <algorithm for generating the key pair> -keystore keystore.jks -validity <days> -alias <alias_name>

        For example:

        keytool -genkey -keyalg RSA -keystore <glassfish_install_dir>/domains/<sts_deploy_domain>/config/keystore.jks -validity 365 -alias owsm

        When prompted for first and last name, enter the hostname of the machine for which the certificate is to be generated. Also enter the appropriate details for the other prompts.

      2. Generate a Certificate Signing Request (CSR) by issuing the following command:

        keytool -certreq -alias owsm -file owsm.csr -keystore keystore.jks -storepass changeit

        The request that is generated and written to the owsm.csr file needs to be submitted to a Certificate Authority in order to get a valid certificate. For example, the Certificate Management Server maintained by the OpenSSO QA team at https://mahogany.red.iplanet.com.

      3. Access the Certificate Management Server at https://mahogany.red.iplanet.com, click SSL Server in the left pane, and paste the contents of the .csr file, starting from BEGIN CERTIFICATE REQUEST and ending at END CERTIFICATE REQUEST, into the PKCS # 10 Request field.

        Fill out the other fields, as appropriate, and submit the request. Once the request is approved, the certificate can be retrieved from the retrieval tab on the same page.

      4. Copy the certificate content (PKCS # 7 format) starting from BEGIN CERTIFICATE to END CERTIFICATE into a file with .cert extension and import the server certificate into the <glassfish_install_dir>/domains/<sts_deploy_domain>/config/keystore.jks file by using the following keytool command:

        keytool -import -v -alias owsm -file owsm.cert -keystore keystore.jks -storepass changeit

        Enter YES when prompted if you trust the certificate.

      5. Access the Certificate Authority's SSL Certificate. Go to https://mahogany.red.iplanet.com and navigate to SSL Server -> Retrieval tab -> List Certificates -> Find. Click on the first Details button on the page and copy the Base 64 encoded certificate into another .cert file. For example: mahogany.cert

      6. Import this certificate with alias as "rootca" into the <glassfish_install_dir>/domains/<sts_deploy_domain>/config/cacerts.jks file, using the following command:

        keytool -import -v -alias rootca -file mahogany.cert -keystore cacerts.jks -storepass changeit

      7. The previous step may need to be repeated for client side truststore.jks file. Delete any existing rootca aliases from that file and import the new one as shown above (changing the location of the keystore file).

      8. To configure GlassFish with the new certificate, access the Administration Console at http://hostname:admin-port/. Navigate to Configuration -> HTTP Service -> http-listener2 (default SSL enabled port) -> SSL, and change the certificate nickname from s1as (self-signed cert) to owsm.

      9. Restart Glassfish.

14.2.2 SAML Holder-of-Key With Message Protection Scenario

The following procedure describes how to configure SAML holder-of-key with message protection using WS-Trust with OpenSSO STS. This example uses a WebLogic Web service and SOA Composite client to demonstrate the scenario.

To configure SAML holder-of-key with message protection using WS-Trust with OpenSSO STS:

  1. Configure OpenSSO STS, as described "Configuring OpenSSO STS".

  2. Configure the STS service policy following the steps described in "Configure a Policy for Automatic Policy Configuration".

    Make a copy of oracle/sts_trust_config_service_policy and edit the policy configuration, as described below, based on the requestor token type.

    To support WS-Security 1.0 username token with message protection requestor token:

    • orasp:port-uri="http://<host>:<port>/openssosts/sts/wss10un"

    • orasp:wsdl-uri="http://<host>:<port>/openssosts/sts/wss10un?wsdl" (Optional)

    To support WS-Security 1.0 username token over SSL with message protection requestor token:

    • orasp:port-uri="https://<host:ssl_port>/openssosts/sts/tlswss10un"

    • orasp:wsdl-uri="https://<host:ssl_port>/openssosts/sts/tlswss10un?wsdl" (Optional)

    To support WS-Security 1.0 X509 token with message protection requestor token:

    • orasp:port-uri="http://<host>:<port>/openssosts/sts/wss10x509"

    • orasp:wsdl-uri="http://<host>:<port>/openssosts/sts/wss10x509?wsdl" (Optional)

    To support WS-Security 1.1 Kerberos token with message protection requestor token:

    • orasp:port-uri="http://<host>:<port>/openssosts/sts/wss11kerberos"

    • orasp:wsdl-uri="http://<host>:<port>/openssosts/sts/wss11kerberos?wsdl" (Optional)

  3. Configure the Web service policy following the steps described in "Configure a Web Service for Automatic Policy Configuration".

    Attach the policy created in step 2 followed by the oracle/wss11_sts_issued_saml_hok_with_message_protection_service_policy to the WebLogic Web service. For more information, see "Attaching Policies Directly to a Single Subject Using Fusion Middleware Control".

    Note:

    By default, the oracle/wss11_sts_issued_saml_hok_with_message_protection_service_policy policy is configured with token type of SAML 1.1. If you wish to configure the token type to be SAML 2.0, you will need to make a copy of the policy and edit it, as described in "Cloning a Web Service Policy". (This value should match the client policy.)

  4. Configure the Web service client policy following the steps described in "Configure a Web Service Client for Automatic Policy Configuration".

    Attach the oracle/wss11_sts_issued_saml_hok_with_message_protection_client_policy policy to the SOA composite client and override the client configuration properties described in Table 19-99, "oracle/wss11_sts_issued_saml_hok_with_message_protection_client_template Properties", as required for your requestor token.

    The sts.auth.user.csf.key should be set to the user credentials available in the default OpenSSO STS configuration. Namely, username test, with password set to test. Though, it is not required to be set for the X509 requestor token.

    Note:

    For more information about overriding client configuration properties when attaching a policy, see "Attaching Policies Directly to Web Service Clients Using Fusion Middleware Control".

    By default, the oracle/wss11_sts_issued_saml_hok_with_message_protection_client_policy policy is configured with token type of SAML 1.1. If you wish to configure the token type to be SAML 2.0, you will need to make a copy of the policy and edit it, as described in "Cloning a Web Service Policy". (This value should match the service policy.)

14.2.3 SAML Sender Vouches with Message Protection Scenario

Note:

Before proceeding, it is recommended that you review "Configuring SAML Sender Vouches with WS-Trust".

The following procedure describes how to configure SAML sender vouches with message protection using WS-Trust with OpenSSO STS. This example uses a WebLogic Web service and SOA Composite client to demonstrate the scenario.

To configure SAML sender vouches with message protection using WS-Trust with OpenSSO STS:

  1. Configure OpenSSO STS, as described "Configuring OpenSSO STS".

  2. Configure the client-side STS policy following the steps described in "Manually Configuring the STS Config Policy From the Web Service Client: Main Steps".

    Note:

    Automatic Policy Configuration cannot be used for SAML sender vouches confirmation because the trust is between the Web service and the client. For more information, see "Configuring SAML Sender Vouches with WS-Trust".

    Make a copy of oracle/sts_trust_config_client_policy and edit the policy configuration based on the requestor token type.

    To support WS-Security 1.0 username token with message protection requestor token:

    • orasp:policy-reference-uri="oracle/wss10_username_token_with_message_protection_client_policy"

    • orasp:port-endpoint="http://<host>:<port>/openfm/SecurityTokenService/#wsdl.endpoint(SecurityTokenService/ISecurityTokenService_Port_UN_WSS10_SOAP12):

    • orasp:port-uri="http://<host>:<port>/openssosts/sts/wss10un"

    • orasp:sts-keystore-recipient-alias="test"

    To support WS-Security 1.0 username token over SSL with message protection requestor token:

    • orasp:policy-reference-uri="oracle/wss_username_token_over_ssl_client_policy"

    • orasp:port-endpoint="http://localhost:8080/openfm/SecurityTokenService/#wsdl.endpoint(SecurityTokenService/ISecurityTokenService_Port_TLS_UN_WSS10_SOAP12)"

    • orasp:port-uri="https://<host:ssl_port>/openssosts/sts/tlswss10un"

    • orasp:sts-keystore-recipient-alias="test"

    To support WS-Security 1.0 X509 token with message protection requestor token:

    • orasp:policy-reference-uri="oracle/wss10_x509_token_with_message_protection_client_policy"

    • orasp:port-endpoint="http://localhost:8080/openfm/SecurityTokenService/#wsdl.endpoint(SecurityTokenService/ISecurityTokenService_Port_X509_WSS10_SOAP12)"

    • orasp:port-uri="http://<host>:<port>/openssosts/sts/wss10x509"

    • orasp:sts-keystore-recipient-alias="test"

  3. Attach the oracle/wss11_saml_token_with_message_protection_service_policy policy to the WebLogic Web service (there is no corresponding issued token policy for SAML sender vouches scenarios) and override the keystore.enc.csf.key to specify the service encryption key alias and password.

    Note:

    By default, the oracle/wss11_saml_hok_with_message_protection_service_policy policy is configured with token type of SAML 1.1. If you wish to configure the token type to be SAML 2.0, you will need to make a copy of the policy and edit it, as described in "Cloning a Web Service Policy".

  4. Attach the policy created in step 2 followed by the oracle/ws11_sts_issued_saml_with_message_protection_client_policy policy to the SOA composite client and override the client configuration properties described in Table 19-101, "wss11_sts_issued_saml_with_message_protection_client_template Settings", as required for your requestor token.

    The "On Behalf Of" use case relies on the sts.auth.on.behalf.of.csf.key and on.behalf.of properties described in Table 19-101, "wss11_sts_issued_saml_with_message_protection_client_template Settings". For more information, see "On Behalf Of Use Cases".

    The on.behalf.of property should be set to true. The sts.auth.on.behalf.of.csf.key should be set to the user credentials available in the default Open SSO STS configuration that support the "on behalf of" use case. Namely, demo, with password set to changeit.

    Note:

    For more information about overriding client configuration properties when attaching a policy, see "Attaching Policies Directly to Web Service Clients Using Fusion Middleware Control".

  5. To grant permission to the client application to request a token from OpenSSO STS "on behalf of" a user, grant the WSIdentityPermission to wsm-agent-core.jar, as descried in "Set the WSIdentityPermission Permission".

14.2.4 SAML Bearer with Message Protection Scenario

The following procedure describes how to configure SAML bearer with message protection using WS-Trust with OpenSSO STS. This example uses a WebLogic Web service and SOA Composite client to demonstrate the scenario.

To configure SAML bearer with message protection using WS-Trust with OpenSSO STS:

  1. Configure OpenSSO STS. as described "Configuring OpenSSO STS".

  2. Configure the STS policy following the steps described in "Setting Up Automatic Policy Configuration for STS".

    Make a copy of oracle/sts_trust_config_service_policy and edit the policy configuration, as described below, based on the requestor token type.

    To support WS-Security 1.0 username token with message protection requestor token:

    • orasp:port-uri="http://<host>:<port>/openssosts/sts/wss10un"

    • orasp:wsdl-uri="http://<host>:<port>/openssosts/sts/wss10un?wsdl" (Optional)

    To support WS-Security 1.0 username token over SSL with message protection requestor token:

    • orasp:port-uri="https://<host:ssl_port>/openssosts/sts/tlswss10un"

    • orasp:wsdl-uri="https://<host:ssl_port>/openssosts/sts/tlswss10un?wsdl" (Optional)

    To support WS-Security 1.0 X509 token with message protection requestor token:

    • orasp:port-uri="http://<host>:<port>/openssosts/sts/wss10x509"

    • orasp:wsdl-uri="http://<host>:<port>/openssosts/sts/wss10x509?wsdl" (Optional)

    To support WS-Security 1.1 Kerberos token with message protection requestor token:

    • orasp:port-uri="http://<host>:<port>/openssosts/sts/wss11kerberos"

    • orasp:wsdl-uri="http://<host>:<port>/openssosts/sts/wss11kerberos?wsdl" (Optional)

  3. Configure the Web service policy following the steps described in "Configure a Web Service for Automatic Policy Configuration".

    Attach the policy created in step 2 followed by the oracle/wss11_sts_issued_saml_bearer_token_over_ssl_service_policy. For more information, see "Attaching Policies Directly to a Single Subject Using Fusion Middleware Control".

  4. Configure the Web service client policy following the steps described in "Configure a Web Service Client for Automatic Policy Configuration".

    Attach the oracle/ws11_sts_issued_saml_bearer_token_over_ssl_client_policy policy to the SOA composite client and override the client configuration properties described in Table 19-96, "oracle/wss_sts_issued_saml_bearer_token_over_ssl_client_template Properties", as required for your requestor token.

    The sts.auth.user.csf.key should be set to the user credentials available in the default OpenSSO STS configuration. Namely, username test, with password set to test. Though, it is not required to be set for the X509 requestor token.

    Note:

    For more information about overriding client configuration properties when attaching a policy, see "Attaching Policies Directly to Web Service Clients Using Fusion Middleware Control".