Authentification unique

Canaille implements several OAuth2 and OpenID Connect specifications that allow users to log themselves once on Canaille, and have access to other applications without logging in anew.

Installation

To use the single sign-on feature, Canaille needs to be installed with the oidc package extra. Then the feature is enabled by default, but can be disabled with the ENABLE_OIDC configuration parameter.

Discovery endpoints

The OAuth2 discovery endpoint is located at /.well-known/oauth-authorization-server and the OpenID Connect discovery endpoint is located at /.well-known/openid-configuration.

Dynamic client registration

The easiest way to register a client is to let the client register itself. You can either provide a registration token to the client by adding it to the DYNAMIC_CLIENT_REGISTRATION_TOKENS configuration parameter, or enable registration for all clients without token by enabling DYNAMIC_CLIENT_REGISTRATION_OPEN.

Manual client registration

La page d’ajout d’application cliente.

La page d’ajout d’application cliente.

Users with the right MANAGE_OIDC permission can manage OIDC clients through the web interface.

Here are some details about the fields in the client edition and registration form:

Nom

Le nom qui sera affiché sur l’interface web, notamment sur la page de consentement.

Contacts

Ce sont les adresses email des personnes responsables du client.

URI

URL d’une page web fournissant des informations à propos du client.

Note

This URL is used to determine the allowed origin for cross-origin requests (CORS) to OIDC and SCIM endpoints. This enables Single Page Applications to directly call these endpoints from the browser.

URI de redirection

URIs qui peuvent servir au flux d’authentification comprenant des redirections, tels le code d’autorisation ou le flux implicite.

URI de redirection post-déconnexion

Les URI vers lesquelles le client peut rediriger les utilisateurs après déconnexion.

Types de consentement

Types de consentement que le client peut utiliser sur le terminal de jetons.

• password allows clients to authenticate users by forwarding their password to the authorization server. This is considered an unsecured flow and is removed from the incoming OAuth 2.1 specification. Only enable this grant when the client don’t support other more secured flow.

• authorization code redirects end-users to the authorization server, optionally ask for their consent, then redirect users to the client application with an authorization code that it can exchange in a second time with an access token. This is the most common grant type.

• implicit redirects end-users to the authorization server, optionally ask for their consent, then redirect users to the client application with an access token. This grant type is less secured than authorization code, and is only intended to be used for client applications that cannot guarantee the secrecy of their credentials, such as SPA.

• hybrid is a mix of implicit and authorization code, and share the security defaults of implicit.

• refresh token asks for a token that cannot be used to access protected resources, but can be used to get a new access token without user manual intervention. This is generally useful.

• client credentials is intended to be used for server-to-server applications, when no user interaction is expected. For example this is the grant type that should be used for provisioning.

• JWT bearer allows clients to exchange a JWT signed by the authorization server against an access token.

Portée

Type d’informations que le client peut demander à propos des utilisateurs.

• openid is needed for the client to be able to access the UserInfo endpoint.

• profile gives access to users name, family names, given names, display names, photos, profile URLs, preferred languages and last update dates.

• email gives access to users email addresses.

• groups gives access to users groups.

• address gives access to users addresses.

• phone gives access to users phone numbers.

Types de réponse

Types de réponse que le client peut utiliser sur le terminal d’autorisation.

• code is used in the authorization code and can be used in the hybrid authorization flows.

• token and id_token are used in the implicit and can be used in the hybrid authorization flows.

Méthode d’authentification du point terminal des jetons

Méthode d’authentification que le client utilise sur le terminal de jeton.

• none indicate clients do not authenticate on the token endpoint. This is considered unsecured, and should only be used for implicit authorization flow.

• client_secret_basic expects clients to pass their credentials in the request headers.

• client_secret_post expects clients to pass their credentials in the POST payload of the request.

• private_key_jwt passes a JWT signed with the client private asymmetric keys in the request POST payload. This is considered very secure, more so if the client publishes its public keys on the internet using the jwks_uri attributes.

• client_secret_jwt passes a JWT signed with the client secret attribute in the request POST payload. This is considered secured, although less than private_key_jwt, but this does not require the client to publish its asymmetric keys, so it might be more easier to set-up.

Audience

Les autres applications qui pourront utiliser les jetons émis pour ce client.

Logo URI

An URL for the logo of this client.

Terms of service URI

URL to the terms of service of the client.

Policy URI

URL to the privacy policy of the client.

Software ID

Unique identifier for this client, that should be stable in time and common for all identity providers.

Software Version

The version of the client.

JSON Web Keys

The public JSON Web Keys of the client.

URI vers les JSON Web Keys

The URI that points to the public JSON Web Keys of the client.

Trusted

Whether the clients needs to display consent dialogs.

Server key management

Key generation

The canaille jwk create command can be used to generate JSON Web Keys. To install a server key, put the output of the command in the ACTIVE_JWKS configuration parameter. The OpenID Connect specification imposes to have at least one RSA key among the active keys.

Key rotation

It is considered a good practice to rotate the authorization server keys on a regular basis.

Canaille has two configuration parameters for key management: ACTIVE_JWKS and INACTIVE_JWKS. Only the keys listed in the former are used to sign tokens, but keys listed in both are used to verify tokens. The keys listed in both are displayed in the server JWKS endpoint, so clients can know that JWTs signed with inactive keys are still valid.

To rotate keys, simply pass a key from ACTIVE_JWKS to INACTIVE_JWKS and restart Canaille. After a few time, you can purge the inactive keys.