5 Identity Assertion Providers

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.

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.

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.

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. For more information, see Implement the IdentityAsserterV2 SSPI.

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 5-1. The PerimeterIdentityAsserterTokenTypes.java file defines the names of the token types Test 1, Test 2, and Test 3 as strings.

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 5-2. (For more information about MDFs and MBean types, see Generate an MBean Type Using the WebLogic MBeanMaker.)

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 5-3.

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.

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:

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.

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.

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

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 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 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:

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.

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

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

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 5-4.

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:

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.

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

The four methods in the AuthenticationProviderV2 SSPI: the getLoginModuleConfiguration, getAssertionModuleConfiguration, getPrincipalValidator, and getIdentityAsserter methods (as described in Implement the AuthenticationProviderV2 SSPI.

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

All instructions provided in this section assume that you are working in a Windows environment.

Create an MBean Definition File (MDF)

To create an MBean Definition File (MDF), follow these steps:

Copy the MDF for the sample Identity Assertion provider to a text file.

Note:

The MDF for the sample Identity Assertion provider is called SampleIdentityAsserter.xml.

Modify the content of the <MBeanType> and <MBeanAttribute> elements in your MDF so that they are appropriate for your custom Identity Assertion provider. For example, consider the following fragment to set the Base64DecodingRequired attribute to false:

Use the WebLogic MBeanMaker to Generate the MBean Type

Once you create your MDF, you are ready to run it through the WebLogic MBeanMaker. The WebLogic MBeanMaker is currently a command-line utility that takes as its input an MDF, and outputs some intermediate Java files, including an MBean interface, an MBean implementation, and an associated MBean information file. Together, these intermediate files form the MBean type for your custom security provider.

The instructions for generating an MBean type differ based on the design of your custom Identity Assertion provider. Follow the instructions that are appropriate to your situation:

where the -DMDF flag indicates that the WebLogic MBeanMaker should translate the MDF into code, xmlFile is the MDF (the XML MBean Description File) and filesdir is the location where the WebLogic MBeanMaker will place the intermediate files for the MBean type.

Whenever xmlfile is provided, a new set of output files is generated.

Each time you use the -DcreateStubs=true flag, it overwrites any existing MBean implementation file.

Note:

As of version 9.0 of WebLogic Server, you can also provide a directory that contains multiple MDF's by using the -DMDFDIR <MDF directory name> option. In prior versions of WebLogic Server, the WebLogic MBeanMaker processed only one MDF at a time. Therefore, you had to repeat this process if you had multiple MDFs (in other words, multiple Identity Assertion providers).

where the -DMDF flag indicates that the WebLogic MBeanMaker should translate the MDF into code, xmlFile is the MDF (the XML MBean Description File) and filesdir is the location where the WebLogic MBeanMaker will place the intermediate files for the MBean type.

Whenever xmlfile is provided, a new set of output files is generated.

Each time you use the -DcreateStubs=true flag, it overwrites any existing MBean implementation file.

Note:

As of version 9.0 of WebLogic Server, you can also provide a directory that contains multiple MDF's by using the -DMDFDIR <MDF directory name> option. In prior versions of WebLogic Server, the WebLogic MBeanMaker processed only one MDF at a time. Therefore, you had to repeat this process if you had multiple MDFs (in other words, multiple Identity Assertion providers).

If you implemented optional SSPI MBeans in your MDF, follow these steps:

Locate the MBean implementation file.

The MBean implementation file generated by the WebLogic MBeanMaker is named MBeanNameImpl.java. For example, for the MDF named SampleIdentityAsserter, the MBean implementation file to be edited is named SampleIdentityAsserterImpl.java.

For each optional SSPI MBean that you implemented in your MDF, implement each method. Be sure to also provide implementations for any methods that the optional SSPI MBean inherits.

If you included any custom operations in your MDF, implement the methods using the method stubs.

where the -DMDF flag indicates that the WebLogic MBeanMaker should translate the MDF into code, xmlFile is the MDF (the XML MBean Description File) and filesdir is the location where the WebLogic MBeanMaker will place the intermediate files for the MBean type.

Whenever xmlfile is provided, a new set of output files is generated.

Each time you use the -DcreateStubs=true flag, it overwrites any existing MBean implementation file.

Note:

As of version 9.0 of WebLogic Server, you can also provide a directory that contains multiple MDF's by using the -DMDFDIR <MDF directory name> option. In prior versions of WebLogic Server, the WebLogic MBeanMaker processed only one MDF at a time. Therefore, you had to repeat this process if you had multiple MDFs (in other words, multiple Identity Assertion providers).

If you implemented optional SSPI MBeans in your MDF, follow these steps:

Locate and open the MBean implementation file.

The MBean implementation file generated by the WebLogic MBeanMaker is named MBeanNameImpl.java. For example, for the MDF named SampleIdentityAsserter, the MBean implementation file to be edited is named SampleIdentityAsserterImpl.java.

Open your existing MBean implementation file (which you saved to a temporary directory in step 1).

Synchronize the existing MBean implementation file with the MBean implementation file generated by the WebLogic MBeanMaker.

Accomplishing this task may include, but is not limited to: copying the method implementations from your existing MBean implementation file into the newly-generated MBean implementation file (or, alternatively, adding the new methods from the newly-generated MBean implementation file to your existing MBean implementation file), and verifying that any changes to method signatures are reflected in the version of the MBean implementation file that you are going to use (for methods that exist in both MBean implementation files).

If you modified the MDF to implement optional SSPI MBeans that were not in the original MDF, implement each method. Be sure to also provide implementations for any methods that the optional SSPI MBean inherits.

If you modified the MDF to include any custom operations that were not in the original MDF, implement the methods using the method stubs.

Save the version of the MBean implementation file that is complete (that is, has all methods implemented).

Copy this MBean implementation file into the directory where the WebLogic MBeanMaker placed the intermediate files for the MBean type. You specified this as filesdir in step 3. (You will be overriding the MBean implementation file generated by the WebLogic MBeanMaker as a result of step 3.)

About the Generated MBean Interface File

The MBean interface file is the client-side API to the MBean that your runtime class or your MBean implementation will use to obtain configuration data. It is typically used in the initialize method as described in Understand the Purpose of the "Provider" SSPIs.

Because the WebLogic MBeanMaker generates MBean types from the MDF you created, the generated MBean interface file will have the name of the MDF, plus the text "MBean" appended to it. For example, the result of running the SampleIdentityAsserter MDF through the WebLogic MBeanMaker will yield an MBean interface file called SampleIdentityAsserterMBean.java.

Use the WebLogic MBeanMaker to Create the MBean JAR File (MJF)

Once your have run your MDF through the WebLogic MBeanMaker to generate your intermediate files, and you have edited the MBean implementation file to supply implementations for the appropriate methods within it, you need to package the MBean files and the runtime classes for the custom Identity Assertion provider into an MBean JAR File (MJF). The WebLogic MBeanMaker also automates this process.

To create an MJF for your custom Identity Assertion provider, follow these steps:

where the -DMJF flag indicates that the WebLogic MBeanMaker should build a JAR file containing the new MBean types, jarfile is the name for the MJF and filesdir is the location where the WebLogic MBeanMaker looks for the files to JAR into the MJF.

Compilation occurs at this point, so errors are possible. If jarfile is provided, and no errors occur, an MJF is created with the specified name.

Note:

When you create a JAR file for a custom security provider, a set of XML binding classes and a schema are also generated. You can choose a namespace to associate with that schema. Doing so avoids the possibility that your custom classes will conflict with those provided by Oracle. The default for the namespace is vendor. You can change this default by passing the -targetNameSpace argument to the WebLogicMBeanMaker or the associated WLMBeanMaker ant task.

If you want to update an existing MJF, simply delete the MJF and regenerate it. The WebLogic MBeanMaker also has a -DIncludeSource option, which controls whether source files are included into the resulting MJF. Source files include both the generated source and the MDF itself. The default is false. This option is ignored when -DMJF is not used.

The resulting MJF can be installed into your WebLogic Server environment, or distributed to your customers for installation into their WebLogic Server environments.

Install the MBean Type Into the WebLogic Server Environment

To install an MBean type into the WebLogic Server environment, copy the MJF into the WL_HOME\server\lib\mbeantypes directory, where WL_HOME is the top-level installation directory for WebLogic Server. This "deploys" your custom Identity Assertion provider—that is, it makes the custom Identity Assertion provider manageable from the WebLogic Server Administration Console.

Note:

WL_HOME\server\lib\mbeantypes is the default directory for installing MBean types. (Beginning with 9.0, security providers can be loaded from ...\domaindir\lib\mbeantypes as well.) However, if you want WebLogic Server to look for MBean types in additional directories, use the -Dweblogic.alternateTypesDirectory=<dir> command-line flag when starting your server, where <dir> is a comma-separated list of directory names. When you use this flag, WebLogic Server will always load MBean types from WL_HOME\server\lib\mbeantypes first, then will look in the additional directories and load all valid archives present in those directories (regardless of their extension). For example, if -Dweblogic.alternateTypesDirectory = dirX,dirY, WebLogic Server will first load MBean types from WL_HOME\server\lib\mbeantypes, then any valid archives present in dirX and dirY. If you instruct WebLogic Server to look in additional directories for MBean types and are using the Java Security Manager, you must also update the weblogic.policy file to grant appropriate permissions for the MBean type (and thus, the custom security provider). For more information, see "Using Java Security to Protect WebLogic Resources" in Programming Security for Oracle WebLogic Server.

You can create instances of the MBean type by configuring your custom Identity Assertion provider (see Configure the Custom Identity Assertion Provider Using the Administration Console), and then use those MBean instances from a GUI, from other Java code, or from APIs. For example, you can use the WebLogic Server Administration Console to get and set attributes and invoke operations, or you can develop other Java objects that instantiate MBeans and automatically respond to information that the MBeans supply. We recommend that you back up these MBean instances.

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 Securing Oracle WebLogic Server.

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 Chapter 13, "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.

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.

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.

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.

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 Chapter 13, "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.AuthenticationgetChallengeToken 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.

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.

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.

Filter likely stores the AppChallengeContext somewhere such as a session attribute.

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.

Filter sees this and calls the weblogic.security.services.Authentication continueChallengeIdentity method.

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

Scripting on this page enhances content navigation, but does not change the content in any way.