Skip to main content
Version: 9.2605.x RR

AccessTokenConsumer

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.

Introduction and overview​

The AccessTokenConsumer AuthState implements the validation of access tokens issued by the AuthorizationServer AuthState (Bearer Tokens). It is used to protect access to the resource server.

If the access token provided by the client can be successfully validated, an authenticated session is established using the user ID the end-user was authenticated with at the authorization server. The lifetime of this session is limited to the lifetime of the access token. For details, see Session lifetime. The roles are set to the scope values requested in the authorization request which lead to the issuance of the access token.

Only bearer tokens issued by the AuthorizationServer AuthState and sent using the authorization request header field are accepted. An example HTTP request for a protected resource is

GET /resource HTTP/1.1
Host: server.example.com
Authorization: Bearer [token]

where [token] needs to be replaced by the token issued by the authorization server.

If an access token could not be validated, an error code according to RFC6750 is returned.

To be compatible with the tokens issued by the authorization server, the key material configured in the AccessTokenConsumer AuthState must match the key material configured in the AuthorizationServer AuthState.

Session lifetime​

After validating a JWT access token, the AuthState sets the session attribute ch.nevis.session.notOnOrAfter to the exp claim of the token. As a result:

  • The TokenAssembler caps the ttl of the SecToken at this time. A shorter configured ttl or session lifetime still applies; a longer one does not extend the limit.
  • nevisAuth no longer accepts the session after this time.

This is intended when the AuthState protects a resource server: the session must not outlive the access token.

nevisProxy does not adapt its session timeouts, such as MaxInactiveInterval, to the access token. When a request accesses a session with an expired SecToken, the IdentityCreationFilter applies its SectokenExpireStrategy (default kill). Logout requests are the exception: nevisProxy forwards them to nevisAuth with the expired SecToken.

AccessTokenConsumer in an interactive login flow

The limit also applies if the AuthState is only one step of a longer login, for example followed by a one-time password (OTP). A 5-minute access token then results in a SecToken valid for at most 5 minutes, regardless of the session lifetime of the realm.

If the next request after the SecToken expired is a logout, nevisAuth rejects the SecToken (token not valid at this time) and cannot resolve the session. The logout is then handled by the default domain: the first configured Domain, unless a domain is marked as default. See Initial request-dispatching. As a result, the logout flow of an unrelated realm may run.

To apply the session lifetime of the realm instead, remove ch.nevis.session.notOnOrAfter directly after the AccessTokenConsumer, for example with a TransformAttributes AuthState:

<AuthState name="RemoveSessionNotOnOrAfter" class="ch.nevis.esauth.auth.states.standard.TransformAttributes" final="false">
<ResultCond name="ok" next="NextState"/>
<Response value="AUTH_ERROR"/>
<property name="removeOnEmptyValue" value="true"/>
<property name="sess:ch.nevis.session.notOnOrAfter" value=""/>
</AuthState>

Or with a ScriptState:

session.remove('ch.nevis.session.notOnOrAfter')
response.setResult('ok')

Description​

The following table and chapters describe the characteristics of the AuthState.

TopicDescription
Classch.nevis.esauth.auth.states.oauth2.consumer.AccessTokenConsumer
LoggingOAuth2Consumer
Auditingnone
MarkerOAUTH2:token
Methodsprocess

Properties​

  • keystoreref (string, "DefaultKeyStore")

    Together with the keyobjectref identifies the key material reference to validate the access token.

  • keyobjectref (string, "DefaultSigner")

    This property configures the key material to use when validating the access token. The access token is decrypted using the configured private key. Currently, RSA and Elliptic Curve (EC) keys are supported.

  • keystoreref.old, keyobjectref.old and keycurve.old

    This property configures the previous certificate to use when validating the token(s) during the certificate rollover period. Currently, RSA and Elliptic Curve (EC) keys are supported.

  • propagationScope (string, "session")

    Define propagation scope to store information for following AuthStates.

  • introspectionEndpoint (string (URI), -)

    Defines external token introspection endpoint for checking whether access token is still active. If this property is not configured, or the authState cannot connect to external token introspection endpoint, the normal validation process takes place.

    info

    The use of this property requires that the introspection endpoint does not use authentication.

  • httpclient.* (String)

    Configure the outgoing HTTP communication to the introspectionEndpoint. For a list of valid HTTP properties, see HTTP Client.

Input​

none

Transitions​

  • token-valid

    The provided access token is valid.

  • token-invalid

    The provided access token is invalid.

Output​

  • [propagationScope]:oauth2.token.claim.[field]

    Claims present in the access token. For details, see Token format.

Errors​

none

Notes​

none

Example​

<AuthState
class="ch.nevis.esauth.auth.states.oauth2.consumer.AccessTokenConsumer"
final="false"
name="OAuthTokenConsumer"
resumeState="true">
<ResultCond name="token-invalid"
next="AuthError" />
<ResultCond name="token-valid"
next="AuthDone" />
<property name="keystoreref"
value="OAuthKeyStore" />
<property name="keyobjectref"
value="OAuthTokenVerifier" />
</AuthState>