OAuth2ClientState

nevisAuth 4.38.x HTTP client changes

The new HTTP client shipped with nevisAuth 4.38.0.12 will likely require changes in this auth state configuration, specifically in the area of certificate configuration and handling.

Visit the migration guide for additional information.

Preconditions and limitations

Each OAuth2 implementation is based on the provider’s flavor. As a consequence, the OAuth2 implementation of one OAuth2 identity provider may differ from the implementation of another OAuth2 identity provider. The OAuth2ClientState AuthState is able to work with at least the following OAuth2 identity providers:

• Facebook
• GitHub
• Instagram

Description

The following table describes the characteristics of the OAuth2ClientState AuthState.

Topic	Description
Class	ch.nevis.esauth.auth.states.oauth2.client.OAuth2ClientState
Logging	OAuth2Client
Auditing	none
Marker	none
Methods

Properties

• authorizationEndpoint (string(URL))

  The endpoint used for the authorization request.

  Supported are a valid URL, or a variable that is substituted with a valid URL during runtime.

• tokenEndpoint (string(URL))

  The endpoint used for the token request.

  Supported are a valid URL, or a variable that is substituted with a valid URL during runtime.

• userInfoEndpoint (string(URL))

  The endpoint used to get user information.

  Supported are a valid URL, or a variable that is substituted with a valid URL during runtime.

• emailEndpoint (string(URL), -)

  Optional endpoint used to get the user's email.

  Supported are a valid URL, or a variable that is substituted with a valid URL during runtime.

• redirectURI (string (URL))

  The redirect_uri used in the authorization request.

  Supported are a valid URL, or a variable that is substituted with a valid URL during runtime.

• clientId (string)

  The client_id used in the authorization and token request.

• clientSecret (string)

  The client_secret used in the token request. The AuthState supports both a fixed client secret and a variable that is substituted during runtime.

• scope (space-separated string)

  The requested scope used in the authorization request.

• claimsRequest (string)

  The claims request parameter. This value must be formatted in JSON and does not accept trailing spaces or tabs.

• arbitraryAuthRequestParam.[paramName] (string)

  Arbitrary additional request parameters used in the authorization request. The property supports variable substitution.

  Example

  <property name="arbitraryAuthRequestParam.[paramName]" value="[paramValue]" />

• userId (string, "${sess:[AuthStateName].idTokenClaim.sub}")

  The user ID by which the user will be authorized. The AuthState supports both a fixed user ID and a variable ID that is substituted during runtime.

• clientAuthMethod (string, "client_secret_basic")

  How the secret is sent to the token endpoint. There are two options:

  • client_secret_basic (default)

    The client secret and the client ID are sent to the token endpoint with the HTTP Basic authorization scheme.

  • client_secret_post

    The client secret and the client ID are sent to the token endpoint with the HTTP Post scheme.

  • client_secret_jwt

    The client secret and the client ID are sent to the token endpoint using JWT Bearer token.

• responseMode (string, "query")

  The way to handle authorization callback (to nevisAuth). The following options are available:

  • query (default)

    The callback is handled via GET request.

  • form_post

    The callback is handled via POST request.

• allowRedirect (boolean, true)

  After receiving a response from OAuth2 identity provider, OAuth2ClientState will automatically do redirect to the original request URL. Set allowRedirect to "false" to disable this behavior.

  info

  After you disable the redirect here, add another AuthState for redirecting back to the original request URL.

• httpclient.* (String)

  Configure the outgoing HTTP communication towards tokenEndpoint, userInfoEndpoint, emailEndpoint. For a list of valid HTTP properties, see HTTP Client.

Input

none

Transitions

• failed

  Authorization was not successful, nevisAuth cannot contact any provided endpoint, or an internal error occurred.

• ok

  Authorization was successful, have received the requested user information.

Output

• session:[AuthStateName].tokenResponse.[field]

  The value of the fields of the received token response. For example: OAuth2Client.tokenResponse.access_token = [encodedAccessToken]

• session:[AuthStateName].oauth2TokenClaim.[claimName]

  The value of the claims present in the token. For example: OAuth2Client.oauth2TokenClaim.id = [id]

Errors

none

Notes

none

Example

<AuthState name="oauth2TokenClaim" class="ch.nevis.esauth.auth.states.oauth2.client.OAuth2ClientState" final="false">
        <ResultCond name="ok" next="AuthDone"/>
        <ResultCond name="failed" next="AuthError"/>   
        <property name="authorizationEndpoint" value="[authorizationEndpoint]" />
        <property name="tokenEndpoint" value="[tokenEndpoint]" />
        <property name="userInfoEndpoint" value="[userInfoEndpoint]" />
        <property name="redirectURI" value="[redirectURI]" />
        <property name="clientId" value="[clientId]" />
        <property name="scope" value="openid email" />
        <property name="claimsRequest"
            value="{&quot;id_token&quot;:{&quot;given_name&quot;:null}, &quot;userinfo&quot;:{&quot;address&quot;:null}}" />
        <property name="clientSecret" value="[clientSecret]" />
        <property name="arbitraryAuthRequestParam.access_type" value="offline" />
        <property name="arbitraryAuthRequestParam.acr_values" value="#{StringUtils.contains(inargs['auth-strength'],'2') ? 'qoa2':'qoa1'}" />
</AuthState>