54 Configuring Custom Authentication

Oracle Service Bus supports client-specified custom authentication credentials for both transport- and message-level proxy service requests. The custom authentication credentials can be in the form of tokens, or a username and password token combination.

Oracle Service Bus accepts and attempts to authenticate a custom token passed to a proxy service in an HTTP header, SOAP header (for SOAP-based proxy services) or in the payload (for non-SOAP proxy services). You use the proxy service configuration wizard to configure the proxy service with the mechanism by which the token is passed, and the token type.

Oracle Service Bus also accepts and attempts to authenticate a username and password token passed in a SOAP header (for SOAP based proxy services), or in the payload for non-SOAP proxy services. You use the proxy service configuration wizard to configure the proxy service with the mechanism by which the username and password are passed.

Note:

The custom authentication mechanisms work alone or in concert with the message-level security for Web services described in Chapter 52, "Configuring Message-Level Security for Web Services." See Section 54.9, "Combining WS-Security with Custom Username/Password and Tokens" for information about using both types of security.

The following custom authentication mechanisms are supported:

This section describes the following custom authentication topics:

54.1 What Are Custom Authentication Tokens?

An authentication token is some data, represented as a string or XML, that identifies an entity (user or process), such as an X509 client certificate. Typically, authentication tokens are designed to be used within specific security protocols. Some authentication tokens are cryptographically protected and some are not. Some authentication tokens carry key material.

In the context of Oracle Service Bus, a custom authentication token can be a username/password or an opaque identity assertion token in a user-defined location in the request. A username/password token is allowed in a SOAP header (for SOAP-based services) or in the payload of some non-SOAP proxy service. An identity assertion token is allowed in an HTTP header, in a SOAP header (for SOAP-based services), or in the payload of some non-SOAP proxy service. The Oracle Service Bus domain must include an Identity Assertion provider that supports the token type.

Oracle Service Bus uses the authenticated user to establish a security context for the client. The security context established by authenticating a custom token or username and password can be used as the basis for outbound credential mapping and access control.

To authenticate and authorize clients who supply tokens for authentication, you must configure an Identity Assertion provider that maps the client's credential to an Oracle Service Bus user. Oracle Service Bus uses this resulting username to establish a security context for the client.

54.1.1 Custom Authentication Token Use and Deployment

The addition of custom authentication token support in Oracle Service Bus addresses two customer needs. In the first scenario, a proxy service request has a username/password somewhere in the message payload, for example in a SOAP header. Oracle Service Bus must get this username/password and authenticate the user.

In the second scenario, the message contains some kind of authentication token (other than username/password), such as a secure-token-xyz token. The token may be in an HTTP header or in the message payload. Oracle Service Bus must get the token and authenticate it. In either case, a security context is established if authentication succeeds.

Most security-related configuration is typically done at deployment time, and custom authentication fits that model: it can be configured directly on the production environment at deployment time. Alternatively, you can configure authentication during staging and import it into the production environment.

Custom authentication, which includes both username/password tokens and custom tokens, is an integral part of the proxy service definition. When a proxy service is exported, any configuration of custom tokens is included in the jar file. When a new version of the proxy service is imported, the previous configuration is overwritten with whatever configuration is contained in the jar file.

Only users in the IntegrationDeployer or IntegrationAdministrator roles can configure custom token authentication. Users in the IntegrationOperator or IntegrationMonitor roles have read-only access to this configuration.

54.2 Understanding Transport-Level Custom Authentication

You can authenticate client requests at the transport-level via custom authentication tokens. You specify a custom token in an HTTP header. The HTTP (and HTTPS) configuration page of the service definition wizard allows you to configure client authentication. The options for HTTP and HTTPS proxy services are:

  • None

  • Basic

  • Custom Authentication

  • Client Certificate (HTTPS Only)

These are mutually exclusive options.

If you choose custom authentication, you must also specify the name of the HTTP header that is to carry the token, and the token type.

The steps for configuring transport-level custom credentials are described in Section 2.3, "Working with Proxy Services."

The custom authentication token can be any active token type, previously configured for an Identity Assertion provider, that is carried in an HTTP header.

You need to configure, or create and configure, an Identity Assertion provider that handles the token type you plan to use. See Section 54.5, "Configuring Identity Assertion Providers for Custom Tokens."

After you have configured the transport-level custom credentials, you can then additionally configure the message level security configuration, as described in Chapter 52, "Configuring Message-Level Security for Web Services."

54.2.1 Importing and Exporting and Transport-Level Custom Token Authentication

