com.unboundid.directory.sdk.broker.api
Class TokenStore

java.lang.Object
  com.unboundid.directory.sdk.broker.api.TokenStore

All Implemented Interfaces:

Configurable, ExampleUsageProvider, UnboundIDExtension

@Extensible
@IdentityBrokerExtension
@ThreadSafety(level=INTERFACE_THREADSAFE)
public abstract class TokenStore
extends java.lang.Object
implements UnboundIDExtension, Configurable, ExampleUsageProvider

This class defines an API that must be implemented by extensions that wish to store and retrieve authorization codes and access tokens instances for the OAuth 2 service. This type of token store is generic and can support a wide range of repositories. When using multiple Identity Broker instances in a deployment, the repository should be accessible from all instances. In addition, this type of token store has the ability to generate the values of the codes and tokens that are returned to the client application. These values are also used to retrieve the authorization code and access token instances from the token store.

Configuring Token Stores

In order to configure a token store created using this API, use a command like:

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

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

Constructor Summary

TokenStore()
Creates a new instance of this token store.

Method Summary

abstract AuthorizationCode	consumeAuthorizationCode(java.lang.String codeValue) Retrieves the authorization code associated with the specified code value.
void	defineConfigArguments(com.unboundid.util.args.ArgumentParser parser) Updates the provided argument parser to define any configuration arguments which may be used by this extension.
void	finalizeTokenStore() This hook is called when the Identity Broker shuts down.
abstract AccessToken	getAccessToken(java.lang.String tokenValue) Retrieves the access token associated with the specified token value.
abstract AccessToken	getAccessTokenFromRefreshToken(java.lang.String tokenValue) Retrieves the access token associated with the refresh token value.
abstract java.util.Collection<AccessToken>	getAccessTokensByUser(java.lang.String username) Retrieves all the access tokens associated with the provided username.
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	initializeTokenStore(IdentityBrokerContext serverContext, TokenStoreConfig config, com.unboundid.util.args.ArgumentParser parser) Initializes this token store.
abstract AccessToken	revokeToken(java.lang.String tokenValue) Revoke the access token along with the associated refresh token if it exists so they will no longer be considered valid.
abstract void	storeAccessToken(AccessToken accessToken) Store a new access token with an optional refresh token and overwrite any existing tokens for the same application by the same owner.
abstract void	storeAuthorizationCode(AuthorizationCode authorizationCode) Store a new authorization code and overwrite any existing codes for the same application by the same owner.
java.lang.String	toString() Retrieves a string representation of this token store.
abstract void	toString(java.lang.StringBuilder buffer) Appends a string representation of this token store to the provided buffer.

Methods inherited from class java.lang.Object

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

Constructor Detail

TokenStore

public TokenStore()

