205hlab-mirrors/authentik
2
0
Fork 0
mirror of https://github.com/goauthentik/authentik.git synced 2026-06-17 19:09:11 +03:00
Code Issues Packages Projects Releases Wiki Activity

website/docs: clarify OAuth2 provider overview (#22144)

Browse Source
This commit is contained in:
Dominic R
2026-06-04 13:05:04 -04:00
committed by GitHub
parent 313eb26ac4
commit 5ad73a0f6a
1 changed files with 34 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files
website/docs/add-secure-apps/providers/oauth2/index.mdx
+34 -34
View File
@@ -1,29 +1,29 @@
---
title: OAuth 2.0 provider
title: OAuth2/OpenID provider
---
In authentik, you can [create](./create-oauth2-provider.md) an [OAuth 2.0](https://oauth.net/2/) provider that authentik uses to authenticate the user to the associated application. This provider supports both generic OAuth 2.0 as well as OpenID Connect (OIDC).
In authentik, you can [create](./create-oauth2-provider.md) an [OAuth 2.0](https://oauth.net/2/) provider that authenticates users to an associated application. The provider supports generic OAuth 2.0 clients and OpenID Connect (OIDC) relying parties.
## authentik and OAuth 2.0
It's important to understand how authentik works with and supports the OAuth 2.0 protocol, so before taking a [closer look at OAuth 2.0 protocol](#about-oauth-20-and-oidc) itself, let's cover a bit about authentik.
Before looking at the [OAuth 2.0 protocol](#about-oauth-20-and-oidc), it helps to understand the roles that authentik can play.
authentik can act either as the OP (OpenID Provider, with authentik as the IdP), or as the RP (Relying Party, or the application that uses OAuth 2.0 to authenticate). If you want to configure authentik as an OP, create an OAuth 2.0 provider. If you want authentik to serve as the RP, then configure a [source](../../../users-sources/sources/index.md). Of course, authentik can serve as both the RP and OP, if you want to use the authentik OAuth provider and also use sources.
authentik can act as the OpenID Provider (OP), where authentik is the identity provider, or as the Relying Party (RP), where authentik uses an external OAuth 2.0 or OIDC provider for authentication. To use authentik as the OP, create an OAuth 2.0 provider and attach it to an application. To use authentik as the RP, configure an OAuth [source](../../../users-sources/sources/index.md). The same authentik instance can act as both an OP and an RP.
authentik supports all standard OAuth 2.0 flows (authorization code, client_credentials, implicit, hybrid, device code) and grant types, and follows the [OIDC spec](https://openid.net/specs/openid-connect-core-1_0.html). OAuth 2.0 in authentik supports PKCE, [GitHub compatibility](./github-compatibility.md), and the RP receives data from our scope mapping system.
authentik supports standard OAuth 2.0 flows and grant types, including authorization code, client credentials, implicit, hybrid, refresh token, and device code. authentik also follows the [OIDC spec](https://openid.net/specs/openid-connect-core-1_0.html), supports PKCE and [GitHub compatibility](./github-compatibility.md), and uses [scope mappings](../property-mappings/index.md#scope-mappings-with-oauth2) to control the claims returned to the RP.
The authentik OAuth 2.0 provider comes with all the standard functionality and features of OAuth 2.0, including the OAuth 2.0 security principles such as no cleartext storage of credentials, configurable encryption, configurable short expiration times, and the configuration of automatic rotation of refresh tokens. In short, authentik offers comprehensive OAuth 2.0 support.
The OAuth 2.0 provider includes security-focused configuration options such as no cleartext storage of credentials, configurable signing and encryption keys, short token expiration times, and automatic refresh token rotation.
## About OAuth 2.0 and OIDC
OAuth 2.0 is an authorization protocol that allows an application (the RP) to delegate authorization to an OP. OIDC is an authentication protocol built on top of OAuth 2.0, which provides identity credentials and other data on top of OAuth 2.0.
OAuth 2.0 is an authorization framework that lets an application delegate authorization to an authorization server. OIDC builds authentication on top of OAuth 2.0, adding identity tokens and standardized user claims.
**OAuth 2.0** typically requires two requests (unlike the previous "three-legged" OAuth 1.0). The two "legs", or requests, for OAuth 2.0 are:
A typical OAuth 2.0 authorization code flow has two main requests:
1. An authorization request is prepared by the RP and contains parameters for its implementation of OAuth and which data it requires, and then the User's browser is redirected to that URL.
2. The RP sends a request to authentik in the background to exchange the access code for an access token (and optionally a refresh token).
1. The RP prepares an authorization request that describes the requested access and redirects the user's browser to the OP.
2. After the OP authenticates the user, the RP exchanges the authorization code for an access token and, optionally, a refresh token.
In detail, with OAuth 2.0 when a user accesses the application (the RP) via their browser, the RP then prepares a URL with parameters for the OpenID Provider (OP), which the user's browser is redirected to. The OP authenticates the user and generates an authorization code. The OP then redirects the client (the user's browser) back to the RP, along with that authorization code. In the background, the RP then sends that same authorization code in a request authenticated by the `client_id` and `client_secret` to the OP. Finally, the OP responds by sending an Access Token saying this user has been authorized (the RP is recommended to validate this token using cryptography) and optionally a Refresh Token.
When a user opens the application, the RP builds an authorization URL and redirects the user's browser to the OP. The OP authenticates the user and redirects the browser back to the RP with an authorization code. The RP then sends the code to the OP in a back-channel request, authenticating with its `client_id` and, for confidential clients, its `client_secret`. The OP returns an access token and, when configured, a refresh token. The RP should validate received tokens before trusting their contents.
The image below shows a typical authorization code flow.
@@ -63,7 +63,7 @@ sequenceDiagram
| OpenID Configuration | `/application/o/<application slug>/.well-known/openid-configuration` |
:::caution Reserved application slugs
Due to how the OAuth2 provider endpoints are structured, you cannot create applications that use the slugs `authorize`, `token`, `device`, `userinfo`, `introspect`, or `revoke` as these would conflict with the global OAuth 2.0 endpoints.
Due to how the OAuth2/OpenID provider endpoints are structured, you cannot create applications that use the slugs `authorize`, `token`, `device`, `userinfo`, `introspect`, or `revoke` as these would conflict with the global OAuth 2.0 endpoints.
:::
### Cross-provider token introspection and revocation
@@ -74,11 +74,11 @@ For cross-provider introspection or revocation, authenticate the request with a
### Additional configuration options with Redirect URIs
When using an OAuth 2.0 provider in authentik, the OP must validate the provided redirect URI by the RP. An authentik admin can configure a list in the **Redirect URI** field on the Provider.
When using an OAuth 2.0 provider in authentik, the OP must validate the redirect URI provided by the RP. An authentik administrator can configure allowed redirect URIs in the provider's **Redirect URI** field.
When you create a new OAuth 2.0 provider and app in authentik and you leave the **Redirect URI** field empty, then the first time a user opens that app, authentik uses that URL as the saved redirect URL.
If you leave the **Redirect URI** field empty when creating a provider and application, authentik saves the first redirect URI used when a user opens the application.
For advanced use cases, an authentik admin can use regular expressions (regex) instead of a redirect URL. For example, if you want to list ten different applications, instead of listing them all individually, you can create an expression with wildcards. When using regex, be aware that authentik uses a dot as a separator in the URL, but in regex a dot means "one of any character", a wildcard. You should therefore escape the dot with `\.` to prevent its interpretation as a wildcard.
For advanced use cases, an authentik administrator can use regular expressions instead of static redirect URLs. For example, you can use a regular expression to match a group of related redirect URLs instead of listing each URL individually. When matching literal periods in hostnames, escape them as `\.` because, in regular expressions, an unescaped period matches any character.
### OAuth2/OpenID Connect back-channel logout
@@ -109,11 +109,11 @@ Global issuer mode still serves the discovery document at `https://authentik.com
There are three general flows of OAuth 2.0:
1. Web-based application authorization (Authorization code, Implicit, Refresh token)
2. Client credentials (Machine-to-machine)
1. Web-based application authorization (authorization code, implicit, and hybrid)
2. Client credentials (machine-to-machine)
3. Device code
Additionally, the [Refresh token](#refresh-token-grant) (grant type) is optionally used with any of the above flows, as well as the client credentials and device code flows.
The [refresh token](#refresh-token-grant) grant type can be used with several flows to obtain a new access token without another interactive login.
You can define which grant types are available for your OAuth2 provider when you [create and configure the provider](./create-oauth2-provider.md). By default, all types are selected.
@@ -127,27 +127,27 @@ The flows and grant types used in this case are those used for a typical authori
#### Authorization code
The authorization code is for environments with both a client and an application server, where the back and forth happens between the client and an app server (the logic lives on app server). The RP needs to authorize itself to the OP. Client ID (public, identifies which app is talking to it) and client secret (the password) that the RP uses to authenticate.
The authorization code grant is intended for applications with a backend server. The browser receives an authorization code, and the backend exchanges that code for tokens. During the exchange, confidential clients authenticate to the OP with their client ID and client secret.
If you configure authentik to use "Offline access" then during the initial auth the OP sends two tokens, an access token (short-lived, hours, can be customized) and a refresh token (typically longer validity, days or infinite). The RP (the app) saves both tokens. When the access token is about to expire, the RP sends the saved refresh token back to the OP, and requests a new access token. When the refresh token itself is about to expire, the RP can also ask for a new refresh token. This can all happen without user interaction if you configured the offline access.
If you configure authentik to allow offline access, the OP can return both a short-lived access token and a longer-lived refresh token during the initial authorization. The RP stores the tokens and uses the refresh token to request a new access token before the current access token expires. Depending on the provider settings, the RP can also receive a rotated refresh token without requiring another user interaction.
:::info
Starting with authentik 2024.2, applications only receive an access token. To receive a refresh token, both applications and authentik must be configured to request the `offline_access` scope. In authentik this can be done by selecting the `offline_access` Scope mapping in the provider settings.
Starting with authentik 2024.2, applications only receive an access token by default. To receive a refresh token, the application must request the `offline_access` scope and the authentik provider must include the `offline_access` scope mapping.
:::
The authorization code grant type is used to convert an authorization code to an access token (and optionally a refresh token). The authorization code is retrieved through the authentik [Authorization flow](../../flows-stages/flow/index.md), can only be used once, and expires quickly.
The authorization code grant converts an authorization code into an access token and, optionally, a refresh token. The authorization code is issued by the authentik [authorization flow](../../flows-stages/flow/index.md), can only be used once, and expires quickly.
#### Implicit
:::info
The OAuth 2.0 [Security Best Current Practice document](https://tools.ietf.org/html/draft-ietf-oauth-security-topics) recommends against using the Implicit flow entirely, and OAuth 2.0 for Browser-Based Apps describes the technique of using the authorization code flow with PKCE instead. ([source](https://oauth.net/2/grant-types/implicit/))
The OAuth 2.0 [Security Best Current Practice document](https://tools.ietf.org/html/draft-ietf-oauth-security-topics) recommends against using the implicit flow. OAuth 2.0 for browser-based apps recommends using the authorization code flow with PKCE instead. ([source](https://oauth.net/2/grant-types/implicit/))
:::
This flow is intended for modern single‑page applications or downloaded apps that run entirely on the client side (all JavaScript, no backend logic) and have no server that can safely store secrets or exchange tokens. Because the client secret cannot be kept secure on the user’s device, the implicit flow is required in these architectures. With the implicit flow, the application skips the second request in the authorization code flow: after the initial authorization request, the client receives a token directly. Using cryptographic checks such as PKCE, the client can verify that it is the intended recipient and that it is safe to use the token. The RP can then use cryptography to validate the token.
The implicit flow was designed for browser-only or installed applications that cannot safely store a client secret. In this flow, the OP returns tokens directly from the authorization request instead of requiring a separate back-channel token exchange. For new browser-based applications, use the authorization code flow with PKCE instead.
#### Hybrid
The Hybrid flow is an OpenID Connect flow that incorporates traits of both the Implicit flow and the Authorization Code flow. It provides an application instant access to an ID token while ensuring secure and safe retrieval of access tokens and refresh tokens. This can be useful in situations where the application needs to quickly access information about the user, while in the background doing further processing to get additional tokens before gaining access to additional resources.
The hybrid flow is an OpenID Connect flow that combines parts of the implicit flow and the authorization code flow. It can return an ID token immediately while the application completes a back-channel exchange to retrieve access tokens and refresh tokens.
### 2. Client credentials
@@ -157,13 +157,13 @@ For more information, see [Machine-to-machine authentication](./machine_to_machi
### 3. Device code
The device code flow is used in situations where there is no browser and limited options for text or data input from a client ("input-constrained devices"). For example, using a subscription TV program on a television, where you use a website on your mobile device to input a code displayed on the TV, authenticate, and then you are logged in to the TV.
The device code flow is used when a device has no browser or has limited text input. For example, a TV application can display a code that the user enters on another device to authenticate the session.
For more information, see [Device code flow](./device_code.md).
#### Refresh token grant
Refresh tokens can be used as long-lived tokens to access user data, and further renew the refresh token down the road.
Refresh tokens let an application obtain new access tokens without requiring another interactive login. Depending on the provider settings, refresh tokens can also be rotated when they are used.
:::info
Starting with authentik 2024.2, the refresh token grant type requires the `offline_access` scope.
@@ -178,7 +178,7 @@ Scopes can be configured using scope mappings, a type of [property mapping](../p
By default, every user that has access to an application can request any of the configured scopes. Starting with authentik 2022.4, you can do additional checks for the scope in an expression policy (bound to the application):
```python
# There are additional fields set in the context, use `ak_logger.debug(request.context)` to see them.
# There are additional fields set in the context; use `ak_logger.debug(request.context)` to see them.
if "my-admin-scope" in request.context["oauth_scopes"]:
return ak_is_group_member(request.user, name="my-admin-group")
@@ -187,7 +187,7 @@ return True
## Default & special scopes
When a client does not request any scopes, authentik will treat the request as if all configured scopes were requested. Depending on the configured authorization flow, consent still needs to be given, and all scopes are listed there.
When a client does not request any scopes, authentik treats the request as if all configured scopes were requested. Depending on the configured authorization flow, consent still needs to be given, and all scopes are listed there.
This does _not_ apply to special scopes, as those are not configurable in the provider.
@@ -201,13 +201,13 @@ This does _not_ apply to special scopes, as those are not configurable in the pr
### authentik
- `goauthentik.io/api`: This scope grants the refresh token access to the authentik API on behalf of the user
- `goauthentik.io/api`: This scope grants the refresh token access to the authentik API on behalf of the user.
### GitHub compatibility
- `user`: No-op, is accepted for compatibility but does not give access to any resources
- `read:user`: Same as above
- `user:email`: Allows read-only access to `/user`, including email address
- `user`: No-op, is accepted for compatibility but does not give access to any resources.
- `read:user`: Same as above.
- `user:email`: Allows read-only access to `/user`, including email address.
- `read:org`: Allows read-only access to `/user/teams`, listing all the user's groups as teams.
### Email scope verification
@@ -242,4 +242,4 @@ When **Signing Key** is not selected, authentik signs JWTs symmetrically with th
### Encryption
authentik can also encrypt JWTs (turning them into JWEs) it issues by selecting an **Encryption Key** in the provider. When selected, all JWTs will be encrypted symmetrically using the selected certificate. authentik uses the `RSA-OAEP-256` algorithm with the `A256CBC-HS512` encryption method.
authentik can also encrypt JWTs (turning them into JWEs) that it issues by selecting an **Encryption Key** in the provider. When selected, all JWTs will be encrypted using the selected certificate. authentik uses the `RSA-OAEP-256` key management algorithm with the `A256CBC-HS512` content encryption method.