com.unboundid.directory.sdk.common.api

Class AccessTokenValidator

java.lang.Object

com.unboundid.directory.sdk.common.api.AccessTokenValidator

All Implemented Interfaces:

Configurable, ExampleUsageProvider, UnboundIDExtension

@Extensible
 @BrokerExtension
 @DirectoryServerExtension
 @SynchronizationServerExtension(appliesToLocalContent=true,
                                appliesToSynchronizedContent=false)
 @MetricsEngineExtension
 @DirectoryProxyServerExtension(appliesToLocalContent=true,
                               appliesToRemoteContent=true)
 @ThreadSafety(level=INTERFACE_THREADSAFE)
public abstract class AccessTokenValidator
extends java.lang.Object
implements UnboundIDExtension, Configurable, ExampleUsageProvider

This class defines an API that may be implemented by PingAuthorize Server extensions that validate externally generated access tokens. Implementing extensions that support this API enables the PingAuthorize Server to accept access tokens generated from external Identity Providers.

Configuring Access Token Validators

In order to configure an Access Token Validator created using this API, use a command like:

      dsconfig create-token-validator \
           ---validator-name "{name}" \
           --type third-party \
           --set "extension-class:{class-name}" \
           --set "extension-argument:{name=value}"
 

where "{name}" is the name to use for the Access Token Validator instance, "{class-name}" is the fully-qualified name of the Java class that extends com.unboundid.directory.sdk.common.api.AccessTokenValidator, and "{name=value}" represents name-value pairs for any arguments to provide to the Access Token Validator. If multiple arguments should be provided to the extension, then the "--set extension-argument:{name=value}" option should be provided multiple times.

Constructor Summary

Constructors

Constructor and Description
AccessTokenValidator() Creates a new instance of this Access Token Validator.

Method Summary

Modifier and Type	Method and Description
void	defineConfigArguments(ArgumentParser parser) Updates the provided argument parser to define any configuration arguments which may be used by this extension.
void	finalizeTokenValidator() Performs any cleanup which may be necessary when this token validator is to be taken out of service.
java.util.Map<java.util.List<java.lang.String>,java.lang.String>	getExamplesArgumentSets() Retrieves a map containing examples of configurations that may be used for this extension.
abstract java.lang.String[]	getExtensionDescription() Retrieves a human-readable description for this extension.
abstract java.lang.String	getExtensionName() Retrieves a human-readable name for this extension.
void	initializeTokenValidator(ServerContext serverContext, AccessTokenValidatorConfig config, ArgumentParser parser) Initializes this access token validator.
abstract TokenValidationResult	validate(java.lang.String encodedAccessToken) Validate the provided access token.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AccessTokenValidator

public AccessTokenValidator()

Creates a new instance of this Access Token Validator. All implementations must include a default constructor, but any initialization should generally be done in the initializeTokenValidator(com.unboundid.directory.sdk.common.types.ServerContext, com.unboundid.directory.sdk.common.config.AccessTokenValidatorConfig, com.unboundid.util.args.ArgumentParser) method.

Method Detail

getExtensionName

public abstract java.lang.String getExtensionName()

Retrieves a human-readable name for this extension.

Specified by:

getExtensionName in interface UnboundIDExtension

Returns:

A human-readable name for this extension.

getExtensionDescription

public abstract java.lang.String[] getExtensionDescription()

Retrieves a human-readable description for this extension. Each element of the array that is returned will be considered a separate paragraph in generated documentation.

Specified by:

getExtensionDescription in interface UnboundIDExtension

Returns:

A human-readable description for this extension, or null or an empty array if no description should be available.

getExamplesArgumentSets

public java.util.Map<java.util.List<java.lang.String>,java.lang.String> getExamplesArgumentSets()

Retrieves a map containing examples of configurations that may be used for this extension. The map key should be a list of sample arguments, and the corresponding value should be a description of the behavior that will be exhibited by the extension when used with that configuration.

Specified by:

getExamplesArgumentSets in interface ExampleUsageProvider

Returns:

A map containing examples of configurations that may be used for this extension. It may be null or empty if there should not be any example argument sets.

defineConfigArguments

public void defineConfigArguments(ArgumentParser parser)
                           throws ArgumentException

Updates the provided argument parser to define any configuration arguments which may be used by this extension. The argument parser may also be updated to define relationships between arguments (e.g., to specify required, exclusive, or dependent argument sets).

Specified by:

defineConfigArguments in interface Configurable

Parameters:

parser - The argument parser to be updated with the configuration arguments which may be used by this extension.

Throws:

ArgumentException - If a problem is encountered while updating the provided argument parser.

initializeTokenValidator

public void initializeTokenValidator(ServerContext serverContext,
                                     AccessTokenValidatorConfig config,
                                     ArgumentParser parser)
                              throws java.lang.Exception

Initializes this access token validator.

Parameters:

serverContext - A handle to the server context for the server in which this extension is running.

config - The general configuration for this token validator.

parser - The argument parser which has been initialized from the configuration for this token validator.

Throws:

java.lang.Exception - If a problem occurs while initializing this token validator.

finalizeTokenValidator

public void finalizeTokenValidator()

Performs any cleanup which may be necessary when this token validator is to be taken out of service.

validate

public abstract TokenValidationResult validate(java.lang.String encodedAccessToken)
                                        throws java.lang.Exception

Validate the provided access token.

Parameters:

encodedAccessToken - access token string as it is received from the requesting client.

Returns:

The PingAuthorize Server may be configured to accept access tokens from multiple sources so it is important that each validator differentiate between a token format that it does not recognize and a token that it can process but is not valid. If the token can be processed, the validator must return a TokenValidationResult object containing token properties. Most importantly the active field of the TokenValidationResult must be set by the validator. The decision as to whether an access token is accepted or not is made by the servlet hosting the token validator. If the token cannot be introspected by the Access Token Validator it must return null to allow other validators to have a chance to process the token.

Throws:

java.lang.Exception - if an error occurs during the processing of a token that can be introspected by the validator. Exceptions should only be thrown for unexpected internal errors. Sensitive information should not be included in the exception message as the message may be returned to the client application that has passed the token.