OAuth2Client (OpenAM Server Only 6.5.5 Documentation)

java.lang.Object
- org.forgerock.oauth.clients.oauth2.OAuth2Client<T>

Type Parameters:

T - type of OAuth client configuration to be used.

All Implemented Interfaces:

OAuthClient

Direct Known Subclasses:

OpenIDConnectClient
```
public class OAuth2Client<T extends OAuth2ClientConfiguration>
extends Object
implements OAuthClient
```
OAuth 2.0 Client Implementation that supports the Authorization Code Grant Flow.

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`ACCESS_TOKEN` The access token issued by the authorization server.
`protected Function<JsonValue,JsonValue,OAuthException>`	`addExpireTime` Adds the actual time the token expires.
`static String`	`AUTHORIZATION_CODE` String used to verify the resource owner who granted the authorization at the authorization server.
`static String`	`AUTHORIZATION_HEADER` Authorization header.
`static String`	`BASIC_AUTH` Basic Auth.
`static String`	`BEARER_TOKEN` Token Type.
`static String`	`CLIENT_ID` Client Identifier.
`static String`	`CLIENT_SECRET` Client Password.
`static String`	`CODE` A type of response_type.
`static String`	`DATA` URI safe data that MUST not be modified by the client and stored in the `DataStore`.
`static String`	`EXPIRE_TIME` Expire time.
`static String`	`EXPIRES_IN` Length of time token expires in.
`static String`	`GRANT_TYPE` Type of grant.
`static String`	`HTTP_GET` HTTP GET.
`static String`	`HTTP_POST` HTTP POST.
`protected Handler`	`httpHandler` `Handler` to be used to make http requests.
`static String`	`LANDING_PAGE` URI where the user agent will be directed to after OAuth interaction is complete.
`static String`	`PKCE_CODE_CHALLENGE` PKCE code challenge parameter.
`static String`	`PKCE_CODE_CHALLENGE_METHOD` PKCE code challenge method.
`static String`	`PKCE_CODE_VERIFIER` PKCE code verifier parameter.
`protected SecureRandom`	`random` `SecureRandom` used to generate opaque, cryptographically secure strings.
`static String`	`REDIRECT_URI` Uri to redirect the user agent back to from the authorization server.
`static String`	`REFRESH_TOKEN` Token used specifically to retrieve access tokens.
`static String`	`RESPONSE_TYPE` Value that determines the authorization processing flow to be used.
`static String`	`SCOPE` e.g.
`static String`	`STATE` Opaque value used to maintain state between the request and the callback.
`protected TimeService`	`timeService` `TimeService` used to handle token expire times.

Constructor Summary

