lemonldap-ng/doc/pages/documentation/current/idpopenidconnect.html
2019-09-23 22:41:16 +02:00

422 lines
21 KiB
HTML

<!DOCTYPE html>
<html lang="en" dir="ltr">
<head>
<meta charset="utf-8" />
<title>documentation:2.0:idpopenidconnect</title>
<meta name="generator" content="DokuWiki"/>
<meta name="robots" content="index,follow"/>
<meta name="keywords" content="documentation,2.0,idpopenidconnect"/>
<link rel="search" type="application/opensearchdescription+xml" href="lib/exe/opensearch.html" title="LemonLDAP::NG"/>
<link rel="start" href="idpopenidconnect.html"/>
<link rel="contents" href="idpopenidconnect.html" title="Sitemap"/>
<link rel="stylesheet" type="text/css" href="lib/exe/css.php.t.bootstrap3.css"/>
<!-- //if:usedebianlibs
<link rel="stylesheet" type="text/css" href="/javascript/bootstrap/css/bootstrap.min.css" />
//elsif:useexternallibs
<link rel="stylesheet" type="text/css" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css"></script>
//elsif:cssminified
<link rel="stylesheet" type="text/css" href="/static/bwr/bootstrap/dist/css/bootstrap.min.css" />
//else -->
<link rel="stylesheet" type="text/css" href="/static/bwr/bootstrap/dist/css/bootstrap.css" />
<!-- //endif -->
<script type="text/javascript">/*<![CDATA[*/var NS='documentation:2.0';var JSINFO = {"id":"documentation:2.0:idpopenidconnect","namespace":"documentation:2.0"};
/*!]]>*/</script>
<script type="text/javascript" charset="utf-8" src="lib/exe/js.php.t.bootstrap3.js"></script>
<!-- //if:usedebianlibs
<script type="text/javascript" src="/javascript/jquery/jquery.min.js"></script>
//elsif:useexternallibs
<script type="text/javascript" src="http://code.jquery.com/jquery-2.2.0.min.js"></script>
//elsif:jsminified
<script type="text/javascript" src="/static/bwr/jquery/dist/jquery.min.js"></script>
//else -->
<script type="text/javascript" src="/static/bwr/jquery/dist/jquery.js"></script>
<!-- //endif -->
<!-- //if:usedebianlibs
<script type="text/javascript" src="/javascript/jquery-ui/jquery-ui.min.js"></script>
//elsif:useexternallibs
<script type="text/javascript" src="http://code.jquery.com/ui/1.10.4/jquery-ui.min.js"></script>
//elsif:jsminified
<script type="text/javascript" src="/static/bwr/jquery-ui/jquery-ui.min.js"></script>
//else -->
<script type="text/javascript" src="/static/bwr/jquery-ui/jquery-ui.js"></script>
<!-- //endif -->
</head>
<body>
<div class="dokuwiki export container">
<!-- TOC START -->
<div id="dw__toc">
<h3 class="toggle">Table of Contents</h3>
<div>
<ul class="toc">
<li class="level1"><div class="li"><a href="#presentation">Presentation</a></div></li>
<li class="level1"><div class="li"><a href="#configuration">Configuration</a></div>
<ul class="toc">
<li class="level2"><div class="li"><a href="#openid_connect_service">OpenID Connect Service</a></div></li>
<li class="level2"><div class="li"><a href="#issuerdb">IssuerDB</a></div></li>
<li class="level2"><div class="li"><a href="#configuration_of_llng_in_relying_party">Configuration of LL::NG in Relying Party</a></div></li>
<li class="level2"><div class="li"><a href="#configuration_of_relying_party_in_llng">Configuration of Relying Party in LL::NG</a></div>
<ul class="toc">
<li class="level3"><div class="li"><a href="#exported_attributes">Exported attributes</a></div></li>
<li class="level3"><div class="li"><a href="#options">Options</a></div></li>
<li class="level3"><div class="li"><a href="#extra_claims">Extra claims</a></div></li>
</ul></li>
</ul></li>
</ul>
</div>
</div>
<!-- TOC END -->
<h1 class="sectionedit1" id="openid_connect_provider">OpenID Connect Provider</h1>
<div class="level1">
</div>
<!-- EDIT1 SECTION "OpenID Connect Provider" [1-39] -->
<h2 class="sectionedit2" id="presentation">Presentation</h2>
<div class="level2">
<div class="noteclassic">OpenID Connect is a protocol based on REST, OAuth 2.0 and JOSE stacks. It is described here: <a href="http://openid.net/connect/" class="urlextern" title="http://openid.net/connect/" rel="nofollow">http://openid.net/connect/</a>.
</div>
<p>
<abbr title="LemonLDAP::NG">LL::NG</abbr> can act as an OpenID Connect Provider (OP). It will answer to OpenID Connect requests to give user identity (trough ID Token) and information (trough User Info end point).
</p>
<p>
As an OP, <abbr title="LemonLDAP::NG">LL::NG</abbr> supports a lot of OpenID Connect features:
</p>
<ul>
<li class="level1"><div class="li"> Authorization Code, Implicit and Hybrid flows</div>
</li>
<li class="level1"><div class="li"> Publication of JSON metadata and JWKS data (Discovery)</div>
</li>
<li class="level1"><div class="li"> <code>prompt</code>, <code>display</code>, <code>ui_locales</code>, <code>max_age</code> parameters</div>
</li>
<li class="level1"><div class="li"> Extra claims definition</div>
</li>
<li class="level1"><div class="li"> Authentication context Class References (ACR)</div>
</li>
<li class="level1"><div class="li"> Nonce</div>
</li>
<li class="level1"><div class="li"> Dynamic registration</div>
</li>
<li class="level1"><div class="li"> Access Token Hash generation</div>
</li>
<li class="level1"><div class="li"> ID Token signature (HS256/HS384/HS512/RS256/RS384/RS512)</div>
</li>
<li class="level1"><div class="li"> UserInfo end point, as JSON or as JWT</div>
</li>
<li class="level1"><div class="li"> Request and Request <abbr title="Uniform Resource Identifier">URI</abbr></div>
</li>
<li class="level1"><div class="li"> Session management</div>
</li>
<li class="level1"><div class="li"> FrontChannel Logout</div>
</li>
<li class="level1"><div class="li"> BackChannel Logout</div>
</li>
<li class="level1"><div class="li"> PKCE (Since <code>2.0.4</code>)</div>
</li>
</ul>
</div>
<!-- EDIT2 SECTION "Presentation" [40-996] -->
<h2 class="sectionedit3" id="configuration">Configuration</h2>
<div class="level2">
</div>
<!-- EDIT3 SECTION "Configuration" [997-1023] -->
<h3 class="sectionedit4" id="openid_connect_service">OpenID Connect Service</h3>
<div class="level3">
<p>
See <a href="openidconnectservice.html" class="wikilink1" title="documentation:2.0:openidconnectservice">OpenID Connect service</a> configuration chapter.
</p>
</div>
<!-- EDIT4 SECTION "OpenID Connect Service" [1024-1133] -->
<h3 class="sectionedit5" id="issuerdb">IssuerDB</h3>
<div class="level3">
<p>
Go in <code>General Parameters</code> » <code>Issuer modules</code> » <code>OpenID Connect</code> and configure:
</p>
<ul>
<li class="level1"><div class="li"> <strong>Activation</strong>: set to <code>On</code>.</div>
</li>
<li class="level1"><div class="li"> <strong>Path</strong>: keep <code>^/oauth2/</code> unless you need to use another path</div>
</li>
<li class="level1"><div class="li"> <strong>Use rule</strong>: a rule to allow user to use this module, set to <code>1</code> to always allow.</div>
</li>
</ul>
<div class="notetip">For example, to allow only users with a strong authentication level:
<pre class="code">$authenticationLevel &gt; 2</pre>
</div>
</div>
<!-- EDIT5 SECTION "IssuerDB" [1134-1564] -->
<h3 class="sectionedit6" id="configuration_of_llng_in_relying_party">Configuration of LL::NG in Relying Party</h3>
<div class="level3">
<p>
Each Relying Party has its own configuration way. <abbr title="LemonLDAP::NG">LL::NG</abbr> publish its OpenID Connect metadata to ease the configuration of client.
</p>
<p>
The metadata can be found at the standard &quot;Well Known&quot; <abbr title="Uniform Resource Locator">URL</abbr>: <a href="http://auth.example.com/.well-known/openid-configuration" class="urlextern" title="http://auth.example.com/.well-known/openid-configuration" rel="nofollow">http://auth.example.com/.well-known/openid-configuration</a>
</p>
<p>
An example of its content:
</p>
<pre class="code file javascript"><span class="br0">&#123;</span>
<span class="st0">&quot;end_session_endpoint&quot;</span> <span class="sy0">:</span> <span class="st0">&quot;http://auth.example.com/oauth2/logout&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;jwks_uri&quot;</span> <span class="sy0">:</span> <span class="st0">&quot;http://auth.example.com/oauth2/jwks&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;token_endpoint_auth_methods_supported&quot;</span> <span class="sy0">:</span> <span class="br0">&#91;</span>
<span class="st0">&quot;client_secret_post&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;client_secret_basic&quot;</span>
<span class="br0">&#93;</span><span class="sy0">,</span>
<span class="st0">&quot;token_endpoint&quot;</span> <span class="sy0">:</span> <span class="st0">&quot;http://auth.example.com/oauth2/token&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;response_types_supported&quot;</span> <span class="sy0">:</span> <span class="br0">&#91;</span>
<span class="st0">&quot;code&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;id_token&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;id_token token&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;code id_token&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;code token&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;code id_token token&quot;</span>
<span class="br0">&#93;</span><span class="sy0">,</span>
<span class="st0">&quot;userinfo_signing_alg_values_supported&quot;</span> <span class="sy0">:</span> <span class="br0">&#91;</span>
<span class="st0">&quot;none&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;HS256&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;HS384&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;HS512&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;RS256&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;RS384&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;RS512&quot;</span>
<span class="br0">&#93;</span><span class="sy0">,</span>
<span class="st0">&quot;id_token_signing_alg_values_supported&quot;</span> <span class="sy0">:</span> <span class="br0">&#91;</span>
<span class="st0">&quot;none&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;HS256&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;HS384&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;HS512&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;RS256&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;RS384&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;RS512&quot;</span>
<span class="br0">&#93;</span><span class="sy0">,</span>
<span class="st0">&quot;userinfo_endpoint&quot;</span> <span class="sy0">:</span> <span class="st0">&quot;http://auth.example.com/oauth2/userinfo&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;request_uri_parameter_supported&quot;</span> <span class="sy0">:</span> <span class="st0">&quot;true&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;acr_values_supported&quot;</span> <span class="sy0">:</span> <span class="br0">&#91;</span>
<span class="st0">&quot;loa-4&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;loa-1&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;loa-3&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;loa-5&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;loa-2&quot;</span>
<span class="br0">&#93;</span><span class="sy0">,</span>
<span class="st0">&quot;request_parameter_supported&quot;</span> <span class="sy0">:</span> <span class="st0">&quot;true&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;subject_types_supported&quot;</span> <span class="sy0">:</span> <span class="br0">&#91;</span>
<span class="st0">&quot;public&quot;</span>
<span class="br0">&#93;</span><span class="sy0">,</span>
<span class="st0">&quot;issuer&quot;</span> <span class="sy0">:</span> <span class="st0">&quot;http://auth.example.com/&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;grant_types_supported&quot;</span> <span class="sy0">:</span> <span class="br0">&#91;</span>
<span class="st0">&quot;authorization_code&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;implicit&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;hybrid&quot;</span>
<span class="br0">&#93;</span><span class="sy0">,</span>
<span class="st0">&quot;authorization_endpoint&quot;</span> <span class="sy0">:</span> <span class="st0">&quot;http://auth.example.com/oauth2/authorize&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;check_session_iframe&quot;</span> <span class="sy0">:</span> <span class="st0">&quot;http://auth.example.com/oauth2/checksession&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;scopes_supported&quot;</span> <span class="sy0">:</span> <span class="br0">&#91;</span>
<span class="st0">&quot;openid&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;profile&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;email&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;address&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;phone&quot;</span>
<span class="br0">&#93;</span><span class="sy0">,</span>
<span class="st0">&quot;require_request_uri_registration&quot;</span> <span class="sy0">:</span> <span class="st0">&quot;false&quot;</span><span class="sy0">,</span>
<span class="st0">&quot;registration_endpoint&quot;</span> <span class="sy0">:</span> <span class="st0">&quot;http://auth.example.com/oauth2/register&quot;</span>
<span class="br0">&#125;</span></pre>
</div>
<!-- EDIT6 SECTION "Configuration of LL::NG in Relying Party" [1565-3543] -->
<h3 class="sectionedit7" id="configuration_of_relying_party_in_llng">Configuration of Relying Party in LL::NG</h3>
<div class="level3">
<p>
Go in Manager and click on <code>OpenID Connect Relying Parties</code>, then click on <code>Add OpenID Relying Party</code>. Give a technical name (no spaces, no special characters), like “sample-rp”;
</p>
<p>
You can then access to the configuration of this RP.
</p>
</div>
<h4 id="exported_attributes">Exported attributes</h4>
<div class="level4">
<p>
You can map here the attribute names from the <abbr title="LemonLDAP::NG">LL::NG</abbr> session to an <a href="http://openid.net/specs/openid-connect-core-1_0.html#StandardClaims" class="urlextern" title="http://openid.net/specs/openid-connect-core-1_0.html#StandardClaims" rel="nofollow">OpenID Connect claim</a>.
</p>
</div>
<!-- EDIT8 PLUGIN_INCLUDE_START_NOREDIRECT "documentation:2.0:openidconnectclaims" [0-] --><div class="plugin_include_content plugin_include__documentation:2.0:openidconnectclaims" id="plugin_include__documentation__2.0__openidconnectclaims">
<div class="level1">
<div class="table sectionedit10"><table class="inline table table-bordered table-striped">
<thead>
<tr class="row0 roweven">
<th class="col0"> Claim name </th><th class="col1"> Type </th><th class="col2"> Example of corresponding LDAP attribute </th>
</tr>
</thead>
<tr class="row1 rowodd">
<td class="col0"> sub </td><td class="col1"> string </td><td class="col2"> uid </td>
</tr>
<tr class="row2 roweven">
<td class="col0"> name </td><td class="col1"> string </td><td class="col2"> cn </td>
</tr>
<tr class="row3 rowodd">
<td class="col0"> given_name </td><td class="col1"> string </td><td class="col2"> givenName </td>
</tr>
<tr class="row4 roweven">
<td class="col0"> family_name </td><td class="col1"> string </td><td class="col2"> sn </td>
</tr>
<tr class="row5 rowodd">
<td class="col0"> middle_name </td><td class="col1"> string </td><td class="col2"> </td>
</tr>
<tr class="row6 roweven">
<td class="col0"> nickname </td><td class="col1"> string </td><td class="col2"> </td>
</tr>
<tr class="row7 rowodd">
<td class="col0"> preferred_username </td><td class="col1"> string </td><td class="col2"> displayName </td>
</tr>
<tr class="row8 roweven">
<td class="col0"> profile </td><td class="col1"> string </td><td class="col2"> labeledURI </td>
</tr>
<tr class="row9 rowodd">
<td class="col0"> picture </td><td class="col1"> string </td><td class="col2"> </td>
</tr>
<tr class="row10 roweven">
<td class="col0"> website </td><td class="col1"> string </td><td class="col2"> </td>
</tr>
<tr class="row11 rowodd">
<td class="col0"> email </td><td class="col1"> string </td><td class="col2"> mail </td>
</tr>
<tr class="row12 roweven">
<td class="col0"> email_verified </td><td class="col1"> boolean </td><td class="col2"> </td>
</tr>
<tr class="row13 rowodd">
<td class="col0"> gender </td><td class="col1"> string </td><td class="col2"> </td>
</tr>
<tr class="row14 roweven">
<td class="col0"> birthdate </td><td class="col1"> string </td><td class="col2"> </td>
</tr>
<tr class="row15 rowodd">
<td class="col0"> zoneinfo </td><td class="col1"> string </td><td class="col2"> </td>
</tr>
<tr class="row16 roweven">
<td class="col0"> locale </td><td class="col1"> string </td><td class="col2"> preferredLanguage </td>
</tr>
<tr class="row17 rowodd">
<td class="col0"> phone_number </td><td class="col1"> string </td><td class="col2"> telephoneNumber </td>
</tr>
<tr class="row18 roweven">
<td class="col0"> phone_number_verified </td><td class="col1"> boolean </td><td class="col2"> </td>
</tr>
<tr class="row19 rowodd">
<td class="col0"> updated_at </td><td class="col1"> string </td><td class="col2"> </td>
</tr>
<tr class="row20 roweven">
<td class="col0"> formatted </td><td class="col1"> string </td><td class="col2"> registeredAddress </td>
</tr>
<tr class="row21 rowodd">
<td class="col0"> street_address </td><td class="col1"> string </td><td class="col2"> street </td>
</tr>
<tr class="row22 roweven">
<td class="col0"> locality </td><td class="col1"> string </td><td class="col2"> l </td>
</tr>
<tr class="row23 rowodd">
<td class="col0"> region </td><td class="col1"> string </td><td class="col2"> st </td>
</tr>
<tr class="row24 roweven">
<td class="col0"> postal_code </td><td class="col1"> string </td><td class="col2"> postalCode </td>
</tr>
<tr class="row25 rowodd">
<td class="col0"> country </td><td class="col1"> string </td><td class="col2"> co </td>
</tr>
</table></div>
<!-- EDIT10 TABLE [38-861] -->
</div>
<!-- EDIT9 PLUGIN_INCLUDE_END "documentation:2.0:openidconnectclaims" [0-] --></div>
<div class="level4">
<p>
So you can define for example:
</p>
<ul>
<li class="level1"><div class="li"> name =&gt; cn</div>
</li>
<li class="level1"><div class="li"> family_name =&gt; sn</div>
</li>
<li class="level1"><div class="li"> email =&gt; mail</div>
</li>
</ul>
<div class="noteimportant">The specific <code>sub</code> attribute is not defined here, but in User attribute parameter (see below).
</div>
<p>
You can also define extra claims and link them to attributes (see below). Then you just have to define the mapping of this new attributes, for example:
</p>
<ul>
<li class="level1"><div class="li"> birthplace =&gt; l</div>
</li>
<li class="level1"><div class="li"> birthcountry =&gt; co</div>
</li>
</ul>
</div>
<h4 id="options">Options</h4>
<div class="level4">
<ul>
<li class="level1"><div class="li"> <strong>Authentication</strong>:</div>
<ul>
<li class="level2"><div class="li"> <strong>Client ID</strong>: Client ID for this RP</div>
</li>
<li class="level2"><div class="li"> <strong>Client secret</strong>: Client secret for this RP (can be use for symmetric signature)</div>
</li>
<li class="level2"><div class="li"> <strong>Public client</strong> (since version <code>2.0.4</code>): set this RP as public client, so authentication is not needed on token endpoint</div>
</li>
<li class="level2"><div class="li"> <strong>Require PKCE</strong> (since version <code>2.0.4</code>): a code challenge is required at token endpoint (see <a href="https://tools.ietf.org/html/rfc7636" class="urlextern" title="https://tools.ietf.org/html/rfc7636" rel="nofollow">RFC7636</a>)</div>
</li>
</ul>
</li>
<li class="level1"><div class="li"> <strong>Display</strong>:</div>
<ul>
<li class="level2"><div class="li"> <strong>Display name</strong>: Name of the RP application</div>
</li>
<li class="level2"><div class="li"> <strong>Logo</strong>: Logo of the RP application</div>
</li>
</ul>
</li>
<li class="level1"><div class="li"> <strong>User attribute</strong>: session field that will be used as main identifier (<code>sub</code>)</div>
</li>
<li class="level1"><div class="li"> <strong>ID Token signature algorithm</strong>: Select one of <code>none</code>, <code>HS256</code>, <code>HS384</code>, <code>HS512</code>, <code>RS256</code>, <code>RS384</code>, <code>RS512</code></div>
</li>
<li class="level1"><div class="li"> <strong>ID Token expiration</strong>: Expiration time of ID Tokens</div>
</li>
<li class="level1"><div class="li"> <strong>Access token expiration</strong>: Expiration time of Access Tokens</div>
</li>
<li class="level1"><div class="li"> <strong>Redirection addresses</strong>: Space separated list of redirect addresses allowed for this RP</div>
</li>
<li class="level1"><div class="li"> <strong>Bypass consent</strong>: Enable if you never want to display the scope sharing consent screen (consent will be accepted by default). Bypassing the consent is <strong>not</strong> compliant with OpenID Connect standard.</div>
</li>
</ul>
</div>
<h4 id="extra_claims">Extra claims</h4>
<div class="level4">
<p>
Associate attributes to extra claims if the RP request them, for example <code>birth</code> =&gt; <code>birthplace birthcountry</code>
</p>
</div>
<!-- EDIT7 SECTION "Configuration of Relying Party in LL::NG" [3544-] --></div>
</body>
</html>