docs: update and enhance oidc documentation (#2142)
Update and adjust OIDC documentation. This also adds information for users about RP's that have been tested. Co-authored-by: Georg Lauterbach <44545919+aendeavor@users.noreply.github.com> Co-authored-by: Clément Michaud <clement.michaud34@gmail.com> Co-authored-by: Amir Zarrinkafsh <nightah@me.com> Co-authored-by: James Elliott <james-d-elliott@users.noreply.github.com>pull/2185/head
Georg Lauterbach
GitHub
parent
3537cce660
commit
9d7cfb8455
|
|
@ -0,0 +1,29 @@
|
|||
---
|
||||
layout: default
|
||||
title: Community-Tested OIDC Integrations
|
||||
parent: Community
|
||||
nav_order: 4
|
||||
---
|
||||
|
||||
# OIDC Integratins
|
||||
|
||||
**Note** This is community-based content for which the core-maintainers cannot guarantee correctness. The parameters may change over time. If a parameter does not work as documented, please submit a PR to update the list.
|
||||
|
||||
## Currently Tested Applications
|
||||
|
||||
- GitLab (>= 13.0.0)
|
||||
- Grafana (8.0.5)
|
||||
- MinIO (problems with the `state` option which is not supplied by MinIO, see [minio/minio#11398])
|
||||
|
||||
[minio/minio#11398]: https://github.com/minio/minio/issues/11398
|
||||
|
||||
## Known Callback URLs
|
||||
|
||||
If you do not find the application in the list below, you will need to search for yourself - and maybe come back to open a PR to add your application to this list so others won't have to search for them.
|
||||
|
||||
`<DOMAIN>` needs to be substituted with the full URL on which the application runs on. If GitLab, as an example, was reachable under `https://gitlab.example.com`, `<DOMAIN>` would be exactly the same.
|
||||
|
||||
| Application | Version | Callback URL |
|
||||
| :---------: | :------------------: | :------------------------------------------------------: |
|
||||
| GitLab | `14.0.1` | `<DOMAIN>/users/auth/openid_connect/callback` |
|
||||
| MinIO | `RELEASE.2021-06-17` | `<DOMAIN>/minio/login/openid` |
|
||||
|
|
@ -8,7 +8,7 @@ nav_order: 2
|
|||
|
||||
# OpenID Connect
|
||||
|
||||
**Authelia** currently supports the [OpenID Connect] OP role as a [beta](#beta) feature. The OP role is the
|
||||
**Authelia** currently supports the [OpenID Connect] OP role as a [**beta**](#beta) feature. The OP role is the
|
||||
[OpenID Connect] Provider role, not the Relaying Party or RP role. This means other applications that implement the
|
||||
[OpenID Connect] RP role can use Authelia as an authentication and authorization backend similar to how you may use
|
||||
social media or development platforms for login.
|
||||
|
|
@ -16,10 +16,10 @@ social media or development platforms for login.
|
|||
The Relaying Party role is the role which allows an application to use GitHub, Google, or other [OpenID Connect]
|
||||
providers for authentication and authorization. We do not intend to support this functionality at this moment in time.
|
||||
|
||||
## Beta
|
||||
## Roadmap
|
||||
|
||||
We have decided to implement [OpenID Connect] as a beta feature, it's suggested you only utilize it for testing and
|
||||
providing feedback, and should take caution in relying on it in production. [OpenID Connect] and it's related endpoints
|
||||
providing feedback, and should take caution in relying on it in production as of now. [OpenID Connect] and it's related endpoints
|
||||
are not enabled by default unless you specifically configure the [OpenID Connect] section.
|
||||
|
||||
The beta will be broken up into stages. Each stage will bring additional features. The following table is a *rough* plan
|
||||
|
|
@ -93,12 +93,14 @@ for which stage will have each feature, and may evolve over time:
|
|||
</tbody>
|
||||
</table>
|
||||
|
||||
*<sup>1</sup> this stage has not been implemented as of yet*
|
||||
¹ _This stage has not been implemented as of yet_.
|
||||
|
||||
*<sup>2</sup> this individual feature has not been implemented as of yet*
|
||||
² _This individual feature has not been implemented as of yet_.
|
||||
|
||||
## Configuration
|
||||
|
||||
The following snippet provides a sample-configuration for the OIDC identity provider explaining each field in detail.
|
||||
|
||||
```yaml
|
||||
identity_providers:
|
||||
oidc:
|
||||
|
|
@ -138,6 +140,7 @@ identity_providers:
|
|||
## Options
|
||||
|
||||
### hmac_secret
|
||||
|
||||
<div markdown="1">
|
||||
type: string
|
||||
{: .label .label-config .label-purple }
|
||||
|
|
@ -145,12 +148,13 @@ required: yes
|
|||
{: .label .label-config .label-red }
|
||||
</div>
|
||||
|
||||
The HMAC secret used to sign the [OpenID Connect] JWT's. The provided string is hashed to a SHA256 byte string for
|
||||
the purpose of meeting the required format.
|
||||
The HMAC secret used to sign the [OpenID Connect] JWT's. The provided string is hashed to a SHA256
|
||||
byte string for the purpose of meeting the required format. You must [generate this option yourself](#generating-a-random-secret).
|
||||
|
||||
Can also be defined using a [secret](../secrets.md) which is the recommended for containerized deployments.
|
||||
Should be defined using a [secret](../secrets.md) which is the recommended for containerized deployments.
|
||||
|
||||
### issuer_private_key
|
||||
|
||||
<div markdown="1">
|
||||
type: string
|
||||
{: .label .label-config .label-purple }
|
||||
|
|
@ -158,19 +162,19 @@ required: yes
|
|||
{: .label .label-config .label-red }
|
||||
</div>
|
||||
|
||||
The private key in DER base64 encoded PEM format used to encrypt the [OpenID Connect] JWT's. This can easily be
|
||||
generated using the Authelia binary using the following syntax:
|
||||
The private key in DER base64 encoded PEM format used to encrypt the [OpenID Connect] JWT's.[¹](../../faq.md#why_only_use_a_private_issue_key_with_oidc)
|
||||
You must [generate this option yourself](#generating-a-random-secret). To create this option, use
|
||||
`docker run -u "$(id -u):$(id -g)" -v "$(pwd)":/keys authelia/authelia:latest authelia rsa generate --dir /keys`
|
||||
to generate both the private and public key in the current directory. You can then paste the
|
||||
private key into your configuration.
|
||||
|
||||
```console
|
||||
authelia rsa generate --dir /config
|
||||
```
|
||||
|
||||
Can also be defined using a [secret](../secrets.md) which is the recommended for containerized deployments.
|
||||
Should be defined using a [secret](../secrets.md) which is the recommended for containerized deployments.
|
||||
|
||||
### access_token_lifespan
|
||||
|
||||
<div markdown="1">
|
||||
type: duration
|
||||
{: .label .label-config .label-purple }
|
||||
{: .label .label-config .label-purple }
|
||||
default: 1h
|
||||
{: .label .label-config .label-blue }
|
||||
required: no
|
||||
|
|
@ -181,9 +185,10 @@ The maximum lifetime of an access token. It's generally recommended keeping this
|
|||
For more information read these docs about [token lifespan].
|
||||
|
||||
### authorize_code_lifespan
|
||||
|
||||
<div markdown="1">
|
||||
type: duration
|
||||
{: .label .label-config .label-purple }
|
||||
{: .label .label-config .label-purple }
|
||||
default: 1m
|
||||
{: .label .label-config .label-blue }
|
||||
required: no
|
||||
|
|
@ -194,9 +199,10 @@ The maximum lifetime of an authorize code. This can be rather short, as the auth
|
|||
obtain the other token types. For more information read these docs about [token lifespan].
|
||||
|
||||
### id_token_lifespan
|
||||
|
||||
<div markdown="1">
|
||||
type: duration
|
||||
{: .label .label-config .label-purple }
|
||||
{: .label .label-config .label-purple }
|
||||
default: 1h
|
||||
{: .label .label-config .label-blue }
|
||||
required: no
|
||||
|
|
@ -206,23 +212,25 @@ required: no
|
|||
The maximum lifetime of an ID token. For more information read these docs about [token lifespan].
|
||||
|
||||
### refresh_token_lifespan
|
||||
|
||||
<div markdown="1">
|
||||
type: string
|
||||
{: .label .label-config .label-purple }
|
||||
{: .label .label-config .label-purple }
|
||||
default: 30d
|
||||
{: .label .label-config .label-blue }
|
||||
required: no
|
||||
{: .label .label-config .label-green }
|
||||
</div>
|
||||
|
||||
The maximum lifetime of a refresh token. This should typically be slightly more the other token lifespans. This is
|
||||
because the refresh token can be used to obtain new refresh tokens as well as access tokens or id tokens with an
|
||||
The maximum lifetime of a refresh token. The
|
||||
refresh token can be used to obtain new refresh tokens as well as access tokens or id tokens with an
|
||||
up-to-date expiration. For more information read these docs about [token lifespan].
|
||||
|
||||
### enable_client_debug_messages
|
||||
|
||||
<div markdown="1">
|
||||
type: boolean
|
||||
{: .label .label-config .label-purple }
|
||||
{: .label .label-config .label-purple }
|
||||
default: false
|
||||
{: .label .label-config .label-blue }
|
||||
required: no
|
||||
|
|
@ -232,9 +240,10 @@ required: no
|
|||
Allows additional debug messages to be sent to the clients.
|
||||
|
||||
### minimum_parameter_entropy
|
||||
|
||||
<div markdown="1">
|
||||
type: integer
|
||||
{: .label .label-config .label-purple }
|
||||
{: .label .label-config .label-purple }
|
||||
default: 8
|
||||
{: .label .label-config .label-blue }
|
||||
required: no
|
||||
|
|
@ -243,15 +252,16 @@ required: no
|
|||
|
||||
This controls the minimum length of the `nonce` and `state` parameters.
|
||||
|
||||
***Security Notice:*** Changing this value is generally discouraged, reducing it from the default can theoretically make
|
||||
certain scenarios less secure. It highly encouraged that if your OpenID Connect RP does not send these parameters or
|
||||
sends parameters with a lower length than the default that they implement a change rather than changing this value.
|
||||
***Security Notice:*** Changing this value is generally discouraged, reducing it from the default can theoretically
|
||||
make certain scenarios less secure. It is highly encouraged that if your OpenID Connect RP does not send these parameters
|
||||
or sends parameters with a lower length than the default that they implement a change rather than changing this value.
|
||||
|
||||
### clients
|
||||
|
||||
A list of clients to configure. The options for each client are described below.
|
||||
|
||||
#### id
|
||||
|
||||
<div markdown="1">
|
||||
type: string
|
||||
{: .label .label-config .label-purple }
|
||||
|
|
@ -259,9 +269,11 @@ required: yes
|
|||
{: .label .label-config .label-red }
|
||||
</div>
|
||||
|
||||
The Client ID for this client. Must be configured in the application consuming this client.
|
||||
The Client ID for this client. It must exactly match the Client ID configured in the application
|
||||
consuming this client.
|
||||
|
||||
#### description
|
||||
|
||||
<div markdown="1">
|
||||
type: string
|
||||
{: .label .label-config .label-purple }
|
||||
|
|
@ -274,6 +286,7 @@ required: no
|
|||
A friendly description for this client shown in the UI. This defaults to the same as the ID.
|
||||
|
||||
#### secret
|
||||
|
||||
<div markdown="1">
|
||||
type: string
|
||||
{: .label .label-config .label-purple }
|
||||
|
|
@ -281,9 +294,12 @@ required: yes
|
|||
{: .label .label-config .label-red }
|
||||
</div>
|
||||
|
||||
The shared secret between Authelia and the application consuming this client. Currently this is stored in plain text.
|
||||
The shared secret between Authelia and the application consuming this client. This secret must
|
||||
match the secret configured in the application. Currently this is stored in plain text.
|
||||
You must [generate this option yourself](#generating-a-random-secret).
|
||||
|
||||
#### authorization_policy
|
||||
|
||||
<div markdown="1">
|
||||
type: string
|
||||
{: .label .label-config .label-purple }
|
||||
|
|
@ -293,9 +309,10 @@ required: no
|
|||
{: .label .label-config .label-green }
|
||||
</div>
|
||||
|
||||
The authorization policy for this client. Either `one_factor` or `two_factor`.
|
||||
The authorization policy for this client: either `one_factor` or `two_factor`.
|
||||
|
||||
#### redirect_uris
|
||||
|
||||
<div markdown="1">
|
||||
type: list(string)
|
||||
{: .label .label-config .label-purple }
|
||||
|
|
@ -303,22 +320,27 @@ required: yes
|
|||
{: .label .label-config .label-red }
|
||||
</div>
|
||||
|
||||
A list of valid callback URL's this client will redirect to. All other callbacks will be considered unsafe. The URL's
|
||||
are case-sensitive.
|
||||
A list of valid callback URL´s this client will redirect to. All other callbacks will be considered
|
||||
unsafe. The URL's are case-sensitive and they differ from application to application - the community has
|
||||
provided [a list of URL´s for common applications](../../community/oidc-integrations.md).
|
||||
|
||||
#### scopes
|
||||
|
||||
<div markdown="1">
|
||||
type: list(string)
|
||||
{: .label .label-config .label-purple }
|
||||
{: .label .label-config .label-purple }
|
||||
default: openid, groups, profile, email
|
||||
{: .label .label-config .label-blue }
|
||||
required: no
|
||||
{: .label .label-config .label-green }
|
||||
</div>
|
||||
|
||||
A list of scopes to allow this client to consume. See [scope definitions](#scope-definitions) for more information.
|
||||
A list of scopes to allow this client to consume. See [scope definitions](#scope-definitions) for more
|
||||
information. The documentation for the application you want to use with Authelia will most-likely provide
|
||||
you with the scopes to allow.
|
||||
|
||||
#### grant_types
|
||||
|
||||
<div markdown="1">
|
||||
type: list(string)
|
||||
{: .label .label-config .label-purple }
|
||||
|
|
@ -328,11 +350,12 @@ required: no
|
|||
{: .label .label-config .label-green }
|
||||
</div>
|
||||
|
||||
A list of grant types this client can return. It is recommended that this isn't configured at this time unless you know
|
||||
what you're doing. Valid options are: `implicit`, `refresh_token`, `authorization_code`, `password`,
|
||||
A list of grant types this client can return. _It is recommended that this isn't configured at this time unless you
|
||||
know what you're doing_. Valid options are: `implicit`, `refresh_token`, `authorization_code`, `password`,
|
||||
`client_credentials`.
|
||||
|
||||
#### response_types
|
||||
|
||||
<div markdown="1">
|
||||
type: list(string)
|
||||
{: .label .label-config .label-purple }
|
||||
|
|
@ -342,11 +365,12 @@ required: no
|
|||
{: .label .label-config .label-green }
|
||||
</div>
|
||||
|
||||
A list of response types this client can return. It is recommended that this isn't configured at this time unless you
|
||||
know what you're doing. Valid options are: `code`, `code id_token`, `id_token`, `token id_token`, `token`,
|
||||
A list of response types this client can return. _It is recommended that this isn't configured at this time unless you
|
||||
know what you're doing_. Valid options are: `code`, `code id_token`, `id_token`, `token id_token`, `token`,
|
||||
`token id_token code`.
|
||||
|
||||
#### response_modes
|
||||
|
||||
<div markdown="1">
|
||||
type: list(string)
|
||||
{: .label .label-config .label-purple }
|
||||
|
|
@ -360,6 +384,7 @@ A list of response modes this client can return. It is recommended that this isn
|
|||
know what you're doing. Potential values are `form_post`, `query`, and `fragment`.
|
||||
|
||||
#### userinfo_signing_algorithm
|
||||
|
||||
<div markdown="1">
|
||||
type: string
|
||||
{: .label .label-config .label-purple }
|
||||
|
|
@ -371,6 +396,18 @@ required: no
|
|||
|
||||
The algorithm used to sign the userinfo endpoint responses. This can either be `none` or `RS256`.
|
||||
|
||||
## Generating a random secret
|
||||
|
||||
If you must provide a random secret in configuration, you can generate a random string of sufficient length. The command
|
||||
|
||||
```sh
|
||||
LENGTH=64
|
||||
tr -cd '[:alnum:]' < /dev/urandom | fold -w "${LENGTH}" | head -n 1 | tr -d '\n' ; echo
|
||||
```
|
||||
|
||||
prints such a string with a length in characters of `${LENGTH}` on `stdout`. The string will only contain alphanumeric
|
||||
characters. For Kubernetes, see [this section too](../secrets.md#Kubernetes).
|
||||
|
||||
## Scope Definitions
|
||||
|
||||
### openid
|
||||
|
|
@ -435,6 +472,7 @@ Authelia via https://auth.example.com, the discovery URL is https://auth.example
|
|||
|Revoke |api/oidc/revoke |
|
||||
|Userinfo |api/oidc/userinfo |
|
||||
|
||||
[//]: # (Links)
|
||||
|
||||
[OpenID Connect]: https://openid.net/connect/
|
||||
[token lifespan]: https://docs.apigee.com/api-platform/antipatterns/oauth-long-expiration
|
||||
[token lifespan]: https://docs.apigee.com/api-platform/antipatterns/oauth-long-expiration
|
||||
|
|
|
|||
|
|
@ -162,11 +162,46 @@ services:
|
|||
- TZ=Australia/Melbourne
|
||||
```
|
||||
|
||||
|
||||
## Kubernetes
|
||||
|
||||
Secrets can be mounted as files using the following sample manifests.
|
||||
|
||||
To create a secret, the following manifest can be used
|
||||
|
||||
```yaml
|
||||
---
|
||||
kind: Secret
|
||||
apiVersion: v1
|
||||
|
||||
metadata:
|
||||
name: a-nice-name
|
||||
namespace: your-authelia-namespace
|
||||
|
||||
data:
|
||||
duo_key: >-
|
||||
UXE1WmM4S0pldnl6eHRwQ3psTGpDbFplOXFueUVyWEZhYjE0Z01IRHN0RT0K
|
||||
|
||||
jwt_secret: >-
|
||||
anotherBase64EncodedSecret
|
||||
|
||||
...
|
||||
```
|
||||
|
||||
where `UXE1WmM4S0pldnl6eHRwQ3psTGpDbFplOXFueUVyWEZhYjE0Z01IRHN0RT0K` is Base64 encoded for
|
||||
`Qq5Zc8KJevyzxtpCzlLjClZe9qnyErXFab14gMHDstE`, the actual content of the secret. You can generate these contents with
|
||||
|
||||
```sh
|
||||
LENGTH=64
|
||||
tr -cd '[:alnum:]' < /dev/urandom \
|
||||
| fold -w "${LENGTH}" \
|
||||
| head -n 1 \
|
||||
| tr -d '\n' \
|
||||
| tee actualSecretContent.txt \
|
||||
| base64 --wrap 0 \
|
||||
; echo
|
||||
```
|
||||
|
||||
which writes the secret's content to the `actualSecretContent.txt` file and print the Base64 encoded version on `stdout`. `${LENGTH}` is the length in characters of the secret content generated by this pipe. If you don't want the contents to be written to `actualSecretContent.txt`, just delete the line with the `tee` command.
|
||||
|
||||
### Kustomization
|
||||
|
||||
|
|
|
|||
|
|
@ -9,4 +9,9 @@ nav_order: 8
|
|||
## How can the backend be aware of the authenticated users?
|
||||
|
||||
This question is solved
|
||||
[here](https://www.authelia.com/docs/deployment/supported-proxies/#how-can-the-backend-be-aware-of-the-authenticated-users).
|
||||
[here](https://www.authelia.com/docs/deployment/supported-proxies/#how-can-the-backend-be-aware-of-the-authenticated-users).
|
||||
|
||||
## Why only use a private issuer key and no public key with OIDC?
|
||||
|
||||
The reason for using only the private key here is that one is able to calculate the public key easily from the private
|
||||
key (`openssl rsa -in rsa.key -pubout > rsa.pem`).
|
||||
|
|
|
|||
Loading…
Reference in New Issue