Constructors
Constructor and Description
`OAuth2Client(Handler httpHandler, T config, Clock clock, SecureRandom random)` Constructs an OAuth2Client using a provided `Handler` and `OAuthClientConfiguration`.
`OAuth2Client(Handler httpHandler, T config, TimeService timeService, SecureRandom random)` Deprecated.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`protected void`	`addClientIdAndSecret(Request request, Form form)` Adds the client id and client secret to a request based on the determined type of authentication scheme.
`protected String`	`createAuthorizationState()` g Generates a SecureRandom BigInteger as a String.
`protected URI`	`createAuthRedirectUri(String state)` Deprecated. Use `OAuth2Client.createAuthRedirectUri(String, String)` and specify a PKCE challenge.
`protected URI`	`createAuthRedirectUri(String state, String pkceChallenge)` Creates a `URI` that the user agent will be redirected to for authentication and authorization.
`protected String`	`createPkceVerifier()` Generates a secure opaque PKCE verifier value.
`protected Function<Void,JsonValue,OAuthException>`	`createPostAuthResponse(JsonValue storedData)` Creates the post auth response.
`protected Request`	`createRequestForTokenEndpoint(String code)` Deprecated. Use `OAuth2Client.createAuthRedirectUri(String, String)` and specify a PKCE verifier.
`protected Request`	`createRequestForTokenEndpoint(String code, String pkceVerifier)` Creates a `Request` for the token endpoint of an identity provider.
`protected Request`	`createRequestForTokenRefresh(JsonValue storedData)` Creates a `Request` for the token refresh endpoint of an identity provider.
`protected Request`	`createRequestForUserInfoEndpoint(String accessToken)` Creates a `Request` for the user information endpoint of an identity provider.
`protected static String`	`getAccessToken(JsonValue data)` Retrieves an access token from a `JsonValue`.
`Promise<URI,OAuthException>`	`getAuthRedirect(DataStore dataStore, String data, URI landingPage)` Return the URI that the user agent should be redirected to, to authenticate and authorize access.
`protected T`	`getConfig()` Gets the configuration for this `OAuthClient`.
`protected static String`	`getFirstValueOrNull(List<String> values)` Gets the first value out of the List.
`Promise<? extends OAuth2SessionInfo,OAuthException>`	`getSessionInfo(DataStore dataStore)` Validate whether an Auth Server session is still active and valid.
`Promise<UserInfo,OAuthException>`	`getUserInfo(DataStore dataStore)` Return the authenticated user's info from the external authentication server.
`Promise<JsonValue,OAuthException>`	`handlePostAuth(DataStore dataStore, Map<String,List<String>> requestParameters)` Handle the data produced by the Auth Server as a result of a successful authentication and return the final redirect to the landing page specified in the `OAuthClient.getAuthRedirect(DataStore, String, URI)` call.
`protected static Function<Response,JsonValue,OAuthException>`	`mapToJsonValue()` A `Function` that handles a `Response` from an Auth Server that returns the HTTP entity content as JsonValue, and throws an `OAuthException` if the response is not successful (200 family status code).
`protected Function<JsonValue,UserInfo,OAuthException>`	`mapToUserInfo()` Creates a `OAuth2UserInfo` using a users raw profile.
`Promise<Void,OAuthException>`	`refresh(DataStore dataStore)` Refreshes a token if it has expired.
`protected Function<JsonValue,Void,OAuthException>`	`storeResponse(DataStore dataStore)` Stores all the information received from an authentication or authorization server.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - CLIENT_ID
```
public static final String CLIENT_ID
```
    Client Identifier.
    
    See Also:
    
    Constant Field Values
  - CLIENT_SECRET
```
public static final String CLIENT_SECRET
```
    Client Password.
    
    See Also:
    
    Constant Field Values
  - REDIRECT_URI
```
public static final String REDIRECT_URI
```
    Uri to redirect the user agent back to from the authorization server.
    
    See Also:
    
    Constant Field Values
  - GRANT_TYPE
```
public static final String GRANT_TYPE
```
    Type of grant.
    
    See Also:
    
    Constant Field Values
  - RESPONSE_TYPE
```
public static final String RESPONSE_TYPE
```
    Value that determines the authorization processing flow to be used.
    
    See Also:
    
    Constant Field Values
  - AUTHORIZATION_CODE
```
public static final String AUTHORIZATION_CODE
```
    String used to verify the resource owner who granted the authorization at the authorization server.
    
    See Also:
    
    Constant Field Values
  - SCOPE
```
public static final String SCOPE
```
    e.g. mail, profile, openid, etc.
    
    See Also:
    
    Constant Field Values
  - STATE
```
public static final String STATE
```
    Opaque value used to maintain state between the request and the callback.
    
    See Also:
    
    Constant Field Values
  - PKCE_CODE_CHALLENGE
```
public static final String PKCE_CODE_CHALLENGE
```
    PKCE code challenge parameter.
    
    See Also:
    
    Constant Field Values
  - PKCE_CODE_VERIFIER
```
public static final String PKCE_CODE_VERIFIER
```
    PKCE code verifier parameter.
    
    See Also:
    
    Constant Field Values
  - PKCE_CODE_CHALLENGE_METHOD
```
public static final String PKCE_CODE_CHALLENGE_METHOD
```
    PKCE code challenge method.
    
    See Also:
    
    Constant Field Values
  - ACCESS_TOKEN
```
public static final String ACCESS_TOKEN
```
    The access token issued by the authorization server.
    
    See Also:
    
    Constant Field Values
  - REFRESH_TOKEN
```
public static final String REFRESH_TOKEN
```
    Token used specifically to retrieve access tokens.
    
    See Also:
    
    Constant Field Values
  - CODE
