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. Only the Implicit flow (OIDC core v1) is currently supported

The following diagram illustrates the Open ID Connect flow between TrustBuilder 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 TrustBuilder 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 TrustBuilder. It is more commonly known as Service Provider (SP).

• The “Implicit Flow” is the only authentication flow currently supported (more information)

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. TrustBuilder identifies the end-user and asks for a PIN.

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

Creating a “Open ID connect” connector

• Connect as an administrator to the TrustBuilder MFA 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
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.
Validity 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	Select the default authentication method to use on the authentication page served by TrustBuilder: https://ult-inwebo.com/authentication-oidc/va → The first authentication option presented to users will be a page embedding Virtual Authenticator (VA). https://ult-inwebo.com/authentication-oidc/helium → The first authentication option presented to users will be a page embedding Helium. https://ult-inwebo.com/authentication-oidc/neon → The first authentication option presented to users will be a page embedding mAccess Web. https://ult-inwebo.com/authentication-oidc/authenticator → Push notifications with Authenticator app will be presented to users as an authentication method. https://ult-inwebo.com/authentication-oidc/authenticator-with-qrcode → QR code authentication with Authenticator app will be presented to users as an authentication method More information about QR code authentication method Other page… → You can use a custom page To protect users from attacks such as Push Bombing, we recommend selecting the QR code authentication. The QR code authentication method does not use push notifications, therefore it does not enable a push bombing scenario. More information about protecting users from Push Bombing attacks
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 TrustBuilder 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 TrustBuilder MFA 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 TrustBuilder MFA 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	Select the default authentication method to use on the authentication page served by TrustBuilder: https://ult-inwebo.com/authentication-oidc/va → The first authentication option presented to users will be a page embedding Virtual Authenticator (VA). https://ult-inwebo.com/authentication-oidc/helium → The first authentication option presented to users will be a page embedding Helium. https://ult-inwebo.com/authentication-oidc/neon → The first authentication option presented to users will be a page embedding mAccess Web. https://ult-inwebo.com/authentication-oidc/authenticator → Push notifications with Authenticator app will be presented to users as an authentication method. https://ult-inwebo.com/authentication-oidc/authenticator-with-qrcode → QR code authentication with Authenticator app will be presented to users as an authentication method More information about QR code authentication method Other page… → You can use a custom page To protect users from attacks such as Push Bombing, we recommend selecting the QR code authentication. The QR code authentication method does not use push notifications, therefore it does not enable a push bombing scenario. More information about protecting users from Push Bombing attacks
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:

JSON

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:

JSON

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

Testing the OIDC connection to TrustBuilder

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

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 TrustBuilder MFA authentication page of the connector.

Example of TrustBuilder MFA authentication page before activation:

Example of TrustBuilder MFA 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 (TrustBuilder), a creation date, an expiration date and a nonce.