Device Authorization Flow

Authenticator handling OAuth 2.0 Device Authorization Flow in OIDC.

There are two locations where configuration for an OIDC OpenID Provider (OP) using the Device Authorization Flow can be managed:

Verification Flow / Authenticator Chain – You configure the wrapper authenticator and the authenticators that perform the actual user authentication here.
Back-Channel Endpoints – By clicking the following link, you can manage back-channel endpoints such as device_authorize, Token and discovery metadata.

About

No identification is done by this authenticator itself. It acts as a controller for the OAuth 2.0 Device Authorization Flow and for issuing tokens once the user has completed authentication.

Typically this authenticator is the user-facing verification entry point for flows started by a relying party using device_authorize.

Actual user identification is done elsewhere in the configured chain.

The normal pattern is:

A relying party starts Device Flow using the OIDC module.
The end-user visits verification_uri or verification_uri_complete.
UserCodeAuthenticator validates the user_code and binds the verification flow to the correct device session.
The remaining authenticators in the chain perform the actual authentication.
The relying party polls the token endpoint until the flow completes.

Configuration

Common Authenticator configuration can be found here.

Properties
Example

Name	Description	Default value	Mandatory
`chain`	List of authenticators performing the actual user authentication. In practice the first step is typically a `DeviceUserCode` authenticator followed by a selector or another authenticator.	N/A	true
`sign_ref`	List of OIDC signing keys used for overlapping key rotation. Recommended for new configurations.	N/A	false
`keystore`	Legacy single-key keystore configuration used for JWT signing when `sign_ref` is not configured.	N/A	false
`id_token_ttl`	ID token time to live in minutes.	`5`	false
`access_token_ttl`	Access token time to live in milliseconds.	`60000`	false
`use_jwt_access_tokens`	Enables access tokens as JWT.	`false`	false
`jwt_access_token_ttl`	Access Token time to live in minutes when access tokens are sent as JWT.	`5`	false
`enable_refresh_token`	Enables the use of refresh tokens.	`false`	false
`refresh_token_ttl`	Refresh token time to live in milliseconds.	`1800000`	false
`rps`	List of relying parties. Must include at least one relying party.	N/A	true
`success_location`	If configured, the user agent is redirected here when the verification flow completes successfully. If omitted, a simple built-in completion page is returned.	N/A	false
`failure_location`	If configured, the user agent is redirected here when the verification flow fails. If omitted, a simple built-in error page is returned.	N/A	false

{
    "id": "device",
    "type": "OIDCDeviceAuthorizationFlow",
    "config": {
        "base_path": "/access/authn",
        "success_location": "/device-flow/success",
        "failure_location": "/device-flow/failure",
        "chain": [
            {
                "id": "device_user_code",
                "required": true
            },
            {
                "id": "auth_selector",
                "required": true
            }
        ],
        "sign_ref": [
            {
                "keystore": {
                    "path": "/fortified_test/oidc-2026-q1.p12",
                    "password": "secret",
                    "key_password": "secret",
                    "alias": "oidc-2026-q1",
                    "type": "PKCS12"
                }
            }
        ],
        "id_token_ttl": 5,
        "access_token_ttl": 60000,
        "enable_refresh_token": false,
        "rps": [
            {
                "client_id": "tv-client",
                "client_secret": "secret",
                "redirect_uri": [
                    "https://www.example.com/callback"
                ]
            }
        ]
    }
}

UserCodeAuthenticator

The normal first step in the chain is a DeviceUserCode authenticator.

Its purpose is to:

validate the user_code
resolve the correct device session
bind the browser verification flow to that device session before continuing in the chain

The authenticator supports both:

prefilled user_code from verification_uri_complete
manual entry of user_code

API

The DeviceUserCode authenticator follows the general conventions of the Fortified Web Authenticator API.

General requirements

All requests use the HTTP PUT method with Content-Type: application/json, sent to the directory URL the view was loaded from. The session cookie must be sent with every request.

Messages

Message	Purpose
`init`	Fetch the current status and any prefilled `user_code`. Send it when the view loads.
`start`	Submit the `user_code` and bind the browser to the device session.
`cancel`	Cancel the verification.

Init

Send this when the view loads. It moves a pending authenticator into progress and reports whether a user_code was supplied in the URL, so the view can prefill the input field.

Request
Response

{
    "type": "init"
}

{
    "type": "init",
    "success": true,
    "data": {
        "status": "IN_PROGRESS",
        "prefilled": "<user-code>"
    }
}

prefilled is the user_code request parameter, or an empty string when none was supplied. status is the authenticator status: PENDING, IN_PROGRESS, COMPLETED, or FAILED.

Starting a verification

Submit the code the user entered. When user_code is omitted from data, the user_code request parameter is used instead.

{
    "type": "start",
    "data": {
        "user_code": "<user-code>"
    }
}

{
    "type": "complete",
    "success": true,
    "data": {
        "location": "<next-location>"
    }
}

A failure message whose reason describes why the code could not be bound, for example Missing user_code when the code is absent, or an expired, unknown, or already used code.

The binding is cleared on failure, so the user can correct the code and send start again.

Cancel a request

A request can be canceled at any time. This is done by sending a cancel request.

{
    "type": "cancel"
}

Response from server

Expect HTTP status code 200. Anything else is to be considered an error.

The body is a JSON message: an init message while the code is being collected, and a complete, cancel, or failure message once the step ends, as described in Web Authenticator API.

Success, failure and cancel

If success_location is configured, the user is redirected there after a successful verification flow.

If failure_location is configured, the user is redirected there after a failed verification flow.

If these locations are not configured, the wrapper returns a simple built-in text response.

When the user cancels later steps in the verification chain, the underlying Device Flow request remains PENDING. This means the user can re-enter the same user_code and continue the flow as long as the request has not expired.

Session lifecycle

The flow uses a device session in the shared Access session model.

Important behavior:

the same user_code can be reused while the flow is PENDING
after the first successful token response, the device-flow session state is cleaned up
the design supports clustered/session-replicated deployments

Completion pages

If you want branded completion pages instead of the built-in text response, set success_location and failure_location to your own endpoints.

One simple way to do this is to configure an InformationEndpoint that serves static HTML pages with your normal layout and branding.

Logging

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

WEB_100101
IDENTIFIER (user traceid)
DESTINATION_SERVICE_NAME (OIDC client_id, if available)
SOURCE_ADDRESS (user IP address)

On a failed verification flow, an event is logged containing the following:

WEB_100102
IDENTIFIER (user traceid)
DESTINATION_SERVICE_NAME (OIDC client_id, if available)
SOURCE_ADDRESS (user IP address)

The back-channel part of Device Flow is configured on the OIDC module. See Device Authorization Flow.