website/docs: update and rearchitect the oauth2 provider docs

website/docs/add-secure-apps/providers/oauth2/client_credentials.md

@@ -1,4 +1,4 @@
-# Machine-to-machine authentication
+## Machine-to-machine authentication
 
 Client credentials can be used for machine-to-machine communication authentication. Clients can authenticate themselves using service-accounts; standard client_id + client_secret is not sufficient. This behavior is due to providers only being able to have a single secret at any given time.
 

website/docs/add-secure-apps/providers/oauth2/create-oauth2-provider.md

@@ -0,0 +1,20 @@
+---
+title: Create an OAuth2 provider
+---
+
+To add a provider (and the application that uses the provider for authentication) use the Application Wizard, which creates both the new application and the required provider at the same time. For typical scenarios, authentik recommends that you use the Wizard to create both the application and the provider together. (Alternatively, use our legacy process: navigate to **Applications --> Providers**, and then click **Create**.)
+
+1. Log into authentik as an admin, and navigate to **Applications --> Applications**.
+
+2. Click **Create with Wizard**.
+
+3. In the **New application** wizard, define the application details, and then click **Next**.
+
+4. Select the **Provider Type** of **OAuth2/OIDC***, and then click **Next**.
+
+5. On the **Configure OAuth2/OpenId Provider** page,
+
+**Submit**.
+
+
+-   Configure Offline access (though Jens says it is diff for each app, the only thing we do in authentik is to add a scope mapping (a default one that you select when you create the provider).

website/docs/add-secure-apps/providers/oauth2/github-compatibility.md

@@ -0,0 +1,23 @@
+---
+title: GitHub compatibility
+---
+
+The OAuth2 provider also exposes a GitHub-compatible endpoint. This endpoint can be used by applications, which support authenticating against GitHub Enterprise, but not generic OpenID Connect.
+
+To use any of the GitHub Compatibility scopes, you have to use the GitHub Compatibility Endpoints.
+
+| Endpoint        | URL                         |
+| --------------- | --------------------------- |
+| Authorization   | `/login/oauth/authorize`    |
+| Token           | `/login/oauth/access_token` |
+| User Info       | `/user`                     |
+| User Teams Info | `/user/teams`               |
+
+To access the user's email address, a scope of `user:email` is required. To access their groups, `read:org` is required. Because these scopes are handled by a different endpoint, they are not customisable as a Scope Mapping.
+
+## Special scopes for 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
+-   `read:org`: Allows read-only access to `/user/teams`, listing all the user's groups as teams.

website/docs/add-secure-apps/providers/oauth2/index.md

@@ -1,57 +1,136 @@
 ---
-title: OAuth2 Provider
+title: OAuth 2.0 provider
 ---
 
-This provider supports both generic OAuth2 as well as OpenID Connect
+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 OAuth2 as well as OpenID Connect (OIDC).
 
-Scopes can be configured using scope mappings, a type of [property mapping](../property-mappings/index.md#scope-mappings).
+## authentik and OAuth 2.0
 
-| Endpoint             | URL                                                                  |
-| -------------------- | -------------------------------------------------------------------- |
-| Authorization        | `/application/o/authorize/`                                          |
-| Token                | `/application/o/token/`                                              |
-| User Info            | `/application/o/userinfo/`                                           |
-| Token Revoke         | `/application/o/revoke/`                                             |
-| End Session          | `/application/o/<application slug>/end-session/`                     |
-| JWKS                 | `/application/o/<application slug>/jwks/`                            |
-| OpenID Configuration | `/application/o/<application slug>/.well-known/openid-configuration` |
+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.
+
+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, then you create a provider, then use the 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.
+
+All standard OAuth 2.0 flows (authorization code, client_credentials, implicit, hybrid, device code) and grant types are supported in authentik, and we follow the [OIDC spec](https://openid.net/specs/openid-connect-core-1_0.html). OAuth 2.0 in authentik supports OAuth, PKCE, [Github compatibility](./github-compatibility.md) and the RP receives data from our scope mapping system.
+
+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, our OAuth 2.0 protocol support provides full coverage.
+
+## About OAuth 2.0 and OIDC
+
+OAuth 2.0 is an authorization protocol that allows an application (RP) to delegate authorization to an OP. OIDC is an authentication protocol built on top of OAuth2, which provides identity credentials and other data on top of OAuth2.
+
+**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:
+
+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).
+
+In detail, with OAuth2 when a user accesses the application (known as the RP or Relying Party) via their browser, the RP then prepares a URL with parameters for the OpenID Provider (OP), which the users'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 authorised (the RP is recommended to validate this token using cryptography) and optionally a Refresh Token.
+
+The image below shows a typical authorization code flow.
+
+```mermaid
+sequenceDiagram
+    participant user as User
+    participant rp as RP (Relying Party)
+    participant op as OP (OpenID Provider)
+
+    user->>rp: User accesses application
+    rp->>user: RP prepares authorization request & redirects user to OP
+
+    user->>op: User authentication & authorization occurs
+    op->>rp: Redirect back to the RP with an authorization code
+
+    rect rgb(255, 255, 191)
+
+        rp->>op: Exchange authorization code
+        op->>rp: RP receives Access token (optionally Refresh Token)
+    end
+
+    rp->>user: User is logged in
+```
+
+### 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 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.
 
-## GitHub Compatibility
+For advanced use cases, an authentik admin can use regular expressions (regex) instead of a redirect URL. For example, if you want to list 10 diff applications, instead of listing all ten you can create an expression with wildcards. Be aware, when using regex, that authetnik uses a dot as a separator in the URL, but in regex a dot means "one of any character", a wildcard. So you should escape the dot to prevent its interpration as a wildcard.
 
-This provider also exposes a GitHub-compatible endpoint. This endpoint can be used by applications, which support authenticating against GitHub Enterprise, but not generic OpenID Connect.
+## OAuth 2.0 flows and grant types
 
-To use any of the GitHub Compatibility scopes, you have to use the GitHub Compatibility Endpoints.
+There are three general flows of OAuth 2.0:
 
-| Endpoint        | URL                         |
-| --------------- | --------------------------- |
-| Authorization   | `/login/oauth/authorize`    |
-| Token           | `/login/oauth/access_token` |
-| User Info       | `/user`                     |
-| User Teams Info | `/user/teams`               |
+1. Web-based application authorization (Authorization code, Implicit, Refresh token)
+2. Client credentials (Machine-to-machine)
+3. Device code
 
-To access the user's email address, a scope of `user:email` is required. To access their groups, `read:org` is required. Because these scopes are handled by a different endpoint, they are not customisable as a Scope Mapping.
+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.
 
-## Grant types
+### 1: Web-based application authorization
 
-### `authorization_code`:
+The flows and grant types used in this case are those used for a typical authorization process, with a user and an application:
 
-This grant is used to convert an authorization code to an access token (and optionally refresh token). The authorization code is retrieved through the Authorization flow, and can only be used once, and expires quickly.
+-   _Authorization code_ grant type
+-   _Implicit_ grant type (legacy)
+-   _Hybrid_ grant type
+
+#### Authorization code
+
+The authorization code is for environments with both a Client and a 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 authorise itself to the OP. Clint ID (public, identifies which app is talking to it) and client secret (the password) that the RP uses to authenticate.
+
+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 customised) 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.
 
 :::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.
 :::
 
-### `refresh_token`:
+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.
+
+#### 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/))
+:::
+
+This flow is for more modern single page-applications, or ones you download, that are all client-side (all JS, no backend logic, etc) and have no server to make tokens. Because the secret cannot be stored on the client machine, the implicit flow is required in these architectures. With the implicit flow, the flow skips the second part of the two requests seen in the authorization flow; after the initial author request, the implicit flow receives a token, and then with cryptocracy and with PKCE, it can validate that it is the correct client, and that is safe to send a token. The RP (still called that with this implicit flow) can use cryptography to validate the token.
+
+#### 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.
+
+### 2. Client credentials
+
+The client credentials flow and grant types are typically implemented for server-to-server scenarios, when code in a web application invokes a web API.
+
+For more information, see [Machine-to-machine authentication](./client_credentials.md).
+
+### 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.
+
+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.
 
 :::info
-Starting with authentik 2024.2, this grant requires the `offline_access` scope.
+Starting with authentik 2024.2, the refresh token grant type requires the `offline_access` scope.
 :::
 
-### `client_credentials`:
+## Scope mappings
 
-See [Machine-to-machine authentication](./client_credentials.md)
+Scopes can be configured using scope mappings, a type of [property mapping](../property-mappings/index.md#scope-mappings).
+
+| Endpoint             | URL                                                                  |
+| -------------------- | -------------------------------------------------------------------- |
+| Authorization        | `/application/o/authorize/`                                          |
+| Token                | `/application/o/token/`                                              |
+| User Info            | `/application/o/userinfo/`                                           |
+| Token Revoke         | `/application/o/revoke/`                                             |
+| End Session          | `/application/o/<application slug>/end-session/`                     |
+| JWKS                 | `/application/o/<application slug>/jwks/`                            |
+| OpenID Configuration | `/application/o/<application slug>/.well-known/openid-configuration` |
 
 ## Scope authorization
 
@@ -68,10 +147,7 @@ return True
 
 #### 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
--   `read:org`: Allows read-only access to `/user/teams`, listing all the user's groups as teams.
+Refer to [GitHub Compatibility](./github-compatibility.md).
 
 #### authentik
 

website/sidebars.js

@@ -194,8 +194,10 @@ export default {
                                 id: "add-secure-apps/providers/oauth2/index",
                             },
                             items: [
+                                "add-secure-apps/providers/oauth2/create-oauth2-provider",
                                 "add-secure-apps/providers/oauth2/client_credentials",
                                 "add-secure-apps/providers/oauth2/device_code",
+                                "add-secure-apps/providers/oauth2/github-compatibility",
                             ],
                         },
                         "add-secure-apps/providers/saml/index",