2022-06-15 07:51:47 +00:00
|
|
|
---
|
|
|
|
|
title: "OpenID Connect"
|
2022-06-28 00:25:36 +00:00
|
|
|
description: "An introduction into integrating the Authelia OpenID Connect Provider with an OpenID Connect relying party"
|
|
|
|
|
lead: "An introduction into integrating the Authelia OpenID Connect Provider with an OpenID Connect relying party."
|
2022-06-28 05:27:14 +00:00
|
|
|
date: 2022-06-15T17:51:47+10:00
|
2022-06-15 07:51:47 +00:00
|
|
|
draft: false
|
|
|
|
|
images: []
|
|
|
|
|
menu:
|
|
|
|
|
integration:
|
|
|
|
|
parent: "openid-connect"
|
|
|
|
|
weight: 610
|
|
|
|
|
toc: true
|
|
|
|
|
aliases:
|
|
|
|
|
- /docs/community/oidc-integrations.html
|
|
|
|
|
---
|
|
|
|
|
|
2023-01-25 23:59:18 +00:00
|
|
|
Authelia can act as an [OpenID Connect 1.0] Provider as part of an open beta. This section details implementation
|
|
|
|
|
specifics that can be used for integrating Authelia with an [OpenID Connect 1.0] Relying Party, as well as specific
|
|
|
|
|
documentation for some [OpenID Connect 1.0] Relying Party implementations.
|
2022-06-15 07:51:47 +00:00
|
|
|
|
|
|
|
|
See the [configuration documentation](../../configuration/identity-providers/open-id-connect.md) for information on how
|
2023-01-25 23:59:18 +00:00
|
|
|
to configure the Authelia [OpenID Connect 1.0] Provider.
|
2022-06-15 07:51:47 +00:00
|
|
|
|
|
|
|
|
## Scope Definitions
|
|
|
|
|
|
|
|
|
|
### openid
|
|
|
|
|
|
2023-01-25 23:59:18 +00:00
|
|
|
This is the default scope for [OpenID Connect 1.0]. This field is forced on every client by the configuration validation
|
2022-06-28 00:25:36 +00:00
|
|
|
that Authelia does.
|
2022-06-15 07:51:47 +00:00
|
|
|
|
2022-06-28 00:25:36 +00:00
|
|
|
*__Important Note:__ The subject identifiers or `sub` [Claim] has been changed to a [RFC4122] UUID V4 to identify the
|
2023-01-25 23:59:18 +00:00
|
|
|
individual user as per the [Subject Identifier Types] section of the [OpenID Connect 1.0] specification. Please use the
|
2022-06-28 00:25:36 +00:00
|
|
|
`preferred_username` [Claim] instead.*
|
2022-06-15 07:51:47 +00:00
|
|
|
|
2022-06-28 00:25:36 +00:00
|
|
|
| [Claim] | JWT Type | Authelia Attribute | Description |
|
2022-06-15 07:51:47 +00:00
|
|
|
|:---------:|:-------------:|:------------------:|:-----------------------------------------------------------:|
|
|
|
|
|
| iss | string | hostname | The issuer name, determined by URL |
|
|
|
|
|
| jti | string(uuid) | *N/A* | A [RFC4122] UUID V4 representing the JWT Identifier |
|
|
|
|
|
| rat | number | *N/A* | The time when the token was requested |
|
|
|
|
|
| exp | number | *N/A* | Expires |
|
|
|
|
|
| iat | number | *N/A* | The time when the token was issued |
|
|
|
|
|
| auth_time | number | *N/A* | The time the user authenticated with Authelia |
|
|
|
|
|
| sub | string(uuid) | opaque id | A [RFC4122] UUID V4 linked to the user who logged in |
|
|
|
|
|
| scope | string | scopes | Granted scopes (space delimited) |
|
|
|
|
|
| scp | array[string] | scopes | Granted scopes |
|
|
|
|
|
| aud | array[string] | *N/A* | Audience |
|
|
|
|
|
| amr | array[string] | *N/A* | An [RFC8176] list of authentication method reference values |
|
|
|
|
|
| azp | string | id (client) | The authorized party |
|
|
|
|
|
| client_id | string | id (client) | The client id |
|
|
|
|
|
|
2022-06-28 00:25:36 +00:00
|
|
|
### offline_access
|
|
|
|
|
|
|
|
|
|
This scope is a special scope designed to allow applications to obtain a [Refresh Token] which allows extended access to
|
|
|
|
|
an application on behalf of a user. A [Refresh Token] is a special [Access Token] that allows refreshing previously
|
|
|
|
|
issued token credentials, effectively it allows the relying party to obtain new tokens periodically.
|
|
|
|
|
|
|
|
|
|
Generally unless an application supports this and actively requests this scope they should not be granted this scope via
|
|
|
|
|
the client configuration.
|
|
|
|
|
|
2022-06-15 07:51:47 +00:00
|
|
|
### groups
|
|
|
|
|
|
2022-06-28 00:25:36 +00:00
|
|
|
This scope includes the groups the authentication backend reports the user is a member of in the [Claims] of the
|
|
|
|
|
[ID Token].
|
2022-06-15 07:51:47 +00:00
|
|
|
|
2022-06-28 00:25:36 +00:00
|
|
|
| [Claim] | JWT Type | Authelia Attribute | Description |
|
|
|
|
|
|:-------:|:-------------:|:------------------:|:-------------------------------------------------------------------------------------------------------:|
|
|
|
|
|
| groups | array[string] | groups | List of user's groups discovered via [authentication](../../configuration/first-factor/introduction.md) |
|
2022-06-15 07:51:47 +00:00
|
|
|
|
|
|
|
|
### email
|
|
|
|
|
|
2022-06-28 00:25:36 +00:00
|
|
|
This scope includes the email information the authentication backend reports about the user in the [Claims] of the
|
|
|
|
|
[ID Token].
|
2022-06-15 07:51:47 +00:00
|
|
|
|
|
|
|
|
| Claim | JWT Type | Authelia Attribute | Description |
|
|
|
|
|
|:--------------:|:-------------:|:------------------:|:---------------------------------------------------------:|
|
|
|
|
|
| email | string | email[0] | The first email address in the list of emails |
|
|
|
|
|
| email_verified | bool | *N/A* | If the email is verified, assumed true for the time being |
|
|
|
|
|
| alt_emails | array[string] | email[1:] | All email addresses that are not in the email JWT field |
|
|
|
|
|
|
|
|
|
|
### profile
|
|
|
|
|
|
2022-06-28 00:25:36 +00:00
|
|
|
This scope includes the profile information the authentication backend reports about the user in the [Claims] of the
|
|
|
|
|
[ID Token].
|
2022-06-15 07:51:47 +00:00
|
|
|
|
|
|
|
|
| Claim | JWT Type | Authelia Attribute | Description |
|
|
|
|
|
|:------------------:|:--------:|:------------------:|:----------------------------------------:|
|
|
|
|
|
| preferred_username | string | username | The username the user used to login with |
|
|
|
|
|
| name | string | display_name | The users display name |
|
|
|
|
|
|
|
|
|
|
## Authentication Method References
|
|
|
|
|
|
2022-06-28 00:25:36 +00:00
|
|
|
Authelia currently supports adding the `amr` [Claim] to the [ID Token] utilizing the [RFC8176] Authentication Method
|
2022-06-15 07:51:47 +00:00
|
|
|
Reference values.
|
|
|
|
|
|
2023-01-25 23:59:18 +00:00
|
|
|
The values this [Claim] has are not strictly defined by the [OpenID Connect 1.0] specification. As such, some backends may
|
2022-06-15 07:51:47 +00:00
|
|
|
expect a specification other than [RFC8176] for this purpose. If you have such an application and wish for us to support
|
2022-12-19 04:04:02 +00:00
|
|
|
it then you're encouraged to create a [feature request](https://www.authelia.com/l/fr).
|
2022-06-15 07:51:47 +00:00
|
|
|
|
2022-06-28 00:25:36 +00:00
|
|
|
Below is a list of the potential values we place in the [Claim] and their meaning:
|
2022-06-15 07:51:47 +00:00
|
|
|
|
|
|
|
|
| Value | Description | Factor | Channel |
|
|
|
|
|
|:-----:|:----------------------------------------------------------------:|:------:|:--------:|
|
|
|
|
|
| mfa | User used multiple factors to login (see factor column) | N/A | N/A |
|
|
|
|
|
| mca | User used multiple channels to login (see channel column) | N/A | N/A |
|
|
|
|
|
| user | User confirmed they were present when using their hardware key | N/A | N/A |
|
|
|
|
|
| pin | User confirmed they are the owner of the hardware key with a pin | N/A | N/A |
|
|
|
|
|
| pwd | User used a username and password to login | Know | Browser |
|
|
|
|
|
| otp | User used TOTP to login | Have | Browser |
|
|
|
|
|
| hwk | User used a hardware key to login | Have | Browser |
|
|
|
|
|
| sms | User used Duo to login | Have | External |
|
|
|
|
|
|
2022-08-26 03:26:58 +00:00
|
|
|
## User Information Signing Algorithm
|
|
|
|
|
|
|
|
|
|
The following table describes the response from the [UserInfo] endpoint depending on the
|
2022-12-07 09:43:02 +00:00
|
|
|
[userinfo_signing_algorithm](../../configuration/identity-providers/open-id-connect.md#userinfosigningalgorithm).
|
2022-08-26 03:26:58 +00:00
|
|
|
|
|
|
|
|
| Signing Algorithm | Encoding | Content Type |
|
|
|
|
|
|:-----------------:|:------------:|:-----------------------------------:|
|
|
|
|
|
| `none` | JSON | `application/json; charset="UTF-8"` |
|
|
|
|
|
| `RS256` | JWT (Signed) | `application/jwt; charset="UTF-8"` |
|
|
|
|
|
|
2022-06-15 07:51:47 +00:00
|
|
|
## Endpoint Implementations
|
|
|
|
|
|
|
|
|
|
The following section documents the endpoints we implement and their respective paths. This information can
|
|
|
|
|
traditionally be discovered by relying parties that utilize [OpenID Connect Discovery], however this information may be
|
|
|
|
|
useful for clients which do not implement this.
|
|
|
|
|
|
|
|
|
|
The endpoints can be discovered easily by visiting the Discovery and Metadata endpoints. It is recommended regardless
|
|
|
|
|
of your version of Authelia that you utilize this version as it will always produce the correct endpoint URLs. The paths
|
|
|
|
|
for the Discovery/Metadata endpoints are part of IANA's well known registration but are also documented in a table
|
|
|
|
|
below.
|
|
|
|
|
|
|
|
|
|
These tables document the endpoints we currently support and their paths in the most recent version of Authelia. The
|
|
|
|
|
paths are appended to the end of the primary URL used to access Authelia. The tables use the url
|
|
|
|
|
https://auth.example.com as an example of the Authelia root URL which is also the OpenID Connect issuer.
|
|
|
|
|
|
|
|
|
|
### Well Known Discovery Endpoints
|
|
|
|
|
|
|
|
|
|
These endpoints can be utilized to discover other endpoints and metadata about the Authelia OP.
|
|
|
|
|
|
|
|
|
|
| Endpoint | Path |
|
|
|
|
|
|:-----------------------------------------:|:---------------------------------------------------------------:|
|
|
|
|
|
| [OpenID Connect Discovery] | https://auth.example.com/.well-known/openid-configuration |
|
|
|
|
|
| [OAuth 2.0 Authorization Server Metadata] | https://auth.example.com/.well-known/oauth-authorization-server |
|
|
|
|
|
|
|
|
|
|
### Discoverable Endpoints
|
|
|
|
|
|
|
|
|
|
These endpoints implement OpenID Connect elements.
|
|
|
|
|
|
|
|
|
|
| Endpoint | Path | Discovery Attribute |
|
|
|
|
|
|:-------------------:|:-----------------------------------------------:|:----------------------:|
|
|
|
|
|
| [JSON Web Key Sets] | https://auth.example.com/jwks.json | jwks_uri |
|
|
|
|
|
| [Authorization] | https://auth.example.com/api/oidc/authorization | authorization_endpoint |
|
|
|
|
|
| [Token] | https://auth.example.com/api/oidc/token | token_endpoint |
|
2022-08-26 03:26:58 +00:00
|
|
|
| [UserInfo] | https://auth.example.com/api/oidc/userinfo | userinfo_endpoint |
|
2022-06-15 07:51:47 +00:00
|
|
|
| [Introspection] | https://auth.example.com/api/oidc/introspection | introspection_endpoint |
|
|
|
|
|
| [Revocation] | https://auth.example.com/api/oidc/revocation | revocation_endpoint |
|
|
|
|
|
|
|
|
|
|
[ID Token]: https://openid.net/specs/openid-connect-core-1_0.html#IDToken
|
2022-06-28 00:25:36 +00:00
|
|
|
[Access Token]: https://datatracker.ietf.org/doc/html/rfc6749#section-1.4
|
|
|
|
|
[Refresh Token]: https://openid.net/specs/openid-connect-core-1_0.html#RefreshTokens
|
|
|
|
|
|
|
|
|
|
[Claims]: https://openid.net/specs/openid-connect-core-1_0.html#Claims
|
|
|
|
|
[Claim]: https://openid.net/specs/openid-connect-core-1_0.html#Claims
|
2022-06-15 07:51:47 +00:00
|
|
|
|
2023-01-25 23:59:18 +00:00
|
|
|
[OpenID Connect 1.0]: https://openid.net/connect/
|
2022-06-15 07:51:47 +00:00
|
|
|
|
|
|
|
|
[OpenID Connect Discovery]: https://openid.net/specs/openid-connect-discovery-1_0.html
|
2023-02-05 07:11:30 +00:00
|
|
|
[OAuth 2.0 Authorization Server Metadata]: https://datatracker.ietf.org/doc/html/rfc8414
|
2022-06-15 07:51:47 +00:00
|
|
|
|
2023-02-02 01:30:06 +00:00
|
|
|
[JSON Web Key Sets]: https://datatracker.ietf.org/doc/html/rfc7517#section-5
|
2022-06-15 07:51:47 +00:00
|
|
|
|
|
|
|
|
[Authorization]: https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint
|
|
|
|
|
[Token]: https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint
|
2022-08-26 03:26:58 +00:00
|
|
|
[UserInfo]: https://openid.net/specs/openid-connect-core-1_0.html#UserInfo
|
2023-02-05 07:11:30 +00:00
|
|
|
[Introspection]: https://datatracker.ietf.org/doc/html/rfc7662
|
|
|
|
|
[Revocation]: https://datatracker.ietf.org/doc/html/rfc7009
|
2022-06-15 07:51:47 +00:00
|
|
|
|
2023-02-05 07:11:30 +00:00
|
|
|
[RFC8176]: https://datatracker.ietf.org/doc/html/rfc8176
|
|
|
|
|
[RFC4122]: https://datatracker.ietf.org/doc/html/rfc4122
|
2022-06-15 07:51:47 +00:00
|
|
|
[Subject Identifier Types]: https://openid.net/specs/openid-connect-core-1_0.html#SubjectIDTypes
|
