> For the complete documentation index, see [llms.txt](https://docs.fortifiedid.se/access/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fortifiedid.se/access/key-components/authenticators/protocol-managers/oidc/device-authorization-flow.md).

# 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:

1. **Verification Flow / Authenticator Chain** – You configure the wrapper authenticator and the authenticators that perform the actual user authentication here.
2. **Back-Channel Endpoints** – By clicking the following [link](/access/key-components/modules/oidc/device-authorization-flow.md), 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:

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

## Configuration

{% hint style="info" %}
**Authenticator Type:** `OIDCDeviceAuthorizationFlow`
{% endhint %}

Common Authenticator configuration can be found [here](/access/key-components/authenticators/common-configuration.md).

{% tabs %}
{% tab title="Properties" %}

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

{% tab title="Example" %}

```json
{
    "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"
                ]
            }
        ]
    }
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
For the OIDC signing-key model, overlapping rotation, and legacy compatibility, see [OIDC signing keys](/access/key-components/modules/oidc/signing-keys.md).
{% endhint %}

## 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`

## 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)

## Related configuration

The back-channel part of Device Flow is configured on the OIDC module. See [Device Authorization Flow](/access/key-components/modules/oidc/device-authorization-flow.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.fortifiedid.se/access/key-components/authenticators/protocol-managers/oidc/device-authorization-flow.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.