```
public static final String CODE
```
    A type of response_type.
    
    See Also:
    
    Constant Field Values
  - EXPIRES_IN
```
public static final String EXPIRES_IN
```
    Length of time token expires in.
    
    See Also:
    
    Constant Field Values
  - DATA
```
public static final String DATA
```
    URI safe data that MUST not be modified by the client and stored in the DataStore.
    
    See Also:
    
    Constant Field Values
  - LANDING_PAGE
```
public static final String LANDING_PAGE
```
    URI where the user agent will be directed to after OAuth interaction is complete.
    
    See Also:
    
    Constant Field Values
  - EXPIRE_TIME
```
public static final String EXPIRE_TIME
```
    Expire time.
    
    See Also:
    
    Constant Field Values
  - AUTHORIZATION_HEADER
```
public static final String AUTHORIZATION_HEADER
```
    Authorization header.
    
    See Also:
    
    Constant Field Values
  - BASIC_AUTH
```
public static final String BASIC_AUTH
```
    Basic Auth.
    
    See Also:
    
    Constant Field Values
  - BEARER_TOKEN
```
public static final String BEARER_TOKEN
```
    Token Type.
    
    See Also:
    
    Constant Field Values
  - HTTP_GET
```
public static final String HTTP_GET
```
    HTTP GET.
    
    See Also:
    
    Constant Field Values
  - HTTP_POST
```
public static final String HTTP_POST
```
    HTTP POST.
    
    See Also:
    
    Constant Field Values
  - addExpireTime
```
protected final Function<JsonValue,JsonValue,OAuthException> addExpireTime
```
    Adds the actual time the token expires.
  - httpHandler
```
protected final Handler httpHandler
```
    Handler to be used to make http requests.
  - timeService
```
protected final TimeService timeService
```
    TimeService used to handle token expire times.
  - random
```
protected final SecureRandom random
```
    SecureRandom used to generate opaque, cryptographically secure strings.
- Constructor Detail
  - OAuth2Client
```
@Deprecated
public OAuth2Client(Handler httpHandler,
                                T config,
                                TimeService timeService,
                                SecureRandom random)
```
    Deprecated.
    
    Constructs an OAuth2Client using a provided Handler and OAuthClientConfiguration.
    
    Parameters:
    
    httpHandler - Handler used to make Http calls to auth and resource servers.
    
    config - configuration that will be used to drive oauth flow.
    
    timeService - time service.
    
    random - used to generate opaque, cryptographically secure strings.
  - OAuth2Client
```
public OAuth2Client(Handler httpHandler,
                    T config,
                    Clock clock,
                    SecureRandom random)
```
    Constructs an OAuth2Client using a provided Handler and OAuthClientConfiguration.
    
    Parameters:
    
    httpHandler - Handler used to make Http calls to auth and resource servers.
    
    config - configuration that will be used to drive oauth flow.
    
    clock - clock instance
    
    random - used to generate opaque, cryptographically secure strings.
- Method Detail
  - mapToJsonValue
```
protected static Function<Response,JsonValue,OAuthException> mapToJsonValue()
```
    A Function that handles a Response from an Auth Server that returns the HTTP entity content as JsonValue, and throws an OAuthException if the response is not successful (200 family status code).
    
    Returns:
    
    response entity as a JsonValue.
  - getAccessToken
```
protected static final String getAccessToken(JsonValue data)
                                      throws OAuthException
```
    Retrieves an access token from a JsonValue.
    
    Parameters:
    
    data - the JsonValue that may contain an access token.
    
    Returns:
    
    the access token.
    
    Throws:
    
    OAuthException - if no access token is found in the JsonValue.
  - getFirstValueOrNull
```
protected static final String getFirstValueOrNull(List<String> values)
```
    Gets the first value out of the List.
    
    Parameters:
    
    values - List<String>
    
    Returns:
    
    The first value, or null if none exist.
  - mapToUserInfo
```
protected final Function<JsonValue,UserInfo,OAuthException> mapToUserInfo()
```
    Creates a OAuth2UserInfo using a users raw profile.
    
    Returns:
    
    OAuth2UserInfo
  - getAuthRedirect