Transport-level custom authentication tokens are published to the UDDI. The client-auth property is present in the instanceParms of the HTTP or HTTPS transport attributes whenever authentication is configured. As described in "Transport Attributes" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus, the possible values of client-auth are BASIC, CLIENT-CERT and CUSTOM-TOKEN. Whenever the value is CUSTOM-TOKEN, two additional properties are present: token-header and token-type.

Note:

Oracle Service Bus business service definitions do not support custom token authentication. If you import a service from UDDI that has client-auth equal to CUSTOM-TOKEN, the service is imported as if it does not have any authentication configuration.

54.3 Understanding Message-Level Custom Authentication

Oracle Service Bus supports client-specified custom authentication credentials for proxy service message-level requests. The custom authentication credentials can be in the form of a custom token, or a username and password.

Oracle Service Bus accepts and attempts to authenticate a custom token passed to a proxy service in a SOAP header (for SOAP-based proxy services), or in the payload (for non-SOAP proxy services). You use the proxy service configuration wizard to configure the proxy service with the mechanism by which the token is passed, and the token type.

Oracle Service Bus also accepts and attempts to authenticate a username and password token passed in a SOAP header (for SOAP based proxy services), or in the payload for non-SOAP proxy services. You use the proxy service configuration wizard to configure the proxy service with the mechanism by which the username and password are passed.

The following proxy service message-level authentication mechanisms are now supported:

  • For SOAP-based proxy services

    • Custom token in a SOAP header

    • Username/password in a SOAP header

  • For non-SOAP-based proxy services

    • Custom token in the payload of any XML-based proxy services

    • Username/password in the payload of any XML-based proxy services

Message-level custom tokens and message-level username and password are supported on proxy services of the following binding types:

  • WSDL-SOAP

  • WSDL-XML

  • Abstract SOAP

  • Abstract XML

  • Mixed – XML (in the request)

  • Mixed – MFL (in the request)

54.4 Format of XPath Expressions

The configuration for both custom username/password and custom token is similar. In both cases, you specify XPath expressions that enable Oracle Service Bus to locate the necessary information. The root of these XPath expressions is as follows:

  • Use soap-env:Envelope/soap-env:Header if the service binding is anySOAP or WSDL-SOAP.

  • Use soap-env:Body (specifically, the contents of the $body variable) if the service binding is not SOAP based.

    Note:

    All XPath expressions must be in a valid XPath 2.0 format. The XPath expressions must use the XPath "declare namespace" syntax to declare any namespaces used, as follows: 
    declare namespace ns='http://webservices.mycompany.com/MyExampleService';

    For example,

    declare namespace y="http://foo";./y:my-custom-token/text()

54.5 Configuring Identity Assertion Providers for Custom Tokens

An Identity Assertion provider is a specific form of Authentication provider that allows users or system processes to assert their identity using tokens. A client's identity is established through the use of client-supplied tokens. The Identity Assertion provider validates the token. If the token is successfully validated, the Identity Assertion provider maps the token to an Oracle Service Bus username, and returns the username. Identity is said to be "asserted" when the token is mapped to the username. Oracle Service Bus then uses this user name to establish a security context for the client.

If you want the proxy service to consume a custom token, check the provided Oracle WebLogic Server Identity Assertion providers to see if one meets your needs. Oracle WebLogic Server includes a broad array of Identity Assertion providers, including the following:

  • The WebLogic Identity Assertion provider validates X.509 and IIOP-CSIv2 tokens and optionally can use a user name mapper to map that token to a user.

  • The SAML Identity Assertion provider, which acts as a consumer of SAML security assertions.

If you want the Oracle Service Bus proxy service to consume a custom token that is not handled by one of the bundled Identity Assertion providers, for example a secure-token-xyz token, you (or a third-party) must first write an Oracle WebLogic Server Identity Assertion provider that supports the token type and use the Oracle WebLogic Server Administration Console to add that provider to the security realm.

You develop Identity Assertion providers to support the specific types of custom tokens that you will be using to assert the identities of users. You can develop an Identity Assertion provider to support multiple token types. While you can have multiple Identity Assertion providers in a security realm with the ability to validate the same token type, only one Identity Assertion provider can actually perform this validation.

The Identity Assertion process is shown in Figure 54-1, and works as follows:

  1. The proxy service gets the authentication token from the inbound request.

  2. The token is passed to an Identity Assertion provider that is responsible for validating tokens of that type and that is configured as "active."

  3. The Identity Assertion provider validates the token.

  4. If the token is successfully validated, the Identity Assertion provider maps the token to a username, and returns the username.

  5. Oracle Service Bus then continues the authentication process with this username and, if successful, obtains the authenticated subject.

  6. Oracle Service Bus creates the security context. The security context established by authenticating a custom token or username and password can be used as the basis for outbound credential mapping and access control.

