55 Configuring Custom Authentication

This chapter describes how to configure custom transport- and message-level authentication in Service Bus.

This chapter includes the following sections:

For instructions on configuring proxy or business service security, see Securing Business and Proxy Services.

55.1 Introduction to Custom Authentication in Oracle Service Bus

Service Bus supports client-specified custom authentication credentials for transport-level proxy and business service requests, and for message-level proxy service requests. The custom authentication credentials can be in the form of tokens, or a user name and password token combination. At the transport level, Service Bus accepts and attempts to authenticate a custom token passed to a proxy or business service in an HTTP header. At the message level, Service Bus can get the information from a SOAP header (for SOAP-based services) or the payload (for non-SOAP services).

You use the Proxy Service Definition Editor to configure a proxy service with the token type and the mechanism by which the token is passed. For business services, you define a custom authentication Java class, which you can then reference from the Business Service Definition Editor.

Note:

The custom authentication mechanisms work alone or in concert with the message-level security for web services described in Configuring Message-Level Security for Web Services. See Combining WS-Security with Custom User Name/Password and Tokens for information about using both types of security.

55.1.1 Understanding 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 Service Bus, a custom authentication token can be a user name and password or an opaque Identity Assertion token in a user-defined location in the request. A user name and password token is allowed in a SOAP header (for SOAP-based services) or in the payload of some non-SOAP proxy services. 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 services. The Service Bus domain must include an Identity Assertion provider that supports the token type.

Service Bus uses the authenticated user to establish a security context for the client. The security context established by authenticating a custom token or user name 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 a Service Bus user. Service Bus uses this resulting user name to establish a security context for the client.

55.1.2 Custom Authentication Token Use and Deployment

Custom authentication token support in Service Bus addresses two requirements. For the first requirement, a proxy service request has a user name and password somewhere in the message payload, for example in a SOAP header. Service Bus must get this user name and password and authenticate the user. For the second requirement, the message contains some kind of authentication token other than a user name and password, such as a secure-token-xyz token. The token may be in an HTTP header or in the message payload. 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 custom tokens and user name and password 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 MiddlewareAdministrator or Developer application role can configure custom token authentication (or the IntegrationDeployer or IntegrationAdministrator enterprise role). For information about roles, see "Role-Based Access in Oracle Service Bus" in Administering Oracle Service Bus.

55.1.3 Understanding Transport-Level Custom Authentication

You can authenticate client requests at the transport-level using custom authentication tokens, which can be specified in an HTTP header. You configure transport-level custom authentication on the Transport Details page of the service definition editor. The options for HTTP and HTTPS services are:

  • None

  • Basic

  • Custom Authentication

  • Client Certificate (HTTPS Only)

These are mutually exclusive options.

If you choose custom authentication for a proxy service, you must also specify the token type and the name of the HTTP header that is to carry the token. If you choose custom authentication for a business service, you must also specify the custom authenticator Java class. The custom authentication token can be any active token type, previously configured for an Identity Assertion provider, that is carried in an HTTP header.

55.1.3.1 Import/Export 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., 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.

55.1.4 Understanding Message-Level Custom Authentication

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 user name and password. 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 configure message-level custom authentication on the Security page (Oracle Service Bus Console) or the Security Settings page (JDeveloper) of the Proxy Service Definition Editor, which includes specifying the token type and the mechanism by which the token is passed.

The following proxy service message-level authentication mechanisms are 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 user name 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)

55.1.5 Propagating the Identity Obtained From Custom Authentication Tokens

The security context established using a custom token or custom user name/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 using 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 user name/password.

If a custom user name/password is used, the user name/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.

55.1.6 Combining WS-Security with Custom User Name/Password and Tokens

You can secure Service Bus proxy services with transport-level security (for example, HTTPS) or message-level security (for example, WS-Security (WSS) and custom tokens), or a combination of both. For example, client requests can be authenticated at the transport level with custom tokens in HTTP headers, and at the message level with WS-Security tokens, custom tokens, or user name/passwords, except in the WS-Security header.

There is one 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 examples:

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

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

55.2 Format of XPath Expressions

The configuration for both custom user name/password and custom token authentication is similar. In both cases, you specify XPath expressions so Service Bus can 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()

55.3 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 Service Bus user name, and returns the user name. Identity is said to be "asserted" when the token is mapped to the user name. Service Bus then uses this user name to establish a security context for the client.

If you want the proxy or business service to consume a custom token, check the provided WebLogic Server Identity Assertion providers to see if one meets your needs. 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 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 a 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 for a proxy service configured for custom authentication is shown in Figure 55-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 user name, and returns the user name.
  5. Service Bus then continues the authentication process with this user name and, if successful, obtains the authenticated subject.
  6. Service Bus creates the security context. The security context established by authenticating a custom token or user name and password can be used as the basis for outbound credential mapping and access control.

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

