OpenID Connect

An introduction into integrating the Authelia OpenID Connect Provider with an OpenID Connect relying party.

Authelia supports OpenID Connect as part of an open beta. This section details implementation specifics that can be used for integrating Authelia with relying parties, as well as specific documentation for some relying parties.

See the configuration documentation for information on how to configure OpenID Connect.

Scope Definitions

openid

This is the default scope for OpenID Connect. This field is forced on every client by the configuration validation that Authelia does.

Important Note: The subject identifiers or sub Claim has been changed to a RFC4122 UUID V4 to identify the individual user as per the Subject Identifier Types section of the OpenID Connect specification. Please use the preferred_username Claim instead.

ClaimJWT TypeAuthelia AttributeDescription
issstringhostnameThe issuer name, determined by URL
jtistring(uuid)N/AA RFC4122 UUID V4 representing the JWT Identifier
ratnumberN/AThe time when the token was requested
expnumberN/AExpires
iatnumberN/AThe time when the token was issued
auth_timenumberN/AThe time the user authenticated with Authelia
substring(uuid)opaque idA RFC4122 UUID V4 linked to the user who logged in
scopestringscopesGranted scopes (space delimited)
scparray[string]scopesGranted scopes
audarray[string]N/AAudience
amrarray[string]N/AAn RFC8176 list of authentication method reference values
azpstringid (client)The authorized party
client_idstringid (client)The client id

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.

groups

This scope includes the groups the authentication backend reports the user is a member of in the Claims of the ID Token.

ClaimJWT TypeAuthelia AttributeDescription
groupsarray[string]groupsList of user’s groups discovered via authentication

email

This scope includes the email information the authentication backend reports about the user in the Claims of the ID Token.

ClaimJWT TypeAuthelia AttributeDescription
emailstringemail[0]The first email address in the list of emails
email_verifiedboolN/AIf the email is verified, assumed true for the time being
alt_emailsarray[string]email[1:]All email addresses that are not in the email JWT field

profile

This scope includes the profile information the authentication backend reports about the user in the Claims of the ID Token.

ClaimJWT TypeAuthelia AttributeDescription
preferred_usernamestringusernameThe username the user used to login with
namestringdisplay_nameThe users display name

Authentication Method References

Authelia currently supports adding the amr Claim to the ID Token utilizing the RFC8176 Authentication Method Reference values.

The values this Claim has are not strictly defined by the OpenID Connect specification. As such, some backends may expect a specification other than RFC8176 for this purpose. If you have such an application and wish for us to support it then you’re encouraged to create an issue.

Below is a list of the potential values we place in the Claim and their meaning:

ValueDescriptionFactorChannel
mfaUser used multiple factors to login (see factor column)N/AN/A
mcaUser used multiple channels to login (see channel column)N/AN/A
userUser confirmed they were present when using their hardware keyN/AN/A
pinUser confirmed they are the owner of the hardware key with a pinN/AN/A
pwdUser used a username and password to loginKnowBrowser
otpUser used TOTP to loginHaveBrowser
hwkUser used a hardware key to loginHaveBrowser
smsUser used Duo to loginHaveExternal

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.

EndpointPath
OpenID Connect Discoveryhttps://auth.example.com/.well-known/openid-configuration
OAuth 2.0 Authorization Server Metadatahttps://auth.example.com/.well-known/oauth-authorization-server

Discoverable Endpoints

These endpoints implement OpenID Connect elements.

EndpointPathDiscovery Attribute
JSON Web Key Setshttps://auth.example.com/jwks.jsonjwks_uri
Authorizationhttps://auth.example.com/api/oidc/authorizationauthorization_endpoint
Tokenhttps://auth.example.com/api/oidc/tokentoken_endpoint
Userinfohttps://auth.example.com/api/oidc/userinfouserinfo_endpoint
Introspectionhttps://auth.example.com/api/oidc/introspectionintrospection_endpoint
Revocationhttps://auth.example.com/api/oidc/revocationrevocation_endpoint