Identity Assertion Providers

4 Identity Assertion Providers

This chapter describes identity assertion provider concepts and functionality, and provides step-by-step instructions for developing a custom identity assertion provider.

An identity assertion provider is a specific form of authentication provider that allows users or system processes to assert their identity using tokens (in other words, perimeter authentication). identity assertion providers enable perimeter authentication and support single sign-on. You can use an identity assertion provider in place of an authentication provider if you create a LoginModule for the identity assertion provider, or in addition to an authentication provider if you want to use the authentication provider's LoginModule.

If you want to allow the identity assertion provider to be configured separately from the authentication provider, write two providers. If your identity assertion provider and authentication provider cannot work independently, then write one provider.

This chapter includes the following sections:

Identity Assertion Concepts

Before you develop an identity assertion provider, you need to understand the following concepts:

Identity Assertion Providers and LoginModules

When used with a LoginModule, identity assertion providers support single sign-on. For example, an identity assertion provider can generate a token from a digital certificate, and that token can be passed around the system so that users are not asked to sign on more than once.

The LoginModule that an identity assertion provider uses can be:

Part of a custom authentication provider you develop. For more information, see Authentication Providers.
Part of the WebLogic Authentication provider Oracle developed and packaged with WebLogic Server. See Do You Need to Develop a Custom Authentication Provider?.
Part of a third-party security vendor's authentication provider.

Unlike in a simple authentication situation (described in The Authentication Process), the LoginModules that identity assertion providers use do not verify proof material such as usernames and passwords; they simply verify that the user exists.

The LoginModules in this configuration must:

Populate the Subject with required Principals, such as those of type WLSGroup.
Must trust that the user has submitted sufficient proof to login and not require a password or some other proof material.

You must implement the AuthenticationProviderV2.getAssertionModuleConfiguration method in your custom authentication provider, as described in Implement the AuthenticationProviderV2 SSPI. This method is called for identity assertion, such as when an X.509 certificate is being used, and to process the run-as tag in deployment descriptors. Other single signon strategies use it as well.

Note:

See LoginModules.

Identity Assertion and Tokens

You develop identity assertion providers to support the specific types of tokens that you will be using to assert the identities of users or system processes. You can develop an identity assertion provider to support multiple token types, but you or an administrator configure the identity assertion provider so that it validates only one active token type. 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.

Note:

Supporting token types means that the identity assertion provider's runtime class (that is, the IdentityAsserter SSPI implementation) can validate the token type in its assertIdentity method. See Implement the IdentityAsserterV2 SSPI.

The following sections will help you work with new token types:

How to Create New Token Types

If you develop a custom identity assertion provider, you can also create new token types. A token type is simply a piece of data represented as a string. The token types you create and use are completely up to you. The token types currently defined for the WebLogic Identity Assertion provider include: AuthenticatedUser, X.509, CSI.PrincipalName, CSI.ITTAnonymous, CSI.X509CertChain, CSI.DistinguishedName, and wsse:PasswordDigest.

To create new token types, you create a new Java file and declare any new token types as variables of type String., as shown in Example 4-1. The PerimeterIdentityAsserterTokenTypes.java file defines the names of the token types Test 1, Test 2, and Test 3 as strings.

Note:

If you are defining only one new token type, you can also do it right in the identity assertion provider's runtime class, as shown in Example 4-4.

Example 4-1 PerimeterIdentityAsserterTokenTypes.java

package sample.security.providers.authentication.perimeterATN;
public class PerimeterIdentityAsserterTokenTypes
{
   public final static String TEST1_TYPE = 'Test 1";
   public final static String TEST2_TYPE = 'Test 2";
   public final static String TEST3_TYPE = 'Test 3";
}

How to Make New Token Types Available for Identity Assertion Provider Configurations

When you or an administrator configure a custom identity assertion provider (see Configure the Custom Identity Assertion Provider Using the Administration Console), the Supported Types field displays a list of the token types that the identity assertion provider supports. You enter one of the supported types in the Active Types field, as shown in Figure 4-1.

Figure 4-1 Configuring the Sample Identity Assertion Provider

Description of "Figure 4-1 Configuring the Sample Identity Assertion Provider"

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 4-2. (See Generate an MBean Type Using the WebLogic MBeanMaker.)