Creates a new instance of this token store. All implementations must include a default constructor, but any initialization should generally be done in the initializeTokenStore(com.unboundid.directory.sdk.broker.types.IdentityBrokerContext, com.unboundid.directory.sdk.broker.config.TokenStoreConfig, 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(com.unboundid.util.args.ArgumentParser parser)
                           throws com.unboundid.util.args.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:

com.unboundid.util.args.ArgumentException - If a problem is encountered while updating the provided argument parser.

initializeTokenStore

public void initializeTokenStore(IdentityBrokerContext serverContext,
                                 TokenStoreConfig config,
                                 com.unboundid.util.args.ArgumentParser parser)
                          throws com.unboundid.ldap.sdk.LDAPException

Initializes this token store. This hook is called when the Identity Broker first starts up. Any initialization should be performed here. This method should generally store the IdentityBrokerContext in a class member so that it can be used elsewhere in the implementation.

The default implementation is empty.

Parameters:

serverContext - A handle to the server context for the server in which this extension is running. Extensions should typically store this in a class member.

config - The general configuration for this object.

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

Throws:

com.unboundid.ldap.sdk.LDAPException - If a problem occurs while initializing this token store.

finalizeTokenStore

public void finalizeTokenStore()

This hook is called when the Identity Broker shuts down. Any clean-up of this token store should be performed here.

The default implementation is empty.

consumeAuthorizationCode

public abstract AuthorizationCode consumeAuthorizationCode(java.lang.String codeValue)
                                                    throws OAuthException

Retrieves the authorization code associated with the specified code value. If successfully retrieved, the authorization code is no longer considered valid and may not be retrieved again.

Parameters:

codeValue - The value of the authorization code.

Returns:

The authorization code associated with the specified code value or null if the code value is not found.

Throws:

OAuthException - if an error occurred while retrieving the authorization code.

storeAuthorizationCode

public abstract void storeAuthorizationCode(AuthorizationCode authorizationCode)
                                     throws OAuthException

Store a new authorization code and overwrite any existing codes for the same application by the same owner. Implementations must set the authorization code value that may be used to retrieve this AuthorizationCode instance from the token store by calling the following on the passed-in authorization code: AuthorizationCode.setValue()

Parameters:

authorizationCode - The authorization code to store.

Throws:

OAuthException - if an error occurred while creating the authorization code.

storeAccessToken

public abstract void storeAccessToken(AccessToken accessToken)
                               throws OAuthException

Store a new access token with an optional refresh token and overwrite any existing tokens for the same application by the same owner. If the owner is not available, any existing tokens for the same application without an owner should also be overwritten. Implementations must set the access and, if available, refresh token values that may be used to retrieve this AccessToken instance from the token store by calling the following on the passed-in access token: AccessToken.setValue() and AccessToken.getRefreshToken().setValue() If the provided token's value is not null, the implementation should try to use those values to reference the stored token without generating a new value.

Parameters:

accessToken - the access token to store.

Throws:

OAuthException - if an error occurred while creating the access token.

getAccessToken

public abstract AccessToken getAccessToken(java.lang.String tokenValue)
                                    throws OAuthException

Retrieves the access token associated with the specified token value. The AccessToken instance returned by implementations must have its refresh token (if available) set by calling AccessToken.setRefreshToken() and the token value set by calling AccessToken.setValue().

Parameters:

tokenValue - The value of the access token.

Returns:

The access token associated with the specified token value or null if not found.

Throws:

OAuthException - if an error occurred while reading the access token

getAccessTokenFromRefreshToken

public abstract AccessToken getAccessTokenFromRefreshToken(java.lang.String tokenValue)
                                                    throws OAuthException

Retrieves the access token associated with the refresh token value. The AccessToken instance returned by implementations must have its refresh token set by calling AccessToken.setRefreshToken() and the token value set by calling AccessToken.setValue().

Parameters:

tokenValue - The value of the refresh token.

Returns:

The access token associated with the specified refresh token value or null if not found.

Throws:

OAuthException - If an error occurred while retrieving the access token.

getAccessTokensByUser

public abstract java.util.Collection<AccessToken> getAccessTokensByUser(java.lang.String username)
                                                                 throws OAuthException

Retrieves all the access tokens associated with the provided username. All AccessToken instances returned by implementations must have their refresh token (if available) set by calling AccessToken.setRefreshToken() and the token value set by calling AccessToken.setValue().

Parameters:

username - The username to use to identify the token user.

Returns:

The access tokens associated with the provided username or null if not found.

Throws:

OAuthException - If an error occurred while revoking the access token.

revokeToken

public abstract AccessToken revokeToken(java.lang.String tokenValue)
                                 throws OAuthException

Revoke the access token along with the associated refresh token if it exists so they will no longer be considered valid.

Parameters:

tokenValue - The value of the access or refresh token to revoke.

Returns:

The revoked access token or null if the token value was not found.

Throws:

OAuthException - If an error occurred while revoking the access token.

toString

public final java.lang.String toString()

Retrieves a string representation of this token store.

Overrides:

toString in class java.lang.Object

Returns:

A string representation of this token store.

toString

public abstract void toString(java.lang.StringBuilder buffer)

Appends a string representation of this token store to the provided buffer.

Parameters:

buffer - The buffer to which the string representation should be appended.