Revert "website: latest migration to new structure" (#11634)
Revert "website: latest migration to new structure (#11522)"
This reverts commit 9a89a5f94b.
This commit is contained in:
Tana M Berry
64
website/docs/providers/oauth2/client_credentials.md
Normal file
64
website/docs/providers/oauth2/client_credentials.md
Normal file
@ -0,0 +1,64 @@
|
||||
# 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.
|
||||
|
||||
Note that authentik does treat a grant type of `password` the same as `client_credentials` to support applications which rely on a password grant.
|
||||
|
||||
### Static authentication
|
||||
|
||||
Hence identification is based on service-accounts, and authentication is based on App-password tokens. These objects can be created in a single step using the _Create Service account_ function.
|
||||
|
||||
An example request can look like this:
|
||||
|
||||
```
|
||||
POST /application/o/token/ HTTP/1.1
|
||||
Host: authentik.company
|
||||
Content-Type: application/x-www-form-urlencoded
|
||||
|
||||
grant_type=client_credentials&
|
||||
client_id=application_client_id&
|
||||
username=my-service-account&
|
||||
password=my-token&
|
||||
scope=profile
|
||||
```
|
||||
|
||||
This will return a JSON response with an `access_token`, which is a signed JWT token. This token can be sent along requests to other hosts, which can then validate the JWT based on the signing key configured in authentik.
|
||||
|
||||
Starting with authentik 2024.4, it is also possible to encode the username and token of the user to authenticate with, separated with a colon, into a base64 string and pass it as `client_secret` value.
|
||||
|
||||
In addition to that, with authentik 2024.4 it is also possible to pass the configured `client_secret` value, which will automatically generate a service account user for which the JWT token will be issued.
|
||||
|
||||
### JWT-authentication
|
||||
|
||||
Starting with authentik 2022.4, you can authenticate and get a token using an existing JWT.
|
||||
|
||||
(For readability we will refer to the JWT issued by the external issuer/platform as input JWT, and the resulting JWT from authentik as the output JWT)
|
||||
|
||||
To configure this, the certificate used to sign the input JWT must be created in authentik. The certificate is enough, a private key is not required. Afterwards, configure the certificate in the OAuth2 provider settings under _Verification certificates_.
|
||||
|
||||
:::info
|
||||
Starting with authentik 2022.6, you can define a JWKS URL/raw JWKS data in OAuth Sources, and use those to verify the key instead of having to manually create a certificate in authentik for them. This method is still supported but will be removed in a later version.
|
||||
:::
|
||||
|
||||
With this configure, any JWT issued by the configured certificates can be used to authenticate:
|
||||
|
||||
```
|
||||
POST /application/o/token/ HTTP/1.1
|
||||
Host: authentik.company
|
||||
Content-Type: application/x-www-form-urlencoded
|
||||
|
||||
grant_type=client_credentials&
|
||||
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&
|
||||
client_assertion=$inputJWT&
|
||||
client_id=application_client_id
|
||||
```
|
||||
|
||||
Alternatively, you can set the `client_secret` parameter to the `$inputJWT`, for applications which can set the password from a file but not other parameters.
|
||||
|
||||
Input JWTs are checked to be signed by any of the selected _Verification certificates_, and their `exp` attribute must not be now or in the past.
|
||||
|
||||
To do additional checks, you can use _[Expression policies](../../policies/expression)_:
|
||||
|
||||
```python
|
||||
return request.context["oauth_jwt"]["iss"] == "https://my.issuer"
|
||||
```
|
||||
51
website/docs/providers/oauth2/device_code.md
Normal file
51
website/docs/providers/oauth2/device_code.md
Normal file
@ -0,0 +1,51 @@
|
||||
# Device code flow
|
||||
|
||||
(Also known as device flow and [RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628))
|
||||
|
||||
This type of authentication flow is useful for devices with limited input abilities and/or devices without browsers.
|
||||
|
||||
### Requirements
|
||||
|
||||
This device flow is only possible if the active brand has a device code flow setup. This device code flow is run _after_ the user logs in, and before the user authenticates.
|
||||
|
||||
authentik doesn't ship with a default flow for this usecase, so it is recommended to create a new flow for this usecase with the designation of _Stage configuration_
|
||||
|
||||
### Device-side
|
||||
|
||||
The flow is initiated by sending a POST request to the device authorization endpoint, `/application/o/device/` with the following contents:
|
||||
|
||||
```
|
||||
POST /application/o/device/ HTTP/1.1
|
||||
Host: authentik.company
|
||||
Content-Type: application/x-www-form-urlencoded
|
||||
|
||||
client_id=application_client_id&
|
||||
scopes=openid email my-other-scope
|
||||
```
|
||||
|
||||
The response contains the following fields:
|
||||
|
||||
- `device_code`: Device code, which is the code kept on the device
|
||||
- `verification_uri`: The URL to be shown to the enduser to input the code
|
||||
- `verification_uri_complete`: The same URL as above except the code will be prefilled
|
||||
- `user_code`: The raw code for the enduser to input
|
||||
- `expires_in`: The total seconds after which this token will expire
|
||||
- `interval`: The interval in seconds for how often the device should check the token status
|
||||
|
||||
---
|
||||
|
||||
With this response, the device can start checking the status of the token by sending requests to the token endpoint like this:
|
||||
|
||||
```
|
||||
POST /application/o/token/ HTTP/1.1
|
||||
Host: authentik.company
|
||||
Content-Type: application/x-www-form-urlencoded
|
||||
|
||||
grant_type=urn:ietf:params:oauth:grant-type:device_code&
|
||||
client_id=application_client_id&
|
||||
device_code=device_code_from_above
|
||||
```
|
||||
|
||||
If the user has not opened the link above yet, or has not finished the authentication and authorization yet, the response will contain an `error` element set to `authorization_pending`. The device should re-send the request in the interval set above.
|
||||
|
||||
If the user _has_ finished the authentication and authorization, the response will be similar to any other generic OAuth2 Token request, containing `access_token` and `id_token`.
|
||||
84
website/docs/providers/oauth2/index.md
Normal file
84
website/docs/providers/oauth2/index.md
Normal file
@ -0,0 +1,84 @@
|
||||
---
|
||||
title: OAuth2 Provider
|
||||
---
|
||||
|
||||
This provider supports both generic OAuth2 as well as OpenID Connect
|
||||
|
||||
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` |
|
||||
|
||||
## GitHub Compatibility
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## Grant types
|
||||
|
||||
### `authorization_code`:
|
||||
|
||||
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.
|
||||
|
||||
:::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`:
|
||||
|
||||
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.
|
||||
:::
|
||||
|
||||
### `client_credentials`:
|
||||
|
||||
See [Machine-to-machine authentication](./client_credentials)
|
||||
|
||||
## Scope authorization
|
||||
|
||||
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.
|
||||
if "my-admin-scope" in request.context["oauth_scopes"]:
|
||||
return ak_is_group_member(request.user, name="my-admin-group")
|
||||
return True
|
||||
```
|
||||
|
||||
## Special scopes
|
||||
|
||||
#### 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.
|
||||
|
||||
#### authentik
|
||||
|
||||
- `goauthentik.io/api`: This scope grants the refresh token access to the authentik API on behalf of the user
|
||||
|
||||
## Default scopes <span class="badge badge--version">authentik 2022.7+</span>
|
||||
|
||||
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.
|
||||
|
||||
This does _not_ apply to special scopes, as those are not configurable in the provider.
|
||||
Reference in New Issue
Block a user