Example 4-2 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 or an administrator can default the ActiveTypes attribute in the MDF so that it does not have to be set manually with the WebLogic Server Administration Console. An example from the sample identity assertion provider is shown in Example 4-3.

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

Note:

If an identity assertion provider is not developed and configured to validate and accept a token type, the authentication process will fail. For more information about configuring an identity assertion provider, see Configure the Custom Identity Assertion Provider Using the Administration Console.

Passing Tokens for Perimeter Authentication

An identity assertion provider can pass tokens from Java clients to servlets for the purpose of perimeter authentication. Tokens can be passed using HTTP headers, cookies, SSL certificates, or other mechanisms. For example, a string that is base 64-encoded (which enables the sending of binary data) can be sent to a servlet through an HTTP header. The value of this string can be a username, or some other string representation of a user's identity. The identity assertion provider used for perimeter authentication can then take that string and extract the username.

If the token is passed through HTTP headers or cookies, the token is equal to the header or cookie name, and the resource container passes the token to the part of the WebLogic Security Framework that handles authentication. The WebLogic Security Framework then passes the token to the identity assertion provider, unchanged.

WebLogic Server is designed to extend the single sign-on concept all the way to the perimeter through support for identity assertion. Identity assertion allows WebLogic Server to use the authentication mechanism provided by perimeter authentication schemes such as the Security Assertion Markup Language (SAML), the Simple and Protected GSS-API Negotiation Mechanism (SPNEGO), or enhancements to protocols such as Common Secure Interoperability (CSI) v2 to achieve this functionality.

Common Secure Interoperability Version 2 (CSIv2)

WebLogic Server provides support for an Enterprise JavaBean (EJB) interoperability protocol based on Internet Inter-ORB (IIOP) (GIOP version 1.2) and the CORBA Common Secure Interoperability version 2 (CSIv2) specification. CSIv2 support in WebLogic Server:

Interoperates with the Java Platform, Enterprise Edition (Java EE) reference implementation.
Allows WebLogic Server IIOP clients to specify a username and password in the same manner as T3 clients.
Supports Generic Security Services Application Programming Interface (GSSAPI) initial context tokens. For this release, only usernames and passwords and GSSUP (Generic Security Services Username Password) tokens are supported.

Note:

The CSIv2 implementation in WebLogic Server passed Java EE Compatibility Test Suite (CTS) conformance testing.

The external interface to the CSIv2 implementation is a JAAS LoginModule that retrieves the username and password of the CORBA object. The JAAS LoginModule can be used in a WebLogic Java client or in a WebLogic Server instance that acts as a client to another Java EE application server. The JAAS LoginModule for the CSIv2 support is called UsernamePasswordLoginModule, and is located in the weblogic.security.auth.login package.

CSIv2 works in the following manner:

When creating a Security Extensions to Interoperable Object Reference (IOR), WebLogic Server adds a tagged component identifying the security mechanisms that the CORBA object supports. This tagged component includes transport information, client authentication information, and identity token/authorization token information.
The client evaluates the security mechanisms in the IOR and selects the mechanism that supports the options required by the server.
The client uses the SAS protocol to establish a security context with WebLogic Server. The SAS protocol defines messages contained within the service context of requests and replies. A context can be stateful or stateless.

For information about using CSIv2, see Common Secure Interoperability Version 2 in Understanding Security for Oracle WebLogic Server. See LoginModules.

The Identity Assertion Process

In perimeter authentication, a system outside of WebLogic Server establishes trust via tokens (as opposed to the type of authentication described in The Authentication Process, where WebLogic Server establishes trust via usernames and passwords). Identity assertion providers are used as part of perimeter authentication process, which works as follows (see Figure 4-2):

A token from outside of WebLogic Server is passed to an identity assertion provider that is responsible for validating tokens of that type and that is configured as active.
If the token is successfully validated, the identity assertion provider maps the token to a WebLogic Server username, and sends that username back to WebLogic Server, which then continues the authentication process as described in The Authentication Process. Specifically, the username is sent via a Java Authentication and Authorization Service (JAAS) CallbackHandler and passed to each configured authentication provider's LoginModule, so that the LoginModule can populate the subject with the appropriate principals.

