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/.
LL::NG can act as an OpenID Connect Provider (OP). It will answer to
2021-04-02 23:57:30 +02:00
OpenID Connect requests to give user identity (through ID Token) and
information (through User Info end point).
2020-05-14 23:29:41 +02:00
As an OP, LL::NG supports a lot of OpenID Connect features:
- 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:
- **Activation** : set to `` On `` .
- **Path** : keep `` ^/oauth2/ `` unless you need to use another path
- **Use rule** : a rule to allow user to use this module, set to `` 1 ``
to always allow.
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Each Relying Party has its own configuration way. LL::NG publish its
OpenID Connect metadata to ease the configuration of client.
The metadata can be found at the standard "Well Known" URL:
http://auth.example.com/.well-known/openid-configuration
An example of its content:
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
click on `` Add OpenID Relying Party `` . Give a technical label (no
spaces, no special characters), like “sample-rp”;
You can then access to the configuration of this RP.
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-01-05 15:36:00 +01:00
By default, only `standard OpenID Connect claims <http://openid.net/specs/openid-connect-core-1_0.html#StandardClaims> `__ are visible to applications. If you want to add non-standard attributes, you must create a new scope in the *Scope values content* section and make your application request it
2020-12-22 10:33:41 +01:00
2022-01-05 15:36:00 +01:00
For each OpenID Connect attribute you want to release to applications, you can define:
2020-05-14 23:29:41 +02:00
2022-01-05 15:36:00 +01:00
* **Claim name** : the name of the attribute as it will appear in Userinfo responses
* **Variable name** : the name of the LemonLDAP::NG session variable containing the attribute value
* **Type** : the data type of the attribute. By default, a string. Choosing integer or boolean will make the attribute appear as the corresponding JSON type.
2020-11-06 18:41:19 +01:00
* **Array** : choose how to process multi-valued attributes
* **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
The specific `` sub `` attribute is not defined here, but
in User attribute parameter (see below).
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-01-05 15:36:00 +01:00
By default, LemonLDAP::NG already defines the following scope-to-attribute map:
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-01-05 15:36:00 +01:00
If you want to make custom attribute visible to OpenID Connect clients, you
need to declare them in a new scope in this section.
2020-05-14 23:29:41 +02:00
Add your additional scope as the **Key** , and a space-separated list of
2022-01-05 15:36:00 +01:00
attribute as the **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-01-05 15:36:00 +01:00
In this example, an OpenID Client asking for the `` employment_info `` scope will
be able to read the `` company `` and `` position `` attribute from the
2020-05-14 23:29:41 +02:00
Userinfo endpoint.
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
LemonLDAP::NG session variable in the **Exported Attributes**
2020-05-14 23:29:41 +02:00
section
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:
2021-01-14 17:33:11 +01:00
Scope Rules
^^^^^^^^^^^
.. versionadded :: 2.0.12
|beta| This feature may change in a future version in a way that breaks
compatibility with existing configuration
By default, LemonLDAP::NG grants all scopes requested by the application, as
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**
- **Client ID** : Client ID for this RP
- **Client secret** : Client secret for this RP (can be use for
symmetric signature)
- **Public client** (since version `` 2.0.4 `` ): set this RP as public
client, so authentication is not needed on token endpoint
- **Redirection addresses** : Space separated list of redirect
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.
- **User attribute** : session field that will be used as main
identifier (`` sub `` )
- **Force claims to be returned in ID Token** : This options will
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
introspection or userinfo endpoint.
- **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
in the *Extra Claims* section inside the Access Token itself.
2020-05-14 23:29:41 +02:00
- **Additional audiences** (since version `` 2.0.8 `` ): You can
specify a space-separate list of audiences that will be added the
audiences of the ID Token
- **Use refresh tokens** (since version `` 2.0.7 `` ): If this option
is set, LemonLDAP::NG will issue a Refresh Token that can be used
to obtain new access tokens as long as the user session is still
valid.
- **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.
2020-05-14 23:29:41 +02:00
- **Require PKCE** (since version `` 2.0.4 `` ): a code challenge is
required at token endpoint (see
2021-10-26 16:52:45 +02:00
: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.
2021-01-19 11:10:10 +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.
2021-03-10 15:55:13 +01:00
- **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.
2020-06-11 19:04:16 +02:00
- **Authentication Level** : required authentication level to access this application
2020-05-18 09:56:39 +02:00
- **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**
- **Authorization Code expiration** : Expiration time of
authorization code, when using the Authorization Code flow. The
default value is one minute.
- **ID Token expiration** : Expiration time of ID Tokens. The default
value is one hour.
- **Access token expiration** : Expiration time
of Access Tokens. The default value is one hour.
- **Offline session expiration** : This sets the lifetime of the
refresh token obtained with the **offline_access** scope. The
default value is one month. This parameter only applies if offline
sessions are enabled.
2022-01-31 15:57:19 +01:00
- **Logout**
- **Allowed redirection addresses for logout** : A space separated list of
URLs that this client can redirect the user to once the logout is done
(through `` post_logout_redirect_uri `` )
- **URL** : Specify the relying party's logout URL
- **Type** : Type of Logout to perform (only Front-Channel is implemented for now)
- **Session required** : Whether to send the Session ID in the logout request
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
when using the :doc: `Choice <authchoice>` authentication module, the *Choice used for password authentication* setting can be used to select 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-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
relying party's configuration key
* 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.
The Access Rule, if defined, will have access to those variables, as well as
the `@ENV` array. You can use it to restrict the use of this grant to
pre-determined scopes, a particular IP address, etc.
These session attribute will be released on the UserInfo endpoint if they are
mapped to Exported Attributes and Extra Claims
.. seealso ::
2021-10-26 16:52:45 +02:00
Specification for the Client Credentials Grant: :rfc: `6749#section-4.4`
2021-01-19 11:10:10 +01:00
2020-05-14 23:29:41 +02:00
Macros
^^^^^^
You can define here macros that will be only evaluated for this service,
and not registered in the session of the user.
Display
^^^^^^^
- **Display name** : Name of the RP application
- **Logo** : Logo of the RP application
2021-01-14 17:33:11 +01:00
.. |beta| image :: /documentation/beta.png