See "Identity Assertion and Tokens" in Oracle Fusion Middleware Understanding Security for Oracle WebLogic Server for additional information.

Figure 54-1 Identity Assertion and Custom Tokens

Description of Figure 54-1 follows
Description of "Figure 54-1 Identity Assertion and Custom Tokens"

54.5.1 Object Type of Custom Tokens

For transport-level identity assertion, the header value is passed as a java.lang.String to the identity assertion providers. For message-level identity assertion, the XPath expression is evaluated as follows:

  • If the XPath expression returns multiple nodes, an error is raised and identity assertion is not called.

  • If the XPath expression returns an empty result, identity assertion is called with a null argument.

  • If the XPath expression returns a single token of type TEXT or ATTR (See XmlCursor.TokenType at http://xmlbeans.apache.org/docs/2.0.0/reference/org/apache/xmlbeans/XmlCursor.TokenType.html), the string value of the text node or attribute is passed (as returned by XmlCursor.getStringValue()). Otherwise, a single XmlObject is passed.

54.5.2 Configuring a Custom Token Type in an Identity Assertion Provider

The steps required to complete these tasks are described in detail in the following Oracle WebLogic Server documents:

For your convenience, the steps for creating custom token types for an Identity Assertion provider and configuring that provider in the Oracle WebLogic Server Administration Console are briefly listed here. However, you will need to consult the Oracle WebLogic Server documentation to actually complete the tasks.

54.5.2.1 Steps for Configuring a Custom Token Type in an Identity Assertion Provider

You can develop a custom Identity Assertion provider by following these steps:

  1. Create the new token types. See "How to Create New Token Types" in Oracle Fusion Middleware Developing Security Providers for Oracle WebLogic Server.

  2. "Create Runtime Classes Using the Appropriate SSPIs," described in Oracle Fusion Middleware Developing Security Providers for Oracle WebLogic Server. That section shows the SampleIdentityAsserterProviderImpl.java class, which is the runtime class for the sample Identity Assertion provider.

  3. "Generate an MBean Type Using the WebLogic MBeanMaker," described in Oracle Fusion Middleware Developing Security Providers for Oracle WebLogic Server.

  4. "Configure the Custom Identity Assertion Provider Using the Administration Console," described in Oracle Fusion Middleware Developing Security Providers for Oracle WebLogic Server.

  5. Define the active token type. For this task, see "Configuring Identity Assertion Providers" in Oracle Fusion Middleware Securing Oracle WebLogic Server and "How to Make New Token Types Available for Identity Assertion Provider Configurations" in Oracle Fusion Middleware Developing Security Providers for Oracle WebLogic Server.

54.5.2.2 Setting the Supported and Active Types in the MBean

When you configure a custom Identity Assertion provider, the Supported Types field displays a list of the token types that the Identity Assertion provider supports. You enter zero or more of the supported types in the Active Types field.

The content for the Supported Types field is obtained from the SupportedTypes attribute of the MBean Definition File (MDF), which you use to generate your custom Identity Assertion provider's MBean type. An example from the sample Identity Assertion provider is shown in Example 54-1. For more information about MDFs and MBean types, see "Generate an MBean Type Using the WebLogic MBeanMaker" in Oracle Fusion Middleware Developing Security Providers for Oracle WebLogic Server.

Example 54-1 SampleIdentityAsserter MDF: SupportedTypes Attribute

<MBeanType>
...   
<MBeanAttribute 
Name = "SupportedTypes" 
Type = "java.lang.String[]"
Writeable = "false"
Default = "new String[] {&quot;SamplePerimeterAtnToken&quot;}"
/>
...
</MBeanType>

Similarly, the content for the Active Types field is obtained from the ActiveTypes attribute of the MBean Definition File (MDF). You can default the ActiveTypes attribute in the MDF so that it does not have to be set manually with the Oracle WebLogic Server Administration Console. An example from the sample Identity Assertion provider is shown in Example 54-2.

Example 54-2 SampleIdentityAsserter MDF: ActiveTypes Attribute with Default

<MBeanAttribute
Name= "ActiveTypes"
Type= "java.lang.String[]"
Default = "new String[] { &quot;SamplePerimeterAtnToken&quot; }"
/>

While defaulting the ActiveTypes attribute is convenient, you should only do this if no other Identity Assertion provider will ever validate that token type. Otherwise, it would be easy to configure an invalid security realm (where more than one Identity Assertion provider attempts to validate the same token type). Best practice dictates that all MDFs for Identity Assertion providers turn off the token type by default; then an administrator can manually make the token type active by configuring the Identity Assertion provider that validates it.

54.6 Configuring Custom Authentication Transport-Level Security

You ultimately configure custom authentication for transport-level security. However, before you get to this step of the process, you must first configure, or potentially create and configure, an Identity Assertion provider that understands the token type you plan to use.

The steps required to complete these tasks are described in detail in the following Oracle WebLogic Server documents:

54.6.1 Steps for Configuring Custom Authentication Transport-Level Security

The steps for configuring custom authentication transport-level security are as follows:

  1. Determine which custom token format you will be using.

  2. Determine if an existing provider meets your needs. "Choosing an Authentication Provider" in Oracle Fusion Middleware Securing Oracle WebLogic Server offers guidance on this task.

  3. Configure, or create and configure, an Identity Assertion provider that supports the token format.

  4. The Identity Assertion provider maps the token to a username. Add the client's username to the Oracle Service Bus Security Configuration module.

  5. On the protocol-dependent transport configuration page, specify the Authentication Header where Oracle Service Bus is to find the token and the Authentication Token Type. Only those token types that are currently active for a configured Identity Assertion provider are displayed.

54.7 Configuring Custom Authentication Message-Level Security

You ultimately configure custom authentication message-level security. However, before you get to this step of the process, you must first configure, or potentially create and configure, an Authentication provider or Identity Assertion provider that understands the token type you plan to use.

The steps required to complete these tasks are described in detail in the following Oracle WebLogic Server documents:

  • If one of the bundled Authentication or Identity Assertion providers meets your needs, see "Configuring Authentication Providers" in Oracle Fusion Middleware Securing Oracle WebLogic Server for instructions on how to configure this Authentication provider in the Oracle WebLogic Server Administration Console.

  • "How to Create New Token Types" in Oracle Fusion Middleware Developing Security Providers for Oracle WebLogic Server describes how to create custom token types for an identity assertion provider.

  • "Configuring Identity Assertion Providers" in Oracle Fusion Middleware Securing Oracle WebLogic Server describes how to configure identity assertion providers in the Oracle WebLogic Server Administration Console.

54.7.1 Steps for Configuring Custom Authentication Message-Level Security

The steps for configuring custom authentication message-level security are as follows:

  1. Determine which custom username/password or token format you will be using.

  2. Determine if an existing provider meets your needs. "Choosing an Authentication Provider" in Oracle Fusion Middleware Securing Oracle WebLogic Server offers guidance on this task.

    If you specify any Context Properties you will probably need to create your own provider because the provider must know which property names to expect.

  3. Configure, or create and configure, an authentication provider or identity assertion provider that supports the username/password or token format, respectively. This provider must also understand any Context Properties that you want to provide.

  4. Add the client's user name to the Oracle Service Bus Security Configuration module.

  5. On the Security page, configure a new or existing proxy service for the User Name XPath, User Password XPath, or Token Type and Token Path, as appropriate.

  6. Specify the Property Name and Value Selector of any Context Properties that you want to provide.

54.8 Propagating the Identity Obtained From Custom Authentication Tokens

The security context established via a custom token or custom username/password is in no way unique, and you can use it for credential mapping. If you implement both transport-level authentication and message-level authentication, the message-level security context is always used for credential mapping and identity propagation.

For example, if the proxy service authenticates the client via a secure-token-xyz token in a SOAP header, the authenticated subject is used during any mapped service account lookup. The subject is also used when generating SAML tokens on outbound messages. Java callouts can also run under the authentication context associated with a custom token or custom username/password.

If a custom username/password is used, the username/password in the custom token can be used for outbound HTTP BASIC or outbound WS-Security Username Token authentication if a pass-through service account is used.

54.9 Combining WS-Security with Custom Username/Password and Tokens

You can secure Oracle Service Bus proxy services with either transport-level security (for example, HTTPS) and message-level security (for example, WS-Security and custom tokens), or a combination of both. That is, you can configure an Oracle Service Bus proxy service with both transport-level authentication and message-level authentication.

For example, client requests can be authenticated at the transport level with custom tokens in HTTP headers, and at the message level with WSS security tokens, custom tokens, or username/passwords, except in the Web Services Security header.

However, note the following restriction: Although it is possible to combine WS-Security and message-level custom tokens, the WS-Security policy must not require proxy service authentication based on WS-Security tokens. Message-level custom tokens and WS-Security proxy service authentication are mutually exclusive.

Consider the following distinction:

  • It is allowable to configure a proxy service that expects a custom token of type MyToken in SOAP header <foo:MyToken> and that has a WS-Security policy that requires signing or encryption of some message parts (for example, the <foo:MyToken> header and SOAP body).

  • It is not allowable to configure a proxy service that requires a custom token in header <foo:MyToken> and that also has a WS-Security policy that requires a SAML token or any other form of authentication.