```
public Promise<URI,OAuthException> getAuthRedirect(DataStore dataStore,
                                                   String data,
                                                   URI landingPage)
```
    Description copied from interface: OAuthClient
    
    Return the URI that the user agent should be redirected to, to authenticate and authorize access.
    
    Specified by:
    
    getAuthRedirect in interface OAuthClient
    
    Parameters:
    
    dataStore - The data store that contains information about the OAuth interaction.
    
    data - A value which will be stored in the data store to be returned as part of the final landing page redirect response, this MUST be URI safe.
    
    landingPage - The final page a user agent should be sent following successful authentication.
    
    Returns:
    
    Promise, with a type of URI, suitable for redirecting the user agent for external authentication and authorization and an Promise, with a type of OAuthException, when an error occurs.
  - handlePostAuth
```
public Promise<JsonValue,OAuthException> handlePostAuth(DataStore dataStore,
                                                        Map<String,List<String>> requestParameters)
```
    Description copied from interface: OAuthClient
    
    Handle the data produced by the Auth Server as a result of a successful authentication and return the final redirect to the landing page specified in the OAuthClient.getAuthRedirect(DataStore, String, URI) call. Validate the request as secure. The returned JsonValue response will also contain the data passed to OAuthClient.getAuthRedirect(DataStore, String, URI).
    
    Specified by:
    
    handlePostAuth in interface OAuthClient
    
    Parameters:
    
    dataStore - The data store that contains information about the OAuth interaction.
    
    requestParameters - The request parameters containing the data produced by the external authentication server.
    
    Returns:
    
    Promise, with a type of JsonValue, containing the landing page and the data value that was stored in the data store during the OAuthClient.getAuthRedirect(DataStore, String, URI) call; Promise, with a type of OAuthException, when an error occurs.
  - getSessionInfo
```
public Promise<? extends OAuth2SessionInfo,OAuthException> getSessionInfo(DataStore dataStore)
```
    Description copied from interface: OAuthClient
    
    Validate whether an Auth Server session is still active and valid.
    
    Specified by:
    
    getSessionInfo in interface OAuthClient
    
    Parameters:
    
    dataStore - The data store that contains information about the OAuth interaction.
    
    Returns:
    
    Promise, with a type of SessionInfo, representing information about the session. Promise, with a type of OAuthException, when an error occurs.
  - getUserInfo
```
public Promise<UserInfo,OAuthException> getUserInfo(DataStore dataStore)
```
    Description copied from interface: OAuthClient
    
    Return the authenticated user's info from the external authentication server.
    
    Specified by:
    
    getUserInfo in interface OAuthClient
    
    Parameters:
    
    dataStore - The data store that contains information about the OAuth interaction.
    
    Returns:
    
    Promise, with a type of UserInfo, containing the available user info. Promise, with a type of OAuthException, when an error occurs.
  - refresh
```
public Promise<Void,OAuthException> refresh(DataStore dataStore)
```
    Description copied from interface: OAuthClient
    
    Refreshes a token if it has expired.
    
    Specified by:
    
    refresh in interface OAuthClient
    
    Parameters:
    
    dataStore - The data store that contains information about the OAuth interaction.
    
    Returns:
    
    Promise If a new token has been retrieved, update the data store with the new token. OAuthException when an error occurs.
  - createAuthRedirectUri
```
protected URI createAuthRedirectUri(String state,
                                    String pkceChallenge)
```
    Creates a URI that the user agent will be redirected to for authentication and authorization.
    
    Parameters:
    
    state - opaque value used to prevent CSRF attacks.
    
    pkceChallenge - opaque PKCE challenge used to prevent code interception/injection attacks.
    
    Returns:
    
    URI
  - createAuthRedirectUri
```
@Deprecated
protected URI createAuthRedirectUri(String state)
```
    Deprecated. Use OAuth2Client.createAuthRedirectUri(String, String) and specify a PKCE challenge.
    
    Creates a URI that the user agent will be redirected to for authentication and authorization.
    
    Parameters:
    
    state - opaque value used to prevent CSRF attacks.
    
    Returns:
    
    URI
  - createRequestForTokenRefresh
