Getting started with OIDC connector

Introduction

OpenID Connect (OIDC) is an identity layer built on top of the OAuth 2.0 protocol and supported by some OAuth 2.0 providers, such as Google and Azure Active Directory. It defines a sign-in flow that enables a client application to authenticate a user, and to obtain information (or "claims") about that user, such as the user name, email, and so on. User identity information is encoded in a secure JSON Web Token (JWT), called ID token.

Creating a “Open ID connect” connector

  • Connect as an administrator to the inWebo administration console.

  • Go to the “Secure Sites” section.

  • Choose to add a connector of type “Open ID connect”.

  • Configure the connector settings :

OIDC connector settings

OIDC connector settings

Setting

Description

Connector name

A chosen name / information to define the connector's goal in the administration console.

Client ID

Unique client name that will be used during transactions.

Login Type

Indicates whether the login used during the connection should be retrieved in the login field, the email field or the login 2 field.

Client Secret

Not used for now.

Validy period of the token (optional)

The maximum amount of time that the token should remain valid, in seconds. This field should remain empty (the default is 1 year). If you want to custom the validity period of the token, you should refer to the application using the connector (see “Configuring OIDC connector”).

Default Authentication URL

Indicates the chosen authentication page (with VA, Helium, mAccess Web or Authenticator App).

Scopes (optional)

Determines the claims (or information) returned within the OpenID token. By default “openid" is used. If you want to add claims, such as “profile" or/and “email", you should refer to the application using the connector (see “Configuring OIDC connector”).

  • Click on Add to create the connector.

The connector creation automatically generates a connector alias, a Discovery URL and a secure site alias. These elements are displayed on the top of the connector properties.

The associated secure site is automatically generated.

Discovery URL

OpenID Connect defines a discovery mechanism, called OpenID Connect Discovery, where an OpenID server publishes its metadata at a well-known URL, typically “https://server.com/.well-known/openid-configuration

The URL returns a .JSON listing of the OpenID/OAuth endpoints, supported scopes and claims, public keys used to sign the tokens, and other details. The clients can use this information to construct a request to the OpenID server. The field names and values are defined in the OpenID Connect Discovery Specification.

The Discovery URL provided by inWebo is unique to a connector. It can be retrieve in connector properties:

To have a preview of this JSON file content, paste the Discovery URL in a browser. Here is an example: https://connect.myinwebo.com/168d150b-c1e4-459d-b1ca-e142a8150861/.well-known/openid-configuration

{"issuer":"https://connect.myinwebo.com/168d150b-c1e4-459d-b1ca-e142a8150861/",
"authorization_endpoint":"https://connect.myinwebo.com/168d150b-c1e4-459d-b1ca-e142a8150861/authorize",
"jwks_uri":"https://connect.myinwebo.com/168d150b-c1e4-459d-b1ca-e142a8150861/jwks",
"scopes_supported":["openid"],
"response_types_supported":["id_token token","id_token","code"],
"subject_types_supported":["public"],
"id_token_signing_alg_values_supported":["RS256"],
"response_modes_supported":["form_post","query","fragment"],
"grant_types_supported":["authorization_code","implicit"],
"claim_types_supported":["normal"],
"claims_supported":["iss","iat","exp","aud","sub","jti","at_hash","iw-actor-type","iw-groups-and-roles","nonce"],
"claims_parameter_supported":false,
"ui_locales_supported":["en-US"],
"userinfo_endpoint":"https://connect.myinwebo.com/168d150b-c1e4-459d-b1ca-e142a8150861/userinfo",
"token_endpoint":"https://connect.myinwebo.com/168d150b-c1e4-459d-b1ca-e142a8150861/token"}

Configuring OIDC connector

You can configure the OIDC connector using an application. Below is a possible example of the OIDC connector configuration using Apache Guacamole.

Apache Guacamole (or Guacamole) is a HTML5 web application that provides access to desktop environments using remote desktop protocols (such as VNC, RDP and SSH).

Note that Apache Guacamole is just one of many examples of how to configure the OIDC connector.

Prerequisites

Before you start configuring OpenID connector using Guacamole:

Procedure

To configure Open ID connect using Guacamole, you should set the same parameters in both the connector properties (in the inWebo administration console) and in the guacamole properties (in the Guacamole configuration file). Read the following instructions to see how to proceed.

  • Connect as an administrator to the inWebo administration console.

  • Go to the “Secure Sites” section.

  • Choose to add a connector of type “Open ID connect”.

  • Configure the connector settings :

OIDC connector settings

(for Apache Guacamole use case)

OIDC connector settings

(for Apache Guacamole use case)

Setting

Description

Connector name

A chosen name / information to define this connector's goal in the administration console.

Client ID

Unique client name that will be used during transactions.

Login Type

Indicates whether the login used during the connection should be retrieved in the login field, the email field or the login 2 field.

Client Secret

Not used for now.

Validy period of the token (optional)

The maximum amount of time that the token should remain valid, in seconds.

By default, the validity period of the token used in Guacamole is 300 seconds. To be compliant with Guacamole properties, set this parameter to 300.

If you set a different value, you should also edit the guacamole configuration file: set openid-max-token-validity with the same value in second.

Default Authentication URL

Indicates the chosen authentication page (with VA, Helium, mAccess Web or Authenticator App).

Scopes (optional)

Determines the claims (or information) returned within the OpenID token.

By default, the scope used in Guacamole properties file is “openid email profile". To be compliant with Guacamole properties, check the “email” and “profile” boxes.

If you set an other configuration, you should also edit the guacamole configuration file. For example: if you check only “profile” case in connector properties, you should set the scope to “openid profile" in the guacamole configuration file.

  • Click on Add to create the connector.

The connector creation automatically generates a connector alias, a Discovery URL and a secure site alias. These elements are displayed on the top of the connector properties.

The associated secure site is automatically generated.

 

Once the OIDC connector is created, you should configure properties in “guacamole.properties” file which is Guacamole's main configuration file.

These properties are absolutely required as they dictate how Guacamole should connect to the identity provider, how it should verify the identity provider's response, and how the identity provider should redirect users back to Guacamole once their identity has been confirmed.

Here are the required properties:

1 2 3 4 5 openid-authorization-endpoint=https://connect.myinwebo.com/YOUR_CONNECTOR_ALIAS/authorize openid-jwks-endpoint=https://connect.myinwebo.com/YOUR_CONNECTOR_ALIAS/jwks openid-issuer=https://connect.myinwebo.com/YOUR_CONNECTOR_ALIAS/ openid-client-id={YOUR_CLIENT_ID} openid-redirect-uri={YOUR_GUACAMOLE_CLIENT_URL}

These properties values can be retrieved in the Discovery URL (see “Discovery URL” section above).

Complete the openid-scope and the openid-max-token-validity with the same values set in connector properties.

For example: in the connector properties, you have set the “validity period of the token” to 400 seconds and “scopes” to Email.

Then you should configure guacamole.properties file like this:

1 2 openid-scope=400 openid-max-token-validity=openid email

 

Testing the OIDC connection to inWebo

To test the OIDC connector the most important entry is the authorization_endpoint. You can retrieve the authorization_endpoint value in the JSON file returned by the Dicsovery URL (see “Discovery URL” section above).

You can set up a simple HTML form posting to the authorization_endpoint URL to initiate the authentication dialog with inWebo.

Example of form:

1 2 3 4 5 6 7 8 9 10 11 12 <form method="post" name="logon" id="form" action="https://connect.myinwebo.com/168d150b-c1e4-459d-b1ca-e142a8150861/authorize"> <input name="login_hint" value="login"> <input name="iw_activation_code" placeholder="activation code"> <input type="hidden" name="redirect_uri" value="result.html"> <input type="hidden" name="client_id" value="MyOIDC"> <input type="hidden" name="response_type" value="id_token"> <input type="hidden" name="response_mode" value="query"> <input type="hidden" name="scope" value="openid"> <input type="hidden" name="nonce" value="asdorj5"> <input type="submit" value="Connect" /> </form>

After posting the form you should be redirected to the inWebo authentication page of the connector.

Example of inWebo authentication page before activation:

Exemple of inWebo connection page after activation of Virtual Authenticator:

When the authentication is successful the user is redirected to a page which is specified in the field redirect_uri of the above sample form.

Here is a sample page to retrieve the result of an OIDC authentication

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 <html> <head> <script> function getUrlVars() { var vars = {}; var parts = window.location.href.replace(/[#?&]+([^=&]+)=([^&]*)/gi, function(m,key,value) { ; return vars; } document.addEventListener('DOMContentLoaded', (event) => { console.log("Dom loaded !"); setTimeout(getUrlVars(),500); }) </script> </head> <body> Authentication successful </body> </html>

You just have to open the JavaScript console and see the result of the authentication under the form of a id_token encoded and encrypted

eyJraWQiOiJBRFJrQ1VrWXVibHJoUTVYeEFUYUhNT25LclNnRHVHWVRvUExUbHdoSE40IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJib2IiLCJhdWQiOiJNeU9JREMiLCJpc3MiOiJodHRwczpcL1wvY29ubmVjdC5teWlud2Viby5jb21cLzE2OGQxNTBiLWMxZTQtNDU5ZC1iMWNhLWUxNDJhODE1MDg2MVwvIiwiZXhwIjoxNzEzMTkwMDU4LCJpYXQiOjE2MTg1ODIwNTgsIm5vbmNlIjoiYXNkb3JqNSJ9.JcnBuWBiU8zgOVWb4OPSlwapcGgJJcoTjwX2kJZsCR3ZM2XVsUwnamrYhEOXP_lsmLytSmk5BesIsv6VZl1RYXkLYQu4IRDxE2bRByfZ5F8MW_OdEYobpa47BXRaveDPHTWZQnkOpxROYgtGRIHHByz1DAak-PWKx5FA_7WH11g4eD5_7FDkZyGqfswFjdVOsnfPDZw9ICkP2QQnVyS8-kcuxUewLZI1YgjUF9abmrm2Rb8Pp2FBcmIsoFP9LeFGBNB7OisM1TieKtmSuU7C2cozSWeTZ0g8rrtIVYVlt2jWgjRmfpXJXF3PZi1QsqAjOkHF0mZAkN6giE52d6gRpw

You can decode this id token on https://jwt.io/.

Let's see the payload returned once the id_token is decoded:

{
"sub": "bob",
"aud": "MyOIDC",
"iss": "https://connect.myinwebo.com/168d150b-c1e4-459d-b1ca-e142a8150861/",
"exp": 1713190058,
"iat": 1618582058,
"nonce": "asdorj5"
}

Information returned are the user authenticated, the Client ID, the issuer URL (inWebo), a creation date, an expiration date and a nonce.