RPJosh
/
authelia
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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 2021-07-14 03:36:07 +02:00 committed by GitHub
parent 3537cce660
commit 9d7cfb8455
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 147 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
docs/community/oidc-integrations.md 100644
View File

@ -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` |

98
docs/configuration/identity-providers/oidc.md
View File

@ -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,16 +162,16 @@ 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 }
@ -181,6 +185,7 @@ 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 }
@ -194,6 +199,7 @@ 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 }
@ -206,6 +212,7 @@ 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 }
@ -215,11 +222,12 @@ 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 }
@ -232,6 +240,7 @@ 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 }
@ -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,10 +320,12 @@ 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 }
@ -316,9 +335,12 @@ 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

37
docs/configuration/secrets.md
View File

@ -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

5
docs/faq.md
View File

@ -10,3 +10,8 @@ nav_order: 8
This question is solved
[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`).