Authorization Code Flow

Authenticator handling authorization code flows in OIDC.

About

No identification is done by this authenticator. It acts as a controller for issuing Json Web Tokens (JWT). Typically this authenticator is the first point of contact coming from an OpenID Connect Relying Party, requesting identification.

This authenticaton controller can be considered a start and end touch point. The main purpose is to handle OpenID Connect specifics.

Actual user identification is done elsewhere.

When using this authenticator, the ID token is fetched from the token endpoint.

Configuration

Authenticator Type: OIDCAuthCodeFlow

Common Authenticator configuration can be found here.

Properties

Name	Description	Default value	Mandatory
required_authenticators	List of authenticators performing the actual authentication.	N/A
token_code_ttl	Time to live in milliseconds for the generated code. Previous parameter name token_endpoint_ttl is deprecated.	60000
access_token_ttl	Access token time to live in millisesonds. Previous parameter name userinfo_endpoint_ttl is deprecated.	60000
enable_refresh_token	Enables the use of refresh tokens.	false
refresh_token_ttl	Refresh token time to live in millisesonds.	1800000
id_token_ttl	ID token time to live in minutes.	5
id_token_headers	ID token headers. Previous parameter name jwt_headers is deprecated.	N/A
id_token_claims	ID token claims. Previous parameter name jwt_claims is deprecated.	N/A
access_token_headers	Access Token headers. ONLY used when sending access tokens as JWTs.	N/A
access_token_claims	Access Token claims. Previous parameter name userinfo_claims is deprecated.	N/A
use_jwt_access_tokens	Enables access tokens as JWT.	false
jwt_access_token_ttl	Access Token time to live in minutes.	5
keystore	Keystore reference or json object containing key store configuration. Used for JWT signing.	N/A
sign_jwt_keystore_password	Keystore password	N/A
sign_jwt_keystore_alias	Keystore alias	N/A
rps	List of relying parties. Must include at least one relying party.	N/A
required_request_parameters	Required parameters.	["response_type", "client_id", "redirect_uri", "scope", "nonce"]
no_prompt_pass_through	If the prompt request parameter is missing and a user session exists, the user is silently authenticated. Enables the same behaviour as if prompt=none and a user session exists.	false

Example

{
    "id": "auth00",
    "type": "OIDCAuthCodeFlow",
    "config": {
        "base_path": "/test/authn",
        "failure_location": "/authn/failure.html",
        "required_authenticators": [
            "auth_selector"
        ],
        "token_code_ttl": 90000,
        "access_token_ttl": 90000,
        "id_token_ttl": 6,
        "required_request_parameters": [
            "response_type",
            "client_id",
            "redirect_uri",
            "scope",
            "nonce"
        ],
        "keystore": {
            "path": "/fortified_test/keystore.p12",
            "password": "secret",
            "type": "PKCS12"
        },
        "sign_jwt_keystore_password": "secret",
        "sign_jwt_keystore_alias": "jwt",
        "id_token_headers": {
            "kid": ""
        },
        "id_token_claims": {
            "secret_id": "{{{session.id}}}",
            "test_claim": "static_claim",
            "email": "{{{item.mail}}}",
            "nonce": "{{{request.nonce}}}"
        },
        "access_token_claims": {
            "secret_id": "{{{session.id}}}",
            "userinfo_claim_test": "static_claim",
            "email": "{{{item.mail}}}",
            "email_verified": true,
            "address": {
                "street_address": "my address",
                "postal_code": "my postal code"
            },
            "given_name": "{{{item.givenName}}}",
            "subject": "{{{item.subject}}}"
        },
        "rps": [
            {
                "client_id": "provided",
                "client_secret": "provided",
                "redirect_uri": [
                    "https://auth.organisation.com/authenticate/oidcrp"
                ],
                "post_logout_redirect_uris": [
                    "https://auth.organisation.com/authenticate/oidcrp/loggedout"
                ],
                "pipe_id": "optional_pipe_id"
            }
        ]
    }
}

NOTE: id- & access-token claims can be configured globally on the authenticator OR for each relying party. Claims configured on the relying party trumps the global values.