Figure 55-1 Identity Assertion and Custom Tokens in a Proxy Service

Description of Figure 55-1 follows
Description of "Figure 55-1 Identity Assertion and Custom Tokens in a Proxy Service"

55.3.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.

55.3.2 Configuring a Custom Token Type in an Identity Assertion Provider

The steps required to complete these tasks are provided in the following WebLogic Server documents:

55.3.2.1 How to Configure a Custom Token Type in an Identity Assertion Provider

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 WebLogic Server documentation to actually complete the tasks.

To configure a custom token type in an Identity Assertion provider:

  1. Create the new token types. See "How to Create New Token Types" in Developing Security Providers for Oracle WebLogic Server.
  2. Create the runtime classes. See "Create Runtime Classes Using the Appropriate SSPIs" in 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 the MBean type. See "Generate an MBean Type Using the WebLogic MBeanMaker in Developing Security Providers for Oracle WebLogic Server.
  4. Configure the custom Identity Assertion provider. See "Configure the Custom Identity Assertion Provider Using the Administration Console" in Developing Security Providers for Oracle WebLogic Server.
  5. Define the active token type. See "Configuring Identity Assertion Providers" in Administering Security for Oracle WebLogic Server and "How to Make New Token Types Available for Identity Assertion Provider Configurations" in Developing Security Providers for Oracle WebLogic Server.

55.3.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 the following example. For more information about MDFs and MBean types, see "Generate an MBean Type Using the WebLogic MBeanMaker" in Developing Security Providers for Oracle WebLogic Server.

Example - 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 the following example.

Example - 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.

55.4 Configuring Custom Authentication Transport-Level Security

Before you can configure your HTTP proxy or business service for transport-level security, you must configure, or create and configure, an Identity Assertion provider that understands the token type you plan to use.

55.4.1 How to Create a Custom Authentication Class for Outbound

For outbound custom authentication, you need to create a custom Java class that defines the custom logic. The following interfaces provide the methods you need to implement custom authentication for business services:

  • com.bea.wli.sb.transports.http.OutboundAuthentication

  • com.bea.wli.sb.transports.http.HttpUrlConnectionFactory

The custom authenticator must implement the doOutboundAuthentication method of the OutboundAuthentication interface. The custom authenticator can set the authentication headers and read the response from the target service for the initial and the intermediate transactions. For the final step it is expected that the custom authenticator sets only the authentication headers and does not establish the connection with the target service. Service Bus will send the payload along with the authentication headers in the final step. The custom authenticator should not manipulate the payload.

55.4.2 How to Configure Transport-Level Custom Authentication

The following procedure provides the high-level steps you need to complete to define custom authentication at the transport level. It includes links more detailed instructions.

To configure transport-level custom authentication:

  1. Determine which custom token format to use.

  2. Determine if an existing provider meets your needs. For guidance, see "Choosing an Authentication Provider" in Administering Security for Oracle WebLogic Server.

  3. Configure, or create and configure, an Identity Assertion provider that supports the token format. See the following for instructions:

  4. The Identity Assertion provider maps the token to a user name. Add the client's user name in Fusion Middleware Control.

  5. For proxy services, do the following on the Transport Details page of the Proxy Service Definition Editor:

    1. By Authentication, select Custom Authentication.

    2. In the Authentication Header field under Advanced Options (or Advanced Settings), enter the message header where Service Bus can find the token.

    3. In the Authentication Token Type, enter the token type expected by this endpoint.

  6. For business services, create and compile the custom authenticator Java class, and add the class to the system classpath.

  7. For business services, do the following on the Transport Details page of the Business Service Definition Editor:

    1. By Authentication, select Custom Authentication.

    2. In the HTTP Custom Authentication Class Name field, enter the name of the Java class that defines the custom authentication.

  8. Save and activate your changes.

55.5 Configuring Message-Level Custom Authentication

Before you can configure custom authentication message-level security for a proxy service, you must first configure, or create and configure, an authentication provider or Identity Assertion provider that understands the token type you plan to use.

55.5.1 How to Configure Message-Level Custom Authentication for Proxy Services

The following procedure provides the high-level steps you need to complete to define custom authentication at the transport level. It includes links more detailed instructions.

Note:

The provider you use must also understand any context properties that you want to provide. 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.

To configure message-level custom authentication:

  1. Determine which custom user name/password or token format to use.
  2. Determine if an existing provider meets your needs. For guidance, see "Choosing an Authentication Provider" in Administering Security for Oracle WebLogic Server.
  3. Configure, or create and configure, an authentication provider or Identity Assertion provider that supports the user name/password or token format, respectively. See the following for instructions:
  4. Add the client's user name in Fusion Middleware Control.
  5. In Service Bus, define the custom token or user name and password in the security settings for the proxy service. Optionally, specify context properties for the provider.