54 Using SAML with Oracle Service Bus

This chapter describes how to use Security Assertion Markup Language (SAML) policies for exchanging authentication and authorization information between clients and services in Service Bus.

You can use SAML with either the WLS 9 policy framework or with Oracle Web Services Manager. Oracle recommends that you use Oracle Web Services Manager for service security, as described in Securing Oracle Service Bus with Oracle Web Services Manager.

This chapter includes the following topics:

• Mapping Identity to a SAML Token

• Configuring SAML Pass-Through Identity Propagation

• Authenticating SAML Tokens in Proxy Service Requests

• Configuring SAML Authentication with Service Bus (SB) Transport

• Using SAML Identity Switching

• Troubleshooting SAML with Oracle Service Bus

54.1 Mapping Identity to a SAML Token

If your clients do not provide SAML tokens but your business services require them, you can configure a proxy service to map the client's identity to a SAML token.

To configure SAML credential mapping:

1. Configure a proxy service to authenticate clients using any of the following techniques:

   • HTTP or HTTPS basic (client provides user name and password in the request)

   • HTTPS client certificate

   • Message-level authentication (using any of the supported token profiles)

     If a client request includes a WS-Security security header, you must configure the proxy service to process this header on the proxy service side of the message. In Service Bus, you cannot add a SAML header (or any other WS-Security header) to a SOAP envelope that already contains a WS-Security header, neither can you add SAML (or other) security tokens to an existing security header.

   • Third-party authentication

   When the proxy service authenticates the user, the proxy automatically generates a Subject before forwarding the message to a business service.

2. Configure the business service to include a SAML client policy. The policy generates a SAML token for the authenticated user in the Subject.

For a list of Oracle Web Services Manager SAML policies supported with Service Bus, see Predefined Policies and Unsupported Assertions.

Note:

The procedure in this section assumes a proxy-to-business service invocation. When your use case involves proxy-to-proxy invocations prior to the business service invocation, it is helpful to understand how Service Bus handles security headers. For that information, see Using OWSM Security with Local Proxy Services.

54.2 Configuring SAML Pass-Through Identity Propagation

If your clients provide SAML tokens to a pass-through proxy service, you can propagate the client's SAML token to the business service.

This technique requires the business service to be a web service with policy statements that require authentication using SAML tokens.

To configure SAML pass-through identity propagation:

• Proxy Service – Configure a pass-through proxy service as described in Creating a Pass-Through Proxy Service: Main Steps.

• Business Service – Configure a SOAP-HTTP or SOAP-JMS business service with policy statements that require authentication using SAML tokens, as described in Configuring Business Service Message-Level Security: Main Steps.

54.3 Authenticating SAML Tokens in Proxy Service Requests

If your clients provide SAML tokens to an active intermediary proxy service, you can configure the proxy service to assert the client's identity.

To configure a proxy service to use SAML tokens to authenticate clients:

1. When configuring the Identity Assertion provider, note the following requirements:

   • The confirmation method from the policy must match the SAML profile in the SAML asserting party.

   • Specify the asserting party target URL to be the relative URL of the proxy service (omitting the protocol and host information).

   • For signed assertions, add the certificate to the Identity Asserter registry.

2. Create an active intermediary proxy service that communicates over the HTTP, HTTPS, or JMS protocol. The proxy service must be a web service with a policy statement that requires authentication and accepts SAML tokens.

   A proxy service that communicates over the "local" transport type cannot use a SAML token profile to authenticate.

54.4 Configuring SAML Authentication with Service Bus (SB) Transport

If you are using SAML-based authentication with the SB transport, follow these configuration requirements.

• On the asserting party, configure the SAML Credential mapper with URI http://openuri.org/sb_proxy_uri, where sb_proxy_uri is the SB transport service URI.

• When configuring the Identity Assertion provider on the Service Bus side (the relying party), use the asserting party target URL as the proxy endpoint URI. Do not include the protocol and host information. For example, /sb_proxy_uri.

54.5 Using SAML Identity Switching

Oracle Web Services Manager provides a wss11_saml_token_identity_switch_with_message_protection_client_policy that lets you perform identity switching.

The policy, which you attach to a business service, propagates a different identity than the one based on the authenticated Subject from the proxy service. For more information about the policy, see Configuring SAML Web Service Clients for Identity Switching in Securing Web Services and Managing Policies with Oracle Web Services Manager.

If you set the policy property subject.precedence = false and provide a credential store format (CSF) key for the identity you want to switch to, the business service ignores the current subject and creates a SAML token with the credentials in the csf-key.

If you set subject.precedence = true, the current subject is used to create the SAML token. However, if the subject is anonymous, Oracle Web Services Manager attempts to use the csf-key to perform the identity switching.

For information on working with CSF, see Developing with the Credential Store Framework in Securing Applications with Oracle Platform Security Services.

54.5.1 Protecting the Identity-Switching Resource

To prevent malicious access to the identity-switching functionality, you must grant special permissions to the resources that perform identity switching. For example, in Service Bus, you give permissions to the project containing the identity-switching business service.

Use Fusion Middleware Control to give the Service Bus project the proper permissions. Using that topic for guidance, enter the following information in the permissions fields:

• Permission Class: oracle.wsm.security.WSIdentityPermission

• Resource Name: Name (not the path) of the Service Bus project containing the business service

• Permission Actions: assert

54.6 Troubleshooting SAML with Oracle Service Bus

This section provides answers to some commonly asked troubleshooting questions.

Question: I am trying to propagate my proxy service transport identity to a destination business service and keep receiving error, Unable to add security token for identity. What does this mean?

Answer: There are various causes for this error. Generally this means one of the following problems:

• The SAML Credential Mapper is not configured correctly. Double check that the configuration is in accordance with the instructions in Configuring SAML in Securing Web Services and Managing Policies with Oracle Web Services Manager.

• Another common source of this error is that there is no subject information to propagate. To generate a SAML token, you must have a transport-level or message-level subject. Make sure that the client has a subject. This can be done by inspecting the $security message context variable.

Question: I am trying to propagate my proxy service transport identity to a destination business service using SAML holder-of-key and keep receiving error, Failure to add signature. What does this mean?

Answer: There are various causes for this error, but most likely is that the credentials are not configured for the business service's service key provider. When Service Bus generates an outbound holder-of-key assertion, it also generates a digital signature over the message contents, so that the recipient can verify not only that a message is received from a particular user but that the message has not been tampered with. To generate the signature, the business service must have a service key provider with a digital signature credential associated with it.

Question: I am trying to configure an active intermediary proxy service that receives SAML identity tokens and keep receiving errors that look like: The SAML token is not valid. How do I fix this?

Answer: This is generally caused by a missing SAML Identity Asserter or SAML Identity Asserter asserting party configuration for the proxy service. For a proxy service to receive SAML assertions in active intermediary mode, it must have a SAML Identity Asserter configured. For more details, see Configuring a SAML Identity Assertion Provider in Administering Security for Oracle WebLogic Server.