OpenID Connect 1.0 Claims

Claims#

The OAuth 2.0 and OpenID Connect 1.0 effectively names the individual content of a token as a Claim. Each Claim can either be granted individually via:

1. The requested and granted Scope which generally makes the associated Claim values available at the UserInfo endpoint, not within the ID Token.
2. The Claims Parameter which can request the authorization server explicitly include a Claim in the ID Token and/or UserInfo endpoint.

Authelia supports several claims related features:

1. The availability of the Standard Claims using the appropriate scopes:
   • These claims come from the standard attributes available in the authentication backends, usually with the attribute of the same name.
2. The availability of creating your own custom claims and custom scopes.
3. The ability to create Custom Attributes to bolster the custom claims functionality.
4. The ability to request individual claims by clients with the Claims Parameter assuming the client is allowed to request the specified claim.

Because Authelia supports the Claims Parameter the ID Token only returns claims in a way that is privacy and security focused, resulting in a minimal ID Token which solely proves authorization occurred. This allows various flows which require the relying party to share the ID Token with another party to prove they have been authorized, and relies on the Access Token which should be kept completely private to request the additional granted claims from the UserInfo endpoint.

The Scope Definitions indicate the default locations for a specific claim depending on the granted Scope when the Claims Parameter is not used and the default behaviour is not overridden by the registered client configuration.

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 1.0 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 a feature request.

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

Custom Claims#

Authelia supports methods to define your own claims. These can either come from Standard Attributes or Custom Attributes. These claims are delivered to relying parties either via an ID Token minted by Authelia or via the User Information endpoint when requested with the Access Token. The claims are made available to clients by assigning them to a custom scope, and then allowing that client to request that scope. Clients which are allowed to request a claim by requested scope, are also able to request that same claim via the claims parameter.

In the example below we configure 6 elements.

1. The authentication backend is configured to provide the extra_example attribute.
2. The definitions section is configured to provide the attribute_name attribute.
3. The claims policy named custom_claims_policy is configured to provide two claims named claim_name and extra_claim_name which comes from the attributes named attribute_name and extra_example respectively.
4. The claims claim_name and extra_claim_name are then made available via the scope named scope_name.
5. The claims policy custom_claims_policy is assigned to the client with id client_example_id.
6. The custom scope named scope_name is permitted to be requested by the client with id client_example_id via the registered scopes which makes the claims available to the client via the scope or claism parameters.

authentication_backend:
  ldap:
    attributes:
      extra:
        ## Gives Authelia access to a user attribute named 'extra_example'.
        extra_example:
          multi_valued: false
          value_type: 'string'
definitions:
  user_attributes:
    ## Gives Authelia access to a user attribute named 'attribute_name'.
    attribute_name:
      expression: '"attibute_name_users" in groups'
identity_providers:
  oidc:
    claims_policies:
      custom_claims_policy:
        custom_claims:
          ## Gives the 'custom_claims_policy' claim policy access to the 'claim_name' and 'extra_claim_name' claims.
          claim_name:
            attribute: 'attribute_name'
          extra_claim_name:
            attribute: 'extra_example'
    scopes:
      ## Gives the arbitrary scope 'scope_name` access to the 'claim_name' and 'extra_claim_name' claims.
      scope_name:
        claims:
          - 'claim_name'
          - 'extra_claim_name'
    clients:
      - client_id: 'client_example_id'
        ## Assigns the 'custom_claims_policy' to this client.
        claims_policy: 'custom_claims_policy'
        ## Allows this client to request the scope with the extra claims or the individual claims themselves.
        scopes:
          - 'scope_name'

Restore Functionality Prior to Claims Parameter#

The introduction of the claims parameter has removed most claims from the ID Token. This may not work for some clients which do not make requests to the user information endpoint which contains all of these claims, and they may not support the claims parameter.

The following example is a claims policy which restores that behaviour for those clients. Users may choose to expand on this on their own as they desire. This example also shows how to apply this policy to a client using the claims_policy option.

We strongly recommend implementers use the standard process for obtaining the extra claims not generally intended to be included in the ID Token by using the Access Token to obtain them from the UserInfo Endpoint. This process is considered significantly more stable and forms the basis for the future guarantee. This option only exists as a break-glass measure and is only offered on a best-effort basis.

identity_providers:
  oidc:
    claims_policies:
      default:
        id_token: ['groups', 'email', 'email_verified', 'alt_emails', 'preferred_username', 'name']
    clients:
      - client_id: 'client_example_id'
        claims_policy: 'default'

Scope Definitions#

The following scope definitions describe each scope supported and the associated effects including the individual claims returned by granting this scope. By default, we do not issue any claims which reveal the users identity which allows administrators semi-granular control over which claims the client is entitled to.

openid#

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

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.

As per OpenID Connect 1.0 Section 11 Offline Access can only be granted during the Authorization Code Flow or a Hybrid Flow. The Refresh Token will only ever be returned at the Token Endpoint when the client is exchanging their OAuth 2.0 Authorization Code.

Generally unless an application supports this and actively requests this scope they should not be granted this scope via the client configuration.

It is also important to note that we treat a Refresh Token as single use and reissue a new Refresh Token during the refresh flow.

profile#

This scope allows the client to access the profile information the authentication backend reports about the user.

email#

This scope allows the client to access the email information the authentication backend reports about the user.

address#

This scope allows the client to access the address information the authentication backend reports about the user. See the Address Claim definition for information on the format of this claim.

The following table indicates the various sub-claims within the address claim.

phone#

This scope allows the client to access the address information the authentication backend reports about the user.

groups#

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

Special Scopes#

The following scopes represent special permissions granted to a specific token.

authelia.bearer.authz#

This scope allows the granted access token to be utilized with the bearer authorization scheme on endpoints protected via Authelia.

The specifics about this scope are discussed in the OAuth 2.0 Bearer Token Usage for Authorization Endpoints guide.