Figure 4-2 Perimeter Authentication

Description of "Figure 4-2 Perimeter Authentication"

As Figure 4-2 also shows, perimeter authentication requires the same components as the authentication process described in The Authentication Process, but also adds an identity assertion provider.

Do You Need to Develop a Custom Identity Assertion Provider?

The WebLogic Identity Assertion providers support certificate authentication using X509 certificates, SPNEGO tokens, SAML assertion tokens, and CORBA Common Secure Interoperability version 2 (CSIv2) identity assertion.

The LDAP X509 Identity Assertion provider receives an X509 certificate, looks up the LDAP object for the user associated with that certificate, ensures that the certificate in the LDAP object matches the presented certificate, and then retrieves the name of the user from the LDAP object for the purpose of authentication.

The Negotiate Identity Assertion provider is used for SSO with Microsoft clients that support the SPNEGO protocol. The Negotiate Identity Assertion provider decodes SPNEGO tokens to obtain Kerberos tokens, validates the Kerberos tokens, and maps Kerberos tokens to WebLogic users. The Negotiate Identity Assertion provider utilizes the Java Generic Security Service (GSS) Application Programming Interface (API) to accept the GSS security context via Kerberos. The Negotiate Identity Assertion provider is for Windows NT Integrated Login.

The SAML Identity Assertion providers handle SAML assertion tokens when WebLogic Server acts as a SAML destination site. The SAML Identity Assertion providers consume and validate SAML assertion tokens and determines if the assertion is to be trusted (using either the proof material available in the SOAP message, the client certificate, or some other configuration indicator).

The default WebLogic Identity Assertion provider validates the token type, then maps X509 digital certificates and X501 distinguished names to WebLogic usernames. It also specifies a list of trusted client principals to use for CSIv2 identity assertion. The wildcard character (*) can be used to specify that all principals are trusted. If a client is not listed as a trusted client principal, the CSIv2 identity assertion fails and the invoke is rejected.

Note:

To use the WebLogic Identity Assertion provider for X.501 and X.509 certificates, you have the option of using the default user name mapper that is supplied with the WebLogic Server product (weblogic.security.providers.authentication.DefaultUserNameMapperImpl) or providing you own implementation of the weblogic.security.providers.authentication.UserNameMapper interface.

This interface maps a X.509 certificate to a WebLogic Server user name according to whatever scheme is appropriate for your needs. You can also use this interface to map from an X.501 distinguished name to a user name. You specify your implementation of this interface when you use the WebLogic Server Administration Console to configure an identity assertion provider.

The WebLogic Identity Assertion providers support the following token types:

AU_TYPE, for a WebLogic AuthenticatedUser used as a token.
X509_TYPE, for an X509 client certificate used as a token.
CSI_PRINCIPAL_TYPE, for a CSIv2 principal name identity used as a token.
CSI_ANONYMOUS_TYPE, for a CSIv2 anonymous identity used as a token.
CSI_X509_CERTCHAIN_TYPE, for a CSIv2 X509 certificate chain identity used as a token.
CSI_DISTINGUISHED_NAME_TYPE, for a CSIv2 distinguished name identity used as a token.
AUTHORIZATION_NEGOTIATE, for a SPNEGO internal token used as a token.
SAML_ASSERTION_B64_TYPE, for a Base64 encoded SAML.assertion used as a token.
SAML_ASSERTION_DOM_TYPE, for a SAML DOM element used as a token.
SAML_ASSERTION_TYPE, for a SAML string XML form used as a token.
SAML2_ASSERTION_DOM_TYPE, for a SAML2 DOM element used as a token.
SAML2_ASSERTION_TYPE, for a SAML2 string XML form used as a token.
SAML_SSO_CREDENTIAL_TYPE, for a SAML string consisting of the TARGET parameter concatenated with the assertion itself and used as a token.
WSSE_PASSWORD_DIGEST_TYPE, for a username token with a password type of password digest used as a token.
WWW_AUTHENTICATE_NEGOTIATE, for a SPNEGO internal token used as a token.

If you want to perform additional identity assertion tasks or create new token types, then you need to develop a custom identity assertion provider.