Relying party Configuration

Properties

Name	Description	Default value	Mandatory
client_id	Used for identifying and authenticating the client.	N/A
client_secret	Used for identifying and authenticating the client.	N/A
redirect_uri	Redirect location where the authorization code or JWT should be sent.	N/A
post_logout_redirect_uris	Redirect location after logout.	N/A
pipe_id	Pipe reference. Pipe is run directly after user authentication. Used for collecting data for claims.	N/A
id_token_headers	ID token headers configured per RP. Previous parameter name jwt_headers is deprecated.	N/A
id_token_claims	ID token claims configured per RP. Previous parameter name jwt_claims is deprecated.	N/A
access_token_headers	Access Token headers configured per RP. ONLY used when sending access tokens as JWTs.	N/A
access_token_claims	Access Token claims configured per RP. Previous parameter name userinfo_claims is deprecated.	N/A
refresh_token_persist_pipe_id	Pipe to send the refresh token to. It is up to the administrator to decide what the pipe will do.	N/A
refresh_token_resolve_pipe_id	Pipe to load/resolve a refresh token. The pipe should also create and persist a new refresh token.	N/A

Example

"rps" : [{
    "client_id" : "provided",
    "client_secret" : "provided",
    "redirect_uri" : ["https://auth.organisation.com/authenticate/oidcrp"],
    "post_logout_redirect_uris" : ["https://auth.organisation.com/authenticate/oidcrp/loggedout"],
    "pipe_id" : "optional_pipe_id",
    "id_token_headers" : {
        "kid" : ""
    },
    "id_token_claims" : {
        "secret_id": "{{{session.id}}}",
        "test_claim": "static_claim",
        "email": "{{{item.mail}}}",
        "nonce": "{{{request.nonce}}}"
    },
    "access_token_claims" : {
        "secret_id": "{{{session.id}}}",
        "userinfo_claim_test": "static_claim",
        "email": "{{{item.mail}}}",
        "email_verified": true,
        "address": {
            "street_address": "my address", 
            "postal_code": "my postal code"
        },
        "given_name": "{{{item.givenName}}}",
        "subject": "{{{item.subject}}}"
    }
}]

Refresh Tokens

Refresh tokens can be described as "token granting token", which means they are sent to the OIDC server to obtain new ones.

Enable by setting the enable_refresh_token configuration parameter to true.

Optionally configure the refresh_token_ttl configuration parameter.

Default value is 1800000 milliseconds. This will enable refresh tokens valid for 30 minutes.

The OIDC module must have parameter use_refresh_token set to true.

Persisting refresh tokens

There is an option to send the newly created refresh token to a pipe which can be used to store the refresh token without keeping it in memory.

Enable the pipe by configuring the refresh_token_persist_pipe_id configuration parameter on the relying party section.

Loading refresh tokens

Refresh tokens are used with the token endpoint by setting the grant_type request parameter to refresh_token. I the refresh token was persisted in a pipe, use refresh_token_resolve_pipe_id configuration parameter on the relying party section to resolve/load the refresh token, create a new refresh token and persist that new refresh token.

The pipe must return a new refresh_token (string), access_token (string), id_token (string) and expires_in (long) in pipe response. All controls are done in the pipe.

Logging

On a successful authentication, an event is logged containing the following:

• WEB_100101

• IDENTIFIER (user traceid)

• DESTINATION_SERVICE_NAME (redirect URI)

• SOURCE_ADDRESS (user IP address)

Data sent to PIPE

All data put into the shared authentication state along with the HTTP headers are exposed and sent into the pipe.

Data put into the state by this authenticator is:

OIDC request data

Expected data from PIPE

In order to use data from PIPE the response must contain one item. All data from that item will be available when creating the ID token and access token.

Available data for ID_token and Access Token claims

Data is extracted with the help of expansions.

The following scopes are available:

Scope	Description	Example
request	The current authentication request including HTTP headers and params	{{{request.nonce}}}
item	Item properties AND the current authentication state (includes both local and global properties).	{{{item.mail}}}
session	The current session.	{{{session.sub}}}