OpenID Connect (OIDC) Authentication¶

Testflinger supports OpenID Connect (OIDC) authentication for simplifying the management of user logins. This enables integration with existing enterprise identity systems (such as SSO providers), centralizes access control, and allows administrators to manage user lifecycle through the identity provider rather than the Testflinger server itself.

When OIDC is enabled, Testflinger restricts access to its resources to authenticated users only. Users accessing the web interface must authenticate via the OIDC provider while CLI users must either authenticate with the OIDC provider or with a Testflinger client_id and secret_key pair before they can use any functionality. When OIDC is not configured, the server allows anonymous access for non-restricted endpoints. For a list of endpoints and their restriction to different roles, please refer to API endpoint roles.

Provider Capabilities¶

Testflinger relies on specific OIDC capabilities that the configured provider must support:

Token authentication: Testflinger uses client_secret_basic (HTTP Basic Auth in the Authorization header) for confidential clients, or falls back to including the OIDC client_id in the request body for public clients.
Authorization Code Flow: required for web interface authentication, using the authorization_code grant type.
Device Authorization Flow: required for CLI authentication, using the urn:ietf:params:oauth:grant-type:device_code grant type.
Scopes: Testflinger requests openid, profile, and email scopes. The email claim is used as the user’s stable identity within Testflinger.
Redirect URI: the provider must support a redirect URI with the following format for the Authorization Code Flow: https://<testflinger-server-hostname>/auth/callback

Authorization Code Flow¶

This flow is used for web interface authentication.

On initial access to the web interface, users will need to click the Sign In button and will be redirected to the OIDC provider’s login page. After successful authentication, the OIDC provider will redirect the user back to the Testflinger page and all resources will be accessible to the user.

Device Authorization Flow¶

This flow is used for CLI authentication.

Note

If a user provides Testflinger client_id and secret_key pair, the CLI will use these credentials to authenticate with the server directly, bypassing the OIDC device authorization flow.

When users attempt to use the CLI, they will be prompted to visit a URL in their browser and enter a user code. Testflinger acts as a proxy between the user and the OIDC provider: the CLI polls the Testflinger server for the authentication status, while the server exchanges the device code with the OIDC provider.

Once the user completes authentication, the Testflinger server issues its own access and refresh tokens to the CLI which can be used to authenticate directly with Testflinger without being redirected to the OIDC provider on each command until these credentials expire.