```
protected Request createRequestForTokenRefresh(JsonValue storedData)
```
    Creates a Request for the token refresh endpoint of an identity provider.
    
    Parameters:
    
    storedData - data that is in the storage implementation of DataStore.
    
    Returns:
    
    Request for the user token refresh endpoint.
  - createRequestForUserInfoEndpoint
```
protected Request createRequestForUserInfoEndpoint(String accessToken)
```
    Creates a Request for the user information endpoint of an identity provider.
    
    Parameters:
    
    accessToken - token required to retrieve user information.
    
    Returns:
    
    Request for the user information endpoint.
  - createRequestForTokenEndpoint
```
protected Request createRequestForTokenEndpoint(String code,
                                                String pkceVerifier)
```
    Creates a Request for the token endpoint of an identity provider.
    
    Parameters:
    
    code - e.g authorization_code, received from identity provider during authentication and authorization phase.
    
    pkceVerifier - the PKCE verifier, or null if PKCE not being used.
    
    Returns:
    
    Request for the token endpoint.
  - createRequestForTokenEndpoint
```
@Deprecated
protected Request createRequestForTokenEndpoint(String code)
```
    Deprecated. Use OAuth2Client.createAuthRedirectUri(String, String) and specify a PKCE verifier.
    
    Creates a Request for the token endpoint of an identity provider.
    
    Parameters:
    
    code - e.g authorization_code, received from identity provider during authentication and authorization phase.
    
    Returns:
    
    Request for the token endpoint.
  - addClientIdAndSecret
```
protected void addClientIdAndSecret(Request request,
                                    Form form)
```
    Adds the client id and client secret to a request based on the determined type of authentication scheme.
    
    Parameters:
    
    request - request to add authentication parameters.
    
    form - which holds the additional parameters of the request.
  - storeResponse
```
protected final Function<JsonValue,Void,OAuthException> storeResponse(DataStore dataStore)
```
    Stores all the information received from an authentication or authorization server.
    
    Parameters:
    
    dataStore - data store in which to store the information.
    
    Returns:
    
    Void when storage is complete.
  - createPostAuthResponse
```
protected final Function<Void,JsonValue,OAuthException> createPostAuthResponse(JsonValue storedData)
```
    Creates the post auth response.
    
    Parameters:
    
    storedData - data store that contains information about the OAuth interaction.
    
    Returns:
    
    the 'landingPage' and the 'data' as a JsonValue.
  - getConfig
```
protected T getConfig()
```
    Gets the configuration for this OAuthClient.
    
    Returns:
    
    the configuration used to configure this client.
  - createAuthorizationState
```
protected String createAuthorizationState()
```
    g Generates a SecureRandom BigInteger as a String.
    
    Returns:
    
    random BigInteger as a String.
  - createPkceVerifier
```
protected String createPkceVerifier()
```
    Generates a secure opaque PKCE verifier value. See RFC 7636 Section 4.1
    
    Returns:
    
    the random PKCE verifier.

Class OAuth2Client<T extends OAuth2ClientConfiguration>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

CLIENT_ID

CLIENT_SECRET

REDIRECT_URI

GRANT_TYPE

RESPONSE_TYPE

AUTHORIZATION_CODE

SCOPE

STATE

PKCE_CODE_CHALLENGE

PKCE_CODE_VERIFIER

PKCE_CODE_CHALLENGE_METHOD

ACCESS_TOKEN

REFRESH_TOKEN

CODE

EXPIRES_IN

DATA

LANDING_PAGE

EXPIRE_TIME

AUTHORIZATION_HEADER

BASIC_AUTH

BEARER_TOKEN

HTTP_GET

HTTP_POST

addExpireTime

httpHandler

timeService

random

Constructor Detail

OAuth2Client

OAuth2Client

Method Detail

mapToJsonValue

getAccessToken

getFirstValueOrNull

mapToUserInfo

getAuthRedirect

handlePostAuth

getSessionInfo

getUserInfo

refresh

createAuthRedirectUri

createAuthRedirectUri

createRequestForTokenRefresh

createRequestForUserInfoEndpoint

createRequestForTokenEndpoint

createRequestForTokenEndpoint

addClientIdAndSecret

storeResponse

createPostAuthResponse

getConfig

createAuthorizationState

createPkceVerifier