How to Develop a Custom Identity Assertion Provider

If the WebLogic Identity Assertion provider does not meet your needs, you can develop a custom identity assertion provider by following these steps:

Create Runtime Classes Using the Appropriate SSPIs
Generate an MBean type for your custom identity assertion provider by completing the steps described in Generate an MBean Type Using the WebLogic MBeanMaker.
Configure the Custom Identity Assertion Provider Using the Administration Console
Consider whether you need to implement challenge identity assertion, as described in Challenge Identity Assertion.

Create Runtime Classes Using the Appropriate SSPIs

Before you start creating runtime classes, you should first:

When you understand this information and have made your design decisions, create the runtime classes for your custom identity assertion provider by following these steps:

Implement the AuthenticationProviderV2 SSPI
Implement the IdentityAsserterV2 SSPI

Note:

If you want to create a separate LoginModule for your custom identity assertion provider (that is, not use the LoginModule from your authentication provider), you also need to implement the JAAS LoginModule interface, as described in Implement the JAAS LoginModule Interface.

For an example of how to create a runtime class for a custom identity assertion provider, see Example: Creating the Runtime Class for the Sample Identity Assertion Provider.

Implement the AuthenticationProviderV2 SSPI

Note:

The AuthenticationProvider SSPI is deprecated in this release of WebLogic Server. Use the AuthenticationProviderV2 SSPI instead.

To implement the AuthenticationProviderV2 SSPI, provide implementations for the methods described in Understand the Purpose of the Provider SSPIs and the following methods:

getLoginModuleConfiguration
```
public AppConfigurationEntry getLoginModuleConfiguration()
```
The getLoginModuleConfiguration method obtains information about the authentication provider's associated LoginModule, which is returned as an AppConfigurationEntry. The AppConfigurationEntry is a Java Authentication and Authorization Service (JAAS) class that contains the classname of the LoginModule; the LoginModule's control flag (which was passed in via the authentication provider's associated MBean); and a configuration options map for the LoginModule (which allows other configuration information to be passed into the LoginModule).

For more information about the AppConfigurationEntry class (located in the javax.security.auth.login package) and the control flag options for LoginModules, see the AppConfigurationEntry class (http://docs.oracle.com/javase/8/docs/api/javax/security/auth/login/AppConfigurationEntry.html) and the Configuration class (http://docs.oracle.com/javase/8/docs/api/javax/security/auth/login/Configuration.html). For more information about LoginModules, see LoginModules. For more information about security providers and MBeans, see Understand Why You Need an MBean Type.
getAssertionModuleConfiguration
```
public AppConfigurationEntry
getAssertionModuleConfiguration()
```
The getAssertionModuleConfiguration method obtains information about an identity assertion provider's associated LoginModule, which is returned as an AppConfigurationEntry. The AppConfigurationEntry is a JAAS class that contains the classname of the LoginModule; the LoginModule's control flag (which was passed in via the identity assertion provider's associated MBean); and a configuration options map for the LoginModule (which allows other configuration information to be passed into the LoginModule).

The LoginModules in this configuration must populate the Subject with required Principals, such as those of type WLSGroup, and must trust that the user has submitted sufficient proof to login and not require a password or some other proof material.

Note:

The assertIdentity() method of an identity assertion provider is called every time identity assertion occurs, but the LoginModules may not be called if the Subject is cached. The -Dweblogic.security.identityAssertionTTL flag can be used to affect this behavior (for example, to modify the default TTL of 5 minutes or to disable the cache by setting the flag to -1).

It is the responsibility of the identity assertion provider to ensure not just that the token is valid, but also that the user is still valid (for example, the user has not been deleted).
getPrincipalValidator
```
public PrincipalValidator getPrincipalValidator()
```
The getPrincipalValidator method obtains a reference to the principal validation provider's runtime class (that is, the PrincipalValidator SSPI implementation). For more information, see Principal Validation Providers.
getIdentityAsserter
```
public IdentityAsserterV2 getIdentityAsserter()
```
The getIdentityAsserter method obtains a reference to the identity assertion provider's runtime class (that is, the IdentityAsserterV2 SSPI implementation). For more information, see Implement the IdentityAsserterV2 SSPI.

Note:

When the LoginModule used for the identity assertion provider is the same as that used for an existing authentication provider, implementations for the methods in the AuthenticationProviderV2 SSPI (excluding the getIdentityAsserter method) for identity assertion providers can just return null. An example of this is shown in Example 4-4.

See Java API Reference for Oracle WebLogic Server to know more about the AuthenticationProviderV2 SSPI and the methods described above.

Implement the IdentityAsserterV2 SSPI

Note:

The IdentityAsserterV2 SSPI includes additional token types and a handler parameter to the assertIdentity method that can optionally be used to obtain additional information when asserting the identity. Although the IdentityAsserter SSPI is still supported, you should consider using the IdentityAsserterV2 SSPI instead.

To implement the IdentityAsserterV2 SSPI, provide implementations for the following method:

assertIdentity
```
public CallbackHandler assertIdentity(String type, Object token, ContextHandler handler) throws IdentityAssertionException;
```
The assertIdentity method asserts an identity based on the token identity information that is supplied. In other words, the purpose of this method is to validate any tokens that are not currently trusted against trusted client principals. The type parameter represents the token type to be used for the identity assertion. Note that identity assertion types are case insensitive. The token parameter contains the actual identity information. The handler parameter is a ContextHandler object that can optionally be used to obtain additional information that may be used in asserting the identity. The CallbackHandler returned from the assertIdentity method is passed to all configured authentication providers' LoginModules to perform principal mapping, and should contain the asserted username. If the CallbackHandler is null, this signifies that the anonymous user should be used.

A CallbackHandler is a highly-flexible JAAS standard that allows a variable number of arguments to be passed as complex objects to a method. For more information about CallbackHandlers, see the CallbackHandler interface (http://docs.oracle.com/javase/8/docs/api/javax/security/auth/callback/CallbackHandler.html).

Note:

The assertIdentity() method of an identity assertion provider is called every time identity assertion occurs, but the LoginModules may not be called if the Subject is cached. The -Dweblogic.security.identityAssertionTTL flag can be used to affect this behavior (for example, to modify the default TTL of 5 minutes or to disable the cache by setting the flag to -1).

It is the responsibility of the identity assertion provider to ensure not just that the token is valid, but also that the user is still valid (for example, the user has not been deleted).

See Java API Reference for Oracle WebLogic Server to know more about the IdentityAsserterV2 SSPI and the methods described above.

Example: Creating the Runtime Class for the Sample Identity Assertion Provider

Example 4-4 shows the SampleIdentityAsserterProviderImpl.java class, which is the runtime class for the sample identity assertion provider. This runtime class includes implementations for:

The three methods inherited from the SecurityProvider interface: initialize, getDescription, and shutdown (as described in Understand the Purpose of the Provider SSPIs.)
The four methods in the AuthenticationProviderV2 SSPI: the getLoginModuleConfiguration, getAssertionModuleConfiguration, getPrincipalValidator, and getIdentityAsserter methods (as described in Implement the AuthenticationProviderV2 SSPI.
The method in the IdentityAsserterV2 SSPI: the assertIdentity method (described in Implement the IdentityAsserterV2 SSPI).

Note:

The bold face code in Example 4-4 highlights the class declaration and the method signatures.

Example 4-4 SampleIdentityAsserterProviderImpl.java

package examples.security.providers.identityassertion.simple;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.login.AppConfigurationEntry;
import weblogic.management.security.ProviderMBean;
import weblogic.security.service.ContextHandler;
import weblogic.security.spi.AuthenticationProviderV2;
import weblogic.security.spi.IdentityAsserterV2;
import weblogic.security.spi.IdentityAssertionException;
import weblogic.security.spi.PrincipalValidator;
import weblogic.security.spi.SecurityServices;
public final class SimpleSampleIdentityAsserterProviderImpl implements AuthenticationProviderV2,
IdentityAsserterV2
{
   final static private String TOKEN_TYPE   = "SamplePerimeterAtnToken";
   final static private String TOKEN_PREFIX = "username=";
   private String description; 
   public void initialize(ProviderMBean mbean, SecurityServices services)
   {
      System.out.println("SimpleSampleIdentityAsserterProviderImpl.initialize");
      SimpleSampleIdentityAsserterMBean myMBean = (SimpleSampleIdentityAsserterMBean)mbean;
      description = myMBean.getDescription() + "\n" + myMBean.getVersion();
   }
   public String getDescription()
   {
      return description;
   }
   public void shutdown()
   {
      System.out.println("SimpleSampleIdentityAsserterProviderImpl.shutdown");
   }
   public IdentityAsserterV2 getIdentityAsserter()
   {
      return this;
   }
   public CallbackHandler assertIdentity(String type, Object token, ContextHandler context) throws 
   IdentityAssertionException
   {
      System.out.println("SimpleSampleIdentityAsserterProviderImpl.assertIdentity");
      System.out.println("\tType\t\t= "  + type);
      System.out.println("\tToken\t\t= " + token);
      if (!(TOKEN_TYPE.equals(type))) {
         String error = "SimpleSampleIdentityAsserter received unknown token type \"" 
            + type + "\"." + " Expected " + TOKEN_TYPE;
         System.out.println("\tError: " + error);
         throw new IdentityAssertionException(error);
      }
      if (!(token instanceof byte[])) {
         String error = "SimpleSampleIdentityAsserter received unknown token class \"" 
            + token.getClass() + "\"." + " Expected a byte[].";
         System.out.println("\tError: " + error);
         throw new IdentityAssertionException(error);
      }
      byte[] tokenBytes = (byte[])token;
      if (tokenBytes == null || tokenBytes.length < 1) {
         String error = "SimpleSampleIdentityAsserter received empty token byte array";
         System.out.println("\tError: " + error);
         throw new IdentityAssertionException(error);
      }
      String tokenStr = new String(tokenBytes);
      if (!(tokenStr.startsWith(TOKEN_PREFIX))) {
         String error = "SimpleSampleIdentityAsserter received unknown token string \"" 
            + type + "\"." + " Expected " + TOKEN_PREFIX + "username";
         System.out.println("\tError: " + error);
         throw new IdentityAssertionException(error);
      }
      String userName = tokenStr.substring(TOKEN_PREFIX.length());
      System.out.println("\tuserName\t= " + userName);
      return new SimpleSampleCallbackHandlerImpl(userName);
   }
   public AppConfigurationEntry getLoginModuleConfiguration()
   {
      return null;
   }
   public AppConfigurationEntry getAssertionModuleConfiguration()
   {
      return null;
   }
   public PrincipalValidator getPrincipalValidator()
   {
      return null;
   }
}

Example 4-5 shows the sample CallbackHandler implementation that is used along with the SampleIdentityAsserterProviderImpl.java runtime class. This CallbackHandler implementation is used to send the username back to an authentication provider's LoginModule.

Example 4-5 SampleCallbackHandlerImpl.java

package examples.security.providers.identityassertion.simple;
import javax.security.auth.callback.Callback;
import javax.security.auth.callback.NameCallback;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.UnsupportedCallbackException;
/*package*/ class SimpleSimpleSampleCallbackHandler implements CallbackHandler
{
   private String userName;
   /*package*/ SimpleSampleCallbackHandlerImpl(String user)
   {
      userName = user;
   }
   public void handle(Callback[] callbacks) throws UnsupportedCallbackException
   {
      for (int i = 0; i < callbacks.length; i++) {
            Callback callback = callbacks[i];
            if (!(callback instanceof NameCallback)) {
               throw new UnsupportedCallbackException(callback, "Unrecognized 
                  Callback");
            }
            NameCallback nameCallback = (NameCallback)callback;
            nameCallback.setName(userName);
      }
   }
}

Configure the Custom Identity Assertion Provider Using the Administration Console

Configuring a custom identity assertion provider means that you are adding the custom identity assertion provider to your security realm, where it can be accessed by applications requiring identity assertion services.

Configuring custom security providers is an administrative task, but it is a task that may also be performed by developers of custom security providers.

Note:

The steps for configuring a custom identity assertion provider using the WebLogic Server Administration Console are described under Configuring WebLogic Security Providers in Administering Security for Oracle WebLogic Server.

Challenge Identity Assertion

The Challenge Identity Asserter interface supports challenge response schemes in which multiple challenges, responses messages, and state are required. The Challenge Identity Asserter interface allows identity assertion providers to support authentication protocols such as Microsoft's Windows NT Challenge/Response (NTLM), Simple and Protected GSS-API Negotiation Mechanism (SPNEGO), and other challenge/response authentication mechanisms.

Challenge/Response Limitations in the Java Servlet API 2.3 Environment

The WebLogic Security Framework allows you to provide a custom authentication and identity assertion provider. However, due to the nature of the Java Servlet API 2.3 specification, the interaction between the authentication provider and the client or other servers is architecturally limited during the authentication process. This restricts authentication mechanisms to those that are compatible with the authentication mechanisms the Servlet container offers: basic, form, and certificate.

Servlet authentication filters, which are described in Servlet Authentication Filters have fewer architecturally-dependence limitations; that is, they are not dependent on the authentication mechanisms offered by the servlet container. By allowing filters to be invoked prior to the container beginning the authentication process, a security realm can implement a wider scope of authentication mechanisms. For example, a servlet authentication filter could redirect the user to a SAML provider site for authentication.

Servlet authentication filters provide a convenient way to implement a challenge/response protocol in your environment. Filters allow your Challenge Identity Assertion interface to loop through your challenge/response mechanism as often as needed to complete the challenge.

Filters and The Role of the weblogic.security.services.Authentication Class

Servlet authentication filters allow you to implement a challenge/response protocol without being limited to the authentication mechanisms compatible with the Servlet container. However, because servlet authentication filters operate outside of the authentication environment provided by the Security Framework, they cannot depend on the Security Framework to determine provider context, and require an API to drive the multiple-challenge identity assertion process.

The weblogic.security.services.Authentication class has been extended to allow multiple challenge/response identity assertion from a servlet authentication filter. The methods and interface provide a wrapper for the ChallengeIdentityAsserterV2 and ProviderChallengeContext interfaces so that you can invoke them from a servlet authentication filter.

There is no other documented way to perform a multiple challenge/response dialog from a servlet authentication filter within the context of the Security Framework. Your servlet authentication filter cannot directly invoke the ChallengeIdentityAsserterV2 and ProviderChallengeContext interfaces.

Therefore, you need to implement the ChallengeIdentityAsserterV2 and ProviderChallengeContext interfaces, and then use the weblogic.security.services.Authentication methods and AppChallengeContext interface to invoke them from a servlet authentication filter.

How to Develop a Challenge Identity Asserter

To develop a Challenge Identity Asserter:

Implement the ChallengeIdentityAsserterV2 Interface

The ChallengeIdentityAsserterV2 interface extends the IdentityAsserterV2 SSPI. You must implement the ChallengeIdentityAsserterV2 interface in addition to the IdentityAsserterV2 SSPI.

Provide an implementation for all of the IdentityAsserterV2 methods, and the following methods:

assertChallengeIdentity
```
ProviderChallengeContext assertChallengeIdentity(String tokenType, Object token, ContextHandler handler)
```
Use the supplied client token to establish client identity, possibly with multiple challenges. This method returns your implementation of the ProviderChallengeContext interface. The ProviderChallengeContext interface provides a means to query the state of the challenges.

continueChallengeIdentity

void continueChallengeIdentity(ProviderChallengeContext context, String tokenType, Object token, 
ContextHandler handler)

Use the supplied provider context and client token to continue establishing client identity.

getChallengeToken
```
Object getChallengeToken(String type, ContextHandler handler) 
```
This method returns the identity assertion provider's challenge token.

Implement the ProviderChallengeContext Interface

The ProviderChallengeContext interface provides a means to query the state of the challenges. It allows the assertChallengeIdentity and continueChallengeIdentity methods of the ChallengeIdentityAsserterV2 interface to return either the callback handler or a new challenge to which the client must respond.

To implement the ProviderChallengeContext interface, provide implementations for the following methods:

getCallbackHandler
```
CallbackHandler getCallbackHandler() 
```
This method returns the callback handler for the challenge identity assertion. Call this method only when the hasChallengeIdentityCompleted method returns true.
getChallengeToken
```
Object getChallengeToken() 
```
This method returns the challenge token for the challenge identity assertion. Call this method only when the hasChallengeIdentityCompleted method returns false.
hasChallengeIdentityCompleted
```
boolean hasChallengeIdentityCompleted 
```
This method returns whether the challenge identity assertion has completed. It returns true if the challenge identity assertion has completed, false if not. If true, the caller should use the getCallbackHandler method. If false, then the caller should use the getChallengeToken method.

Invoke the weblogic.security.services Challenge Identity Methods

Have your servlet authentication filter invoke the following weblogic.security.services.Authentication methods instead of calling the ChallengeIdentityAsserterV2 SSPI directly:

assertChallengeIdentity
```
AppChallengeContext assertChallengeIdentity(String tokenType, Object token, AppContext appContext) 
```
Use the supplied client token to establish client identity, possibly with multiple challenges. This method returns the context of the challenge identity assertion. This result may contain either the authenticated subject or an additional challenge to which the client must respond. The AppChallengeContext interface provides a means to query the state of the challenges.

continueChallengeIdentity

void continueChallengeIdentity(AppChallengeContext context, String tokenType,
 Object token, AppContext appContext)

Use the supplied provider context and client token to continue establishing client identity.

getChallengeToken
```
Object getChallengeToken 
```
This method returns the initial challenge token for the challenge identity assertion.

Invoke the weblogic.security.services AppChallengeContext Methods

Have your servlet authentication filter invoke the following AppChallengeContext methods instead of invoking the ProviderChallengeContext interface directly:

getAuthenticatedSubject
```
Subject getAuthenticatedSubject() 
```
Returns the authenticated subject for the challenge identity assertion. Call this method only when the hasChallengeIdentityCompleted method returns true.
getChallengeToken
```
Object getChallengeToken() 
```
This method returns the challenge token for the challenge identity assertion. Call this method only when the hasChallengeIdentityCompleted method returns false.
hasChallengeIdentityCompleted
```
boolean hasChallengeIdentityCompleted() 
```
This method returns whether the challenge identity assertion has completed. It returns true if the challenge identity assertion has completed, false if not. If true, the caller should use the getCallbackHandler method. If false, then the caller should use the getChallengeToken method.

Implementing Challenge Identity Assertion from a Filter

In the following code flow, assume that the servlet authentication filter, which is described in Servlet Authentication Filters handles the HTTP level interactions (Authorization and WWW-Authenticate) and is also responsible for calling the weblogic.security.services.Authentication methods and interfaces to drive the Challenge Identity Assertion process.

Browser sends a request
Filter sees requests and no authorization header, so it calls the weblogic.security.services.Authentication getChallengeToken method to get an initial token and sends a 401 response with a WWW-Authenticate negotiate header back
Browser sees 401 with WWW-Authenticate and responds with a new request and a Authorization Negotiate token.
1. Filter sees this and calls the weblogic.security.services.Authentication assertChallengeIdentity method. assertChallengeIdentity takes the token as input, processes it according to whatever rules it needs to follow for the assertion process it is following (for example, if NTLM, then do whatever NTLM requires to process the token), and determine if that succeeded or not. assertChallengeIdentity returns your implementation of the AppChallengeContext interface.
2. Filter calls appChallengeContext hasChallengeCompleted method. Use the AppChallengeContext hasChallengeIdentityCompleted method to see if the challenge has completed. For example, it can determine if the callback handler is not null, meaning that it contains a username, and return true. In this use it returns false, so it must issue another challenge to the client. The filter then calls AppChallengeContext getChallengeToken to get the token to challenge back with.
3. Filter likely stores the AppChallengeContext somewhere such as a session attribute.
4. Filter sends a 401 response with an WWW-Authenticate negotiate and the new token.
Browser sees the new challenge and responds again with an authorization header.
1. Filter sees this and calls the weblogic.security.services.Authentication continueChallengeIdentity method.
2. Filter calls the AppChallengeContext hasChallengeCompleted method. If it returns false another challenge is in order, so call the AppChallengeContext getChallengeToken method to get the token to challenge back with, and so forth. If it returned true, then the challenge has completed and the filter would then call AppChallengeContext getAuthenticatedSubject method and perform a runAs(subject, request).