2020-05-14 23:29:41 +02:00
OpenID Connect Provider
=======================
Presentation
------------
2020-05-18 09:56:39 +02:00
.. note ::
2020-05-14 23:29:41 +02:00
OpenID Connect is a protocol based on REST, OAuth 2.0 and JOSE
stacks. It is described here: http://openid.net/connect/.
2022-02-19 13:09:01 +01:00
LL::NG can act as an OpenID Connect Provider (OP). It will reply to
2021-04-02 23:57:30 +02:00
OpenID Connect requests to give user identity (through ID Token) and
2022-02-18 19:09:41 +01:00
information (through UserInfo endpoint).
2020-05-14 23:29:41 +02:00
2022-02-18 19:09:41 +01:00
As an OP, LL::NG supports many OpenID Connect features:
2020-05-14 23:29:41 +02:00
- Authorization Code, Implicit and Hybrid flows
- Publication of JSON metadata and JWKS data (Discovery)
- `` prompt `` , `` display `` , `` ui_locales `` , `` max_age `` parameters
- Extra claims definition
- Authentication context Class References (ACR)
- Nonce
- Dynamic registration
- Access Token Hash generation
- ID Token signature (HS256/HS384/HS512/RS256/RS384/RS512)
- UserInfo endpoint, as JSON or as JWT
- Request and Request URI
- Session management
- FrontChannel Logout
- BackChannel Logout
2021-10-26 16:52:45 +02:00
- PKCE (Since `` 2.0.4 `` ) - See :rfc: `7636`
- Introspection endpoint (Since `` 2.0.6 `` ) - See :rfc: `7662`
2020-05-14 23:29:41 +02:00
- Offline access (Since `` 2.0.7 `` )
- Refresh Tokens (Since `` 2.0.7 `` )
2021-11-10 19:36:23 +01:00
- Optional JWT Access Tokens (Since `` 2.0.12 `` ) - See :rfc: `9068`
2020-05-14 23:29:41 +02:00
Configuration
-------------
OpenID Connect Service
~~~~~~~~~~~~~~~~~~~~~~
See :doc: `OpenID Connect service<openidconnectservice>` configuration
chapter.
IssuerDB
~~~~~~~~
Go in `` General Parameters `` » `` Issuer modules `` » `` OpenID Connect ``
and configure:
2022-03-03 22:29:45 +01:00
- **Activation** : Set to `` On ``
2022-02-18 19:09:41 +01:00
- **Path** : Keep `` ^/oauth2/ `` unless you need to use another path
- **Use rule** : Rule to allow user to use this module, set to `` 1 ``
to always allow
2020-05-14 23:29:41 +02:00
2020-05-18 09:56:39 +02:00
.. tip ::
2020-05-14 23:29:41 +02:00
For example, to allow only users with a strong authentication
level:
2020-05-18 09:56:39 +02:00
2020-05-14 23:29:41 +02:00
::
2020-05-18 09:56:39 +02:00
2020-05-14 23:29:41 +02:00
$authenticationLevel > 2
2020-05-18 09:56:39 +02:00
2020-05-14 23:29:41 +02:00
Configuration of LL::NG in Relying Party
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2022-02-18 19:09:41 +01:00
Each Relying Party has its own configuration way. LL::NG exposes
its OpenID Connect metadata to help clients configuration.
2020-05-14 23:29:41 +02:00
2022-02-18 19:09:41 +01:00
Metadata can be downloaded at the standard "Well Known" URL:
2020-05-14 23:29:41 +02:00
http://auth.example.com/.well-known/openid-configuration
2022-02-18 19:09:41 +01:00
OIDC metadata example:
2020-05-14 23:29:41 +02:00
2020-05-21 15:13:24 +02:00
.. code-block :: javascript
2020-05-14 23:29:41 +02:00
{
"end_session_endpoint" : "http://auth.example.com/oauth2/logout",
"jwks_uri" : "http://auth.example.com/oauth2/jwks",
"token_endpoint_auth_methods_supported" : [
"client_secret_post",
"client_secret_basic"
],
"token_endpoint" : "http://auth.example.com/oauth2/token",
"response_types_supported" : [
"code",
"id_token",
"id_token token",
"code id_token",
"code token",
"code id_token token"
],
"userinfo_signing_alg_values_supported" : [
"none",
"HS256",
"HS384",
"HS512",
"RS256",
"RS384",
"RS512"
],
"id_token_signing_alg_values_supported" : [
"none",
"HS256",
"HS384",
"HS512",
"RS256",
"RS384",
"RS512"
],
"userinfo_endpoint" : "http://auth.example.com/oauth2/userinfo",
"request_uri_parameter_supported" : "true",
"acr_values_supported" : [
"loa-4",
"loa-1",
"loa-3",
"loa-5",
"loa-2"
],
"request_parameter_supported" : "true",
"subject_types_supported" : [
"public"
],
"issuer" : "http://auth.example.com/",
"grant_types_supported" : [
"authorization_code",
"implicit",
"hybrid"
],
"authorization_endpoint" : "http://auth.example.com/oauth2/authorize",
"scopes_supported" : [
"openid",
"profile",
"email",
"address",
"phone"
],
"require_request_uri_registration" : "false",
"registration_endpoint" : "http://auth.example.com/oauth2/register"
}
Configuration of Relying Party in LL::NG
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Go in Manager and click on `` OpenID Connect Relying Parties `` , then
2022-03-03 22:29:45 +01:00
click on `` Add OpenID Relying Party `` . Set a technical name
(without space or special character), like “sample-rp”;
2020-05-14 23:29:41 +02:00
2022-03-03 22:29:45 +01:00
You can then set this RP configuration.
2020-05-14 23:29:41 +02:00
2022-01-05 15:36:00 +01:00
.. _oidcexportedattr:
2020-05-14 23:29:41 +02:00
Exported attributes
^^^^^^^^^^^^^^^^^^^
2022-01-05 15:36:00 +01:00
.. warning ::
2020-05-14 23:29:41 +02:00
2022-02-18 19:09:41 +01:00
By default, only `standard OpenID Connect claims <http://openid.net/specs/openid-connect-core-1_0.html#StandardClaims> `__
are exposed to applications. If you want to add non-standard attributes, you have to create a new scope in the *Scope values content* section and your application must request it.
2020-12-22 10:33:41 +01:00
2022-03-03 22:29:45 +01:00
For each OpenID Connect attribute you want to expose to applications, you can define:
2020-05-14 23:29:41 +02:00
2022-02-18 19:09:41 +01:00
* **Claim name** : Name of the attribute as it will appear in Userinfo responses
* **Variable name** : Name of the LemonLDAP::NG session variable containing the attribute value
* **Type** : Attribute data type. By default, it is a string. Choosing integer or boolean will make the attribute appear as the corresponding JSON type.
* **Array** : Select how multi-valued attributes are processed
2020-11-06 18:41:19 +01:00
* **Auto** : If the session key contains a single value, it will be released as a JSON number, string or boolean, depending on the previously specified type. If the session key contains multiple values, it will be released as an array of numbers, strings or booleans.
* **Always** : Return an array even if the attribute only contains one value
* **Never** : If the session key contains a single value, it will be released as a JSON number, string or boolean. If the session key contains multiple values, it will be released as a single string with a separator character.
2020-05-14 23:29:41 +02:00
2020-05-21 15:13:24 +02:00
.. attention ::
2020-05-14 23:29:41 +02:00
2022-02-19 13:09:01 +01:00
The specific `` sub `` attribute is not defined here, but in `` User attribute `` parameter (see below).
2020-05-14 23:29:41 +02:00
2020-11-06 18:41:19 +01:00
2021-06-03 18:40:36 +02:00
.. _oidcextraclaims:
2022-01-05 15:36:00 +01:00
Scope values content
^^^^^^^^^^^^^^^^^^^^
2020-05-14 23:29:41 +02:00
2022-02-18 19:09:41 +01:00
By default, the following scope-to-attributes are mapped by LL::NG:
2020-05-14 23:29:41 +02:00
2022-01-05 15:36:00 +01:00
.. csv-table ::
:header: "Scope value", "Attribute list"
:delim: ;
:widths: auto
2020-05-14 23:29:41 +02:00
2022-01-05 15:36:00 +01:00
profile; name family_name given_name middle_name nickname preferred_username profile picture website gender birthdate zoneinfo locale updated_at
email; email email_verified
address; street_address locality region postal_code country
phone; phone_number phone_number_verified
2020-05-14 23:29:41 +02:00
2022-02-18 19:09:41 +01:00
If you want to expose custom attributes to OpenID Connect clients,
you have to declare them in a new scope in this section.
2020-05-14 23:29:41 +02:00
2022-02-18 19:09:41 +01:00
Add your additional scope as **Key** , and a space-separated list of
2022-02-18 22:21:40 +01:00
attributes as **Value** :
2020-05-14 23:29:41 +02:00
2022-01-05 15:36:00 +01:00
- `employment_info` => `position company`
2020-05-14 23:29:41 +02:00
2022-02-18 19:09:41 +01:00
In this example, an OpenID Client requesting for the `` employment_info `` scope will
2022-02-18 22:21:40 +01:00
be able to read the `` company `` and `` position `` attributes from the UserInfo endpoint.
2020-05-14 23:29:41 +02:00
2021-12-10 17:26:30 +01:00
.. important ::
2020-05-14 23:29:41 +02:00
2022-01-05 15:36:00 +01:00
Any attribute defined in this section must be mapped to a
2022-02-18 22:21:40 +01:00
LL::NG session variable in **Exported Attributes** section
2020-05-14 23:29:41 +02:00
2022-01-05 15:36:00 +01:00
.. important ::
Your custom attributes will only be visible if the application requests the
corresponding scope value
2021-06-03 18:40:36 +02:00
.. _oidcscoperules:
2022-03-03 22:29:45 +01:00
Scope rules
2021-01-14 17:33:11 +01:00
^^^^^^^^^^^
.. versionadded :: 2.0.12
|beta| This feature may change in a future version in a way that breaks
2022-02-18 19:09:41 +01:00
compatibility with existing configuration.
2021-01-14 17:33:11 +01:00
2022-02-18 19:09:41 +01:00
By default, LL::NG grants all scopes requested by the application, as
2021-01-14 17:33:11 +01:00
long as the user consents to them.
This configuration screen allows you to change that behavior by attaching
:ref: `a rule<rules>` to a particular scope.
* If the rule evaluates to true, the scope is added to the current request,
even if it was not requested by the application
* If the rule evaluates to false, the scope is removed from the current request
* Scopes which are not declared in the "Scope rules" list are left untouched
When writing scope rules, you can use the special `` $requested `` variable. This
variables evaluates to `true` within a scope rule when the corresponding scope
has been requested by the application. You can use this variable in a dynamic
rule when you only want to add a scope when the application requested it.
Examples:
* `` read `` : `` inGroup('readers') ``
* the `` read `` scope will be granted if the user is a member of the `` readers `` group even if the application did not request it.
* `` write `` : `` $requested and inGroup('writers') ``
* the `` write `` scope will be granted if the user is a member of the `` writers `` group, but only if the application requested it.
2020-05-14 23:29:41 +02:00
Options
^^^^^^^
- **Basic**
2022-08-28 00:47:03 +02:00
- **Public client** (since version `` 2.0.4 `` ): Set this RP as public
client, so authentication is not needed on tokens endpoint
2020-05-14 23:29:41 +02:00
- **Client ID** : Client ID for this RP
2022-02-18 19:09:41 +01:00
- **Client secret** : Client secret for this RP (can be used for
2020-05-14 23:29:41 +02:00
symmetric signature)
2022-08-28 00:47:03 +02:00
- **Allowed redirection addresses for login** : Space-separated list of redirect
2020-05-14 23:29:41 +02:00
addresses allowed for this RP
- **Advanced**
- **Bypass consent** : Enable if you never want to display the scope
sharing consent screen (consent will be accepted by default).
Bypassing the consent is **not** compliant with OpenID Connect
standard.
- **Force claims to be returned in ID Token** : This options will
2022-02-18 19:09:41 +01:00
make user attributes from the requested scope appear as ID Token claims
2021-02-01 17:00:54 +01:00
- **Use JWT format for Access Token** (since version `` 2.0.12 `` ): When
using this option, Access Tokens will use the JWT format, which means they
can be verified by external OAuth2.0 resource servers without using the
2022-02-18 19:09:41 +01:00
Introspection or UserInfo endpoint.
2021-02-01 17:00:54 +01:00
- **Release claims in Access Token** (since version `` 2.0.12 `` ): If Access
Tokens are in JWT format, this option lets you release the claims defined
2022-02-18 19:09:41 +01:00
in the *Extra Claims* section inside the Access Token itself
2020-05-14 23:29:41 +02:00
- **Use refresh tokens** (since version `` 2.0.7 `` ): If this option
2022-02-18 19:09:41 +01:00
is enabled, LL::NG will issue a Refresh Token that can be used
2020-05-14 23:29:41 +02:00
to obtain new access tokens as long as the user session is still
2022-02-18 19:09:41 +01:00
valid
2022-08-28 00:47:03 +02:00
- **User attribute** : Session field that will be used as main
identifier (`` sub `` ). Default value is `` whatToTrace `` .
- **Additional audiences** (since version `` 2.0.8 `` ): You can
specify a space-separated list of audiences that will be added to the
ID Token audiences
2020-05-14 23:29:41 +02:00
- **Security**
2021-02-01 17:00:54 +01:00
- **ID Token signature algorithm** : Select one of the available public key
(RSXXX) or HMAC (HSXXX) based signature algorithms
2021-06-28 14:36:17 +02:00
- **Access Token signature algorithm** (since version `` 2.0.12 `` ): Select
one of the available public key signature algorithms
2021-06-24 09:35:17 +02:00
- **Userinfo response format** (since version `` 2.0.12 `` ): By default,
UserInfo is returned as a simple JSON object. You can also choose to
return it as a JWT, using one of the available signature algorithms.
2022-02-18 19:09:41 +01:00
- **Require PKCE** (since version `` 2.0.4 `` ): A code challenge is
required at Tokens endpoint (see :rfc: `7636` )
2020-05-14 23:29:41 +02:00
- **Allow offline access** (since version `` 2.0.7 `` ): After enabling
this feature, an application may request the **offline_access**
scope, and will obtain a Refresh Token that persists even after
the user has logged off. See
https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess
for details. These offline sessions can be administered through
the Session Browser.
2022-02-18 19:09:41 +01:00
- **Allow OAuth2.0 Password Grant** (since version `` 2.0.8 `` ): Allow the use of
the :ref: `Resource Owner Password Credentials Grant <resource-owner-password-grant>` by this client.
This feature only works if you have configured a form-based authentication module.
- **Allow OAuth2.0 Client Credentials Grant** (since version `` 2.0.11 `` ): Allow the use of the
:ref: `Client Credentials Grant <client-credentials-grant>` by this client.
2022-08-28 00:47:03 +02:00
- **Authentication level** : Required authentication level to access this application
- **Access rule** : Lets you specify a :doc: `Perl rule<rules_examples>` to restrict access to this client
2020-05-14 23:29:41 +02:00
2022-02-11 18:41:11 +01:00
- **Timeouts**
2022-08-28 00:47:03 +02:00
- **Authorization Codes** : Expiration time of
Authorization Codes, when using the Authorization Code flow.
Default value is one minute.
- **ID Tokens** : Expiration time of ID Tokens. Default
2022-02-11 18:41:11 +01:00
value is one hour.
2022-08-28 00:47:03 +02:00
- **Access Tokens** : Expiration time
of Access Tokens. Default value is one hour.
- **Offline sessions** : Lifetime of the
refresh token obtained with the **offline_access** scope.
Default value is one month. This parameter only applies if offline
2022-02-11 18:41:11 +01:00
sessions are enabled.
2022-01-31 15:57:19 +01:00
- **Logout**
2022-07-01 16:45:48 +02:00
- **Bypass confirm** : Bypass logout confirmation when logout is initiated
by relaying party
2022-08-28 00:47:03 +02:00
- **Session required** : Whether to send the Session ID in the logout request
- **Type** : Type of logout to perform (only Front-Channel is implemented for now)
- **URL** : Specify the relying party's logout URL
2022-02-18 19:09:41 +01:00
- **Allowed redirection addresses for logout** : A space-separated list of
2022-01-31 15:57:19 +01:00
URLs that this client can redirect the user to once the logout is done
(through `` post_logout_redirect_uri `` )
2022-03-03 22:29:45 +01:00
Macros
^^^^^^
You can define here macros that will be only evaluated for this service,
2022-08-28 00:47:03 +02:00
and not registered in the user's session.
2022-03-03 22:29:45 +01:00
Display
^^^^^^^
- **Display name** : Name of the RP application
- **Logo** : Logo of the RP application
.. |beta| image :: /documentation/beta.png
2021-09-01 15:28:57 +02:00
Access Rule extra variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^
When writing your access rules, you can additionally use the following variables:
* `` $_oidc_grant_type `` (since version `` 2.0.14 `` ): the grant type being used to
access this service. Possible values: `` authorizationcode `` ,
`` implicit `` , `` hybrid `` , `` clientcredentials `` , `` password ``
2020-05-14 23:29:41 +02:00
2021-01-19 11:10:10 +01:00
.. _resource-owner-password-grant:
Resource Owner Password Credentials Grant
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The Resource Owner Password Credentials Grant allows you to exchange a user's login and password for an access token. This must be considered a legacy form of authentication, since the Authorization Code web-based flow is prefered for all applications that support it. It can however be useful in some scenarios involving technical accounts that cannot implement a web-based authentication flow.
2021-04-07 16:40:15 +02:00
.. versionchanged :: 2.0.12
2022-02-19 13:09:01 +01:00
When using the :doc: `Choice <authchoice>` authentication module, the *Choice used for password authentication* setting can be used for selecting which authentication choice is used by the Resource Owner Password Credentials Grant. Naturally, the selected choice must be a password-based authentication method (LDAP, DBI, REST, etc.).
2021-04-07 16:40:15 +02:00
2021-01-19 11:10:10 +01:00
.. seealso ::
2021-10-26 16:52:45 +02:00
Specification for the Resource Owner Password Credentials Grant: :rfc: `6749#section-4.3`
2021-01-19 11:10:10 +01:00
.. _client-credentials-grant:
Client Credentials Grant
^^^^^^^^^^^^^^^^^^^^^^^^
The Client Credentials Grant allows you to obtain an Access Token using only a Relying Party's Client ID and Client Secret.
The following attributes are made available in the created session:
* The `` _whatToTrace `` attribute (main session identifier), is set to the
2022-04-04 09:03:08 +02:00
relying party's Client ID
2021-01-19 11:10:10 +01:00
* The `` _scope `` attribute is set to the requested scopes
* The `` _clientId `` attribute is set to the Client ID that obtained the access
token.
* The `` _clientConfKey `` attribute is set to the LemonLDAP::NG configuration
key for the client that obtained the access token.
2022-02-19 13:09:01 +01:00
The **Access Rule** , if defined, will have access to those variables, as well as
2021-01-19 11:10:10 +01:00
the `@ENV` array. You can use it to restrict the use of this grant to
pre-determined scopes, a particular IP address, etc.
2022-02-19 13:09:01 +01:00
These session attributes will be released on the UserInfo endpoint if they are
mapped to **Exported Attributes** and **Extra Claims** .
2021-01-19 11:10:10 +01:00
.. seealso ::
2021-10-26 16:52:45 +02:00
Specification for the Client Credentials Grant: :rfc: `6749#section-4.4`