Oracle Service Bus supports the use of Security Assertion Markup Language (SAML) policies for exchanging authentication and authorization information between clients and services.
This chapter provides guidance on using SAML with Oracle Service Bus. You can use SAML with either the WLS 9.2 policy framework or with Oracle Web Services Manager. Oracle recommends that you use Oracle Web Services Manager for service security, as described in Chapter 51, "Securing Oracle Service Bus with Oracle Web Services Manager."
For detailed instructions on setting up your environment to use SAML, see "Configuring SAML" in the Oracle Fusion Middleware Security and Administrator's Guide for Web Services and the SAML configuration topics in Oracle Fusion Middleware Securing Oracle WebLogic Server. The SAML configuration steps in those guides are a prerequisite to using SAML in Oracle Service Bus.
This chapter includes the following topics:
Section 54.2, "Configuring SAML Pass-Through Identity Propagation"
Section 54.3, "Authenticating SAML Tokens in Proxy Service Requests"
Section 54.4, "Configuring SAML Authentication with Service Bus (SB) Transport"
Section 54.6, "Troubleshooting SAML with Oracle Service Bus"
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.
This technique requires the business service to be a Web service with WS-Policy statements that require authentication using SAML tokens.
To configure SAML credential mapping:
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 Oracle 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
Configure the proxy service to include a SAML token in the WS-Security header of its outbound request.
Note:
If you configured the proxy service for dynamic routing, the message context determines the target URL for the request. If the assertion is signed, you must configure the certificate.When the proxy service sends its outbound request, it generates a SAML assertion on behalf of the client. When the business service processes the WS-Security header, it validates the SAML assertion, creates a security context for the identity in the SAML assertion, and invokes the Web service with this security context.
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 Section 53.3.2, "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 Section 53.4, "Configuring Business Service Message-Level Security: Main Steps."
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:
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.
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.
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 Oracle 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.
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 the Oracle Fusion Middleware Security and Administrator's Guide for Web Services.
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 "Overview of Application Development with CSF" in Oracle Fusion Middleware Application Security Guide.
To prevent malicious access to the identity-switching functionality, you must grant special permissions to the resources that perform identity switching. For example, in Oracle Service Bus, you give permissions to the project containing the identity-switching business service.
Use the Oracle Enterprise Manager Fusion Middleware Control to give the Oracle Service Bus project the proper permissions, as described in "Set the WSIdentityPermission Permission" in the Oracle Fusion Middleware Security and Administrator's Guide for Web Services. 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 Oracle Service Bus project containing the business service
Permission Actions – assert
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 the Oracle Fusion Middleware Security and Administrator's Guide for Web Services.
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 Oracle 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 Oracle Fusion Middleware Securing Oracle WebLogic Server.