OpenID Connect tester for developers

OIDC tester screen shot : id_token decoded

When you are a developer and you need to configure an identity provider and get the ID Token and Access Token content right, you often spend an important amount of time iterating over the configuration with your code in debugging mode or tracing the content in the console.

As per the good principle of reducing the “feedback loop” in development cycle, I realise that there was certainly something that could be done to help this.

This article assumes that the you have some understanding of OIDC (= OpenId Connect) or at least that you arrive on this page knowing what you are looking for. If you need to understand OIDC and OAuth2 security protocols, there are tons of good publications on the web.

However, let’s bring some context into this publication:

When I started working with OIDC protocol and started to fight to understand the configuration and understand the reason why authentication failed, I discover the good tools such as oidcdebugger.com and oauthdebugger.com and also the authentication of Postman, but none of them was bringing me what I really expecting: “a way to quickly test the connection, see the ID Token and introspect the other tokens”.

Mostly, I my work, the approach was the “authorisation code” flow mechanism that was used, which cannot be fully debug via the browser network flow since it requires a call from the application back end to the identity provider with the client secret.

The product is still at early stage, but it is usable so I decided to publish to see what you think and if it is useful.

OIDC Tester is a nodejs tool packaged as a docker container that is free to install and use (just give me feedbacks :-) ).

The code is available at : https://gitlab.com/guenoledc-perso/idp-oidc-tester

Get started: I recommend installing oidc-tester as a docker container if you do not need to make change in the code.

$ docker pull registry.gitlab.com/guenoledc-perso/idp-oidc-tester:latest
$ docker run --name oidc-tester -p 8080:80 registry.gitlab.com/guenoledc-perso/idp-oidc-tester:latest

Then navigate to http://localhost:8080

You are first invited to create a new configuration (the configuration is saved in /data/.idp-conf, use a volume to export it outside the docker container).

The easiest way is to use the OIDC discover url of the identity provider. Let’s perform a configuration for Gitlab used as an IDP (you must have a gitlab account).

1. Set the discover url to https://gitlab.com/.well-known/openid-configuration
2. Navigate to https://gitlab.com/profile/applications
3. Fill the application (= client in oidc term) form and set name, Redirect URI as the uri given in the OIDC tester above and do not forget to select at least openid scope (to comply with the protocol and receive an id_token)

4. Save the application. You will be provided an application id (= client_id in oidc term) and a Secret.

5. Set these two information in client id and client secret of the oidc-tester configuration form. Also, set the scope field to openid and other selected scopes (space separated), then “Save”

6. Select the new configuration and click “Apply” to tell the tool to start working with this configuration. You have the below screen

7. Click Login, and follow the authentication process

From here you are authenticated and each function provide quick access to the token or to act on the session. The displayed json contains in particular the tokens structure returned by the identity provider

• Refresh: will use the refresh_token to request a renewal of the access_token
• Session: display the session content managed by the tool with the token, the set cookies, and various other information that are not specific to oidc. note that idTokenDecoded is not really the id_token. It needs to be corrected in the code.
• Access Token: will call the introspect endpoint of the identity provider from the back end to try to get the information that this token bears. Not all identity provider implements this.
• ID Token: will decode the id_token JWT and display the result.
• Refresh Token: will call the introspect endpoint of the identity provider from the back end to try to get the information that this token bears. Not all identity provider implements this.
• User Info: will call the user info endpoint from the back end with the current access token and display the result.
• Logout: will redirect the browser to the end session endpoint to tell the identity provider to terminate the connection.

That’s all for now. I hope some of you will find this tool useful.

Do not hesitate to ping me and give me feedbacks : https://gitlab.com/guenoledc-perso/idp-oidc-tester/-/issues

I will try to add additional functionalities in this tool in particular

• OAuth2 only
• Implicit flow
• Control the login_hint (already used but not controllable)
• PKCE authentication
• Control the prompt
• Control the nonce
• … tell me what else you need