oidc-sample-client

Demo OpenID Connect service provider in NodeJS (tutorial mode)

Tutoral

Requirements

NodeJS >= 8.16

Init

Clone the sources:

git clone https://github.com/kaliop/oidc-sample-client.git && cd oidc-sample-client

Fetch the start tag to get the boostrap:

git checkout start

Install main depencencies:

npm install

Start the application:

npm start

Go to http://localhost:3000

Step 1 - warm-up: standard local login

checkout step-01

No difficulties here. Note: To avoid having to install an external database for the tutorial, we use a CSV file to store fake useres, and node-csv-query library to request it.

Step 2 - logout

checkout step-02

Just detroy the session.

Step 3 - OpenID Connect LoginAuthorize

checkout step-03

Now, let's really start this tutorial. We will implement a client connexion using the Authorization Code Flow. The tutorial code uses a sample identity provider hosted at http://sample-oidc-provider.dev-franceconnect.fr , or you can override environment variables (see config file) if you want to use your own Idp.

The first step is to redirect the user to the identity provider's authorize enpoint, with the required request parameters :

• response_type: specifies the used authorization flow. ie. "code" here.

• scope: specifies which user data the service requires.
  Space delimited list of keywords ('openid', 'profile', 'email', 'address', 'phone'). At least "openid" is required. The other are optional.

• client_id: The OAuth 2.0 Client Identifier knonw by the identity provider.

• redirect_uri: the URL to which the end user will be redirected by the identity provider once authenticated. (ie. the loginCallback that will be implemented in next steps). This uri must have been registered at the identity provider size.

Step 4 - Login Callback : get access token and id token.

checkout step-04

Once the end user has been authenticated by the identity provider, he is redirected to the redrect_uri specified above. The loginCallback endpoint is as follow : <service-fqdn>/login-callback?code=<code>.

We need to call the Token Endpoint as a POST HTTP request with following parameters:

• grant_type: must be "authorisation_code"
• code: the same code value that has just been sent within the loginCallback request. Used to validate the token request.
• redirect_uri: the current request URI.

The reponse must be a JSON containing a access_token and a id_token attributes. We need also to check if the ID Token is valid (see next step)

Step 5 - Login Callback : ID Token Validation

checkout step-05

Check if the ID Token is a valid JWT and if it is compliant to OpenID ID Token Validation rules.

Step 6 - Login Callback : get User Info

checkout step-06

Call User Info Endpoint to get all the needed user data, and store them in session. Now, the end user is fully authenticated into our service.

Step 7 - Login Callback : add scope and map fields

checkout step-07

Claims full scopes to get every userInfo. We also need to reformat the date received from userInfo, to match them to our local format.

Step 8 - Add "state" and "nonce" parameters

checkout step-08

These parameters are not required, but fully recommanded to secure the authentication flow.

Both are random values that are included into the userAuthorize request and check later within the flow:

• state, if present, must be added by the identity provider as additionnal parameter tologinCallback url.
• nonce, if present, must be added by the identity provider within the ID Token.

Step 9: Logout propagation

checkout step-09

Implement the logout propagation (see RP-Initiated Logout):

Resources

• Demo OpenID Connect identity provider
• OpenID Connect Official Specifications
• OpenID Connect Official Basic Guide
• JSON Web Tokens
• Unofficial documentation
• List of certified OpenID Connect libraries