OpenID Connect (OIDC) connector

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.

The following diagram illustrates the Open ID Connect flow between InWebo and the Service Provider.

OIDC terminology

The OpenID Connect specification uses specific terms (See OpenID Connect terminology). The main terms used for the roles in the authentication flows are:

• The “OpenID provider” is the authorization server that issues the ID token. It is more commonly known as the Identity Provider (IdP). In this case inWebo is the Identity Provider.

• The "ID token" is issued by the Identity Provider and contains information about the end user in the form of claims. End user information is encoded in a secure JSON Web Token (JWT),called ID Token.

• A "claim" is a piece of information about the end user (user name for example).

• The "end user" — Whose information is contained in the ID token.

• The "relying party" is the client application that requests the ID token from inWebo. It is more commonly known as Service Provider (SP).

User authentication flow

User authentication can be initiated in two ways: from the Service Provider (SP-initiated authentication) or from the IdP (IdP-initiated authentication). There is no configuration required for this parameter. The authentication flow used depends on whether or not the SP exchanges the login with the IdP.

• SP-initiated: the SP transmits the login to the IDP. InWebo identifies the end-user and asks for a PIN.

• IdP-initiated: in some cases, SP does not transmit the login to inWebo in the payload. The authentication flow is initiated by the IdP inWebo, rather than the Service Provider. inWebo authentication page asks end-user for the login and for the PIN.

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 :

• 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

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:

• you should install and configure Apache Guacamole,

• you should install OpenID Connect authentication extension for 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.

Step 1: Creating the OIDC 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 (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.

Step 2: Configuring Guacamole properties file

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:

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}

JSON

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:

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

JSON

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:

<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

<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.