External SSO

Introduction

The Enterprise licensed Greycat facilitates Single Sign-On (SSO) by integrating an OpenID Connect client. This solution ensures Greycat’s compatibility with any SSO provider implementing the OpenID Connect protocol. This feature streamlines the integration of GreyCat services into clients’ existing ecosystems. They can seamlessly utilize their unique SSO service to manage employee access to Greycat services. Below is a diagram that illustrates the complete authentication flow of GreyCat when using an external SSO provider:

authentication flow

Open ID connect is a protocol based on Oauth2 requiring an ID_Token as the proof of authentication. Note that for some SSO providers, returning ID_Token is optional. Ensure this option is activated in your configuration when using such a provider, such as Azure Entra. Additionally, GreyCat utilizes the implicit flow among all possible flows of Open ID Connect protocol. Ensure the SSO provider is configured to support this flow.

After authentication, Greycat maintains a Greycat session-id based server-side session to keep connections alive since the SSO’s JWT ID Token is not typically meant to be used to maintain sessions (although it could be). Greycat’S session expires regularly and the frontend of Greycat will thus communicate with the SSO provider to verify if a user is still connected. If so, the provider will reply the latest ID_Token and the Greycat session will be renewed on the server-side.

The greycat session’s default lifetime is short (one day - 86400 seconds) in order to refresh a user’s latest personal information through the updated latest ID_Token’s Claims, for example, the user’s role. Be aware that if the user’s information is updated on the SSO provider’s server, this modification won’t be synchronized to GreyCat until the user’s gey cat session expires, unless the user disconnects-reconnects from Greycat manually.

Important feature

Role mapping

GreyCat relies on a Role Based Access Control (RBAC) to enforce fine-grain security controls. Each role is often granted a collection of permissions. You can customize the role definitions and the permissions granted to the on GreyCat through the file that locates at [GreyCat_Project_Root]/gcdata/security/user_policy.json. Meanwhile, GreyCat provides some standard default roles for out-of-the-box usage.

One user can only be linked to a single role, and you can easily map these Greycat user roles to the roles previously or future defined on your SSO provider’s side. This operation should be done on the configuration page of your SSO provider.

After modifying the role mapping/assignment configurations on one user’s SSO provider’s side, this user needs to disconnect and reconnect to GreyCat in order to synchronize the role mappings immediately. Here’s where you find role mapping/assignment configuration on Azure Entra:

Role mapping

Configurations

Where to configure?

You can pass SSO related configurations to GreyCat either by command-line arguments at launch or by environment variables.

--oid_client_id=<str> OpenID Client ID to use for connection
--oid_config_url=<str> url to retrieve the OpenID configuration object

GREYCAT_OID_CLIENT_ID=<str> OpenID Client ID to use for connection
GREYCAT_OID_CONFIG_URL=<str> url to retrieve the OpenID configuration object

What to configure?

On GreyCat’s side

The configurations might vary slightly for each SSO service provider, but you always need to define at least these minimum configurations for Greycat to support OpenID authentication:

Depending on the SSO provider, you might need to configure a OpenID public key which is used to validate the ID token’s signature. For example, this is necessary for KeyCloak but not for Azure. For Azure, this public key is dynamically updated after certain period and it is exposed to the application (in our case, GreyCat) through the Config_URL.

On SSO provider’s side

SSO provider’s Critical settings:

activate_id_token_azure

minimum_claims

FAQs

Quick Start - Using Keycloak as SSO service provider to protect GreyCat access

[Back to the beginning]

Step 1 - Launch Keycloak service

If a keycloak service is already available to you, you can skip to Step 2.2. If it’s not the case, here we propose to launch an instance of Keycloak using Docker which is the most simple solution for demo purpose.

Step 1.1 - Install Docker

According to the official documentation, “Docker is an open platform for developing, shipping, and running applications. Docker enables you to separate your applications from your infrastructure so you can deliver software quickly”. If you’re unfamiliar with Docker’s basic concepts, refer to this link: https://docs.docker.com/get-started/overview/

If you do not have Docker installed on your machine yet, you should proceed the installation first according to your platform:

Step 1.2 Starting a Keycloak instance with Docker

Use the command below to start a Keycloak instance on port 5000 with default username = admin and password=admin (for testing purposes). For this step, Docker will fetch the image of Keycloak automatically if it doesn’t exist on your local machine so you do not need to download the image manually.

docker run -p 5000:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:23.0.7 start-dev

Then you will see an output similar to this:

$ docker run -p 5000:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:23.0.7 start-dev
Updating the configuration and installing your custom providers, if any. Please wait.
2024-03-01 13:44:25,910 INFO  [io.quarkus.deployment.QuarkusAugmentor] (main) Quarkus augmentation completed in 5220ms
...
...
...
2024-03-01 13:44:38,423 INFO  [org.keycloak.services] (main) KC-SERVICES0009: Added user 'admin' to realm 'master'
2024-03-01 13:44:38,426 WARN  [org.keycloak.quarkus.runtime.KeycloakMain] (main) Running the server in development mode. DO NOT use this configuration in production.

Step 2- Configure the Keycloak service

Step 2.1- Create realm

Assuming you launched keycloak using the previous Docker command, navigate to http://localhost:5000/admin/master/console/ and use the default user name/password combinationadmin and admin to connect to the administration console. By default, you have the master realm displayed and we will create a new Realm named “Datathings” from the dropdown button in the top left corner.

create realm

The essential configuration is straightforward. Simply provide the desired name for the realm.

creating realm

2.2 - Create client

In DataThings Realm, create a Client to register our GreyCat application. Navigate to Clients on the left panel and click on Create client button.

create client

General settings

For this example, we name this client DemoGreyCat. For general settings, just make sure you are using OpenID Connect as connection type.

client general settings

Capability configuration

Set the following configurations under Capability configuration:

client capability setting

Login settings

We set, in Login settings:

client login settings

Client configuration (Exported JSON)

After the creation, if you want, you can export the settings by clicking the 3 vertical points button on the right end of your Client.

export client

The exported json format fie that you have should contain this configuration:

{
  "clientId": "DemoGreyCat",
  "name": "Demo GreyCat",
  "description": "A sample application using GreyCat",
  "rootUrl": "",
  "adminUrl": "http://localhost:8080",
  "baseUrl": "",
  "surrogateAuthRequired": false,
  "enabled": true,
  "alwaysDisplayInConsole": false,
  "clientAuthenticatorType": "client-secret",
  "secret": "JwgJmCditznz65QFb26k1jnc9SGuJnIy",
  "redirectUris": [
    "*"
  ],
  "webOrigins": [
    "*"
  ],
  "notBefore": 0,
  "bearerOnly": false,
  "consentRequired": false,
  "implicitFlowEnabled": true,
  "directAccessGrantsEnabled": true,
  "serviceAccountsEnabled": false,
  "publicClient": false,
  "frontchannelLogout": true,
  "protocol": "openid-connect",
  "attributes": {
    "oidc.ciba.grant.enabled": "false",
    "client.secret.creation.time": "1710246459",
    "backchannel.logout.session.required": "true",
    "post.logout.redirect.uris": "*",
    "oauth2.device.authorization.grant.enabled": "false",
    "display.on.consent.screen": "false",
    "backchannel.logout.revoke.offline.tokens": "false"
  },
  "authenticationFlowBindingOverrides": {},
  "fullScopeAllowed": true,
  "nodeReRegistrationTimeout": -1,
  "defaultClientScopes": [
    "web-origins",
    "acr",
    "profile",
    "roles",
    "email",
    "role_for_idtoken"
  ],
  "optionalClientScopes": [
    "address",
    "phone",
    "offline_access",
    "microprofile-jwt"
  ],
  "access": {
    "view": true,
    "configure": true,
    "manage": true
  }
}

This section is essential to grant the access to GreyCat through SSO service. If none compatible role is assigned to the user of if the role is not mentioned in the ID Token, you will get an error code of 403 Forbidden.

Step 3.1 - Role definition

Since GreyCat relies on Role-Based Access Control (RBAC) for security, you’ll need to define server-side roles within GreyCat and associate permissions with them. While this definition happens within GreyCat, you should also define and assign Keycloak roles to users. This ensures user linkage to corresponding GreyCat roles. Essentially, each Keycloak role name should match a GreyCat role name for proper mapping. For example, by default, Greycat generates a set of roles in [GreyCat_Project_Root]/gcdata/security/user_policy.json including admin. To map this GreyCat role to an Keycloak role, create a Keycloak role named ‘admin’. The role definition could be accomplished in two levels. In either of the two levels, only the name of role matters:

Define Realm roles

Realm roles are by default visible to all the clients within the realm. To define realm level roles, you just need to navigate ro Realm roles from the left panel.

realm role

Define Client roles

Client roles are by default only visible to the current client. But you can also reference another client’s roles by specifying the client. To define client level roles, navigate to Clients from the left panel, select your client and click on roles from the top.

client role

Step 3.2 - Role assignment

Create a user

We need to create a user on Keycloak so that we can assign a role to the user. We create users by navigating to Users from the left panel. Be careful, GreyCat uses the email value to distinguish users, make sure this email filed is filled:

Jane Doe

Define credentials

Once you have created a user, you need to define a credential for the user. From the top navigate bar, navigate to Credentials and define a password.

Jane Doe

Define role mapping

Eventually, we can assign roles to this user. We navigate to Role mapping using the top navigate bar. In the popped out panel, in its top left panel, we can select if we wanna assign a Realm Role or a Client Role. Here, we will use the Client Role named admin that we previously defined.

role assignment

Step 4 - Include roles in ID Token

For Keycloak, defining and assigning the roles are still not enough. By default, the information related to roles is not included in the ID Token. As previously mentioned, this will lead to a 403 Forbidden error.

To add this information in the ID Token, you have to edit the Client scope entry specific to the client. Here are the steps you have to take:

client scopes

Once you are at the Client Scopes editing page, you have to configure a new mapper. We previously defined a Client role or a Realm role, we want this mapper to inject this role value to the ID Token. When creating the mapper, we can choose the information to map, we select the User client role option that represents Client role. If you only defined a Realm Role, you should select User realm role.

mapper info

For the configurations related to this mapper, there are several options that are very important:

mapper detail

Step 5 - Configuration for GreyCat

The configurations on GreyCat can be proceeded either through command-line arguments or a .env file at your GreyCat application’s root.

Retrieve the values

Either way, you need three information:

Apply the values

To check how to pass the configurations using command line arguments, you can always run greycat serve -h.

To pass the values by environment variables using a .env file, just create the file named exactly ".env" at the root directory of your GreyCat project and set the values that we just found:

GREYCAT_OID_CONFIG_URL=http://{$KEYCLOAK_HOST_ADDRESS}/realms/{$REALM_ID}/.well-known/openid-configuration
GREYCAT_OID_CLIENT_ID={$CLIENT_ID}
GREYCAT_OID_PUBLIC_KEY={$THE_PUBLIC_KEY_VALUE}

Quick Start - Using Azure Entra as SSO service provider to protect GreyCat access

[Back to the beginning]

Step 1 - Application registration

Step 1.1 - The entry for registration

Using your organization account to login to MS Azure Entra, you will see the home page of Microsoft Entra admin center. If you don’t have an existing instance of the Entra application running, you’ll need to proceed with registration. To do this, from the left side menu, go to Applications -> App registrations. On the top left corner of your work zone, click the button “New registration”.

registration entry

Step 1.2 - Registration

To register an Entra application, you have to provide the following information:

registration panel

Once you submit your registration request, you should see this page below that shows you the information you need to configure your GreyCat deployment.

registration complete

Step 2 - Authentication configuration

Regarding the basic configurations, assuming you followed all the previous steps precisely, you only have to check one last option to complete the settings. In your work zone, navigate toManage -> Authentication. Within the session of implicit grant and hybrid flows, check the ID tokens option. This token is essential for GreyCat’s SSO functionality based on the OpenID Connect protocol.

authentication config

Step 3 - Token configuration

When using a third-party SSO service for authentication, GreyCat manages its own user sessions on the server-side. To enable this, it requires additional information in the claims of the ID Token issued by the SSO service provider. To make this work, it needs extra information in the claims of the ID Token issued by the SSO service provider. Essentially, you have to include either preferred_username or email in the claims of the token. In the case of Azure Entra application, you can include both. We recommend you to always include at least email since this information is always present for a Microsoft account. To configure this, navigate to Manage -> Token configuration. Click on the Add optional claim button in the top left corner of the work zone. When adding email into the claim, Azure might remind you to grant additional permissions because Microsoft Graph manages users’ personal information. Each piece of information needs explicit exposure to your Entra application for visibility.

token_config

If you wanna check the permissions granted to your Entra application, you can navigate to Manage -> API permissions.

api_permissions

This section is essential to grant the access to GreyCat through SSO service. If none compatible role is assigned to the user of if the role is not mentioned in the ID Token, you will get an error code of 403 Forbidden.

Step 3.1 - Define roles

Since GreyCat relies on Role-Based Access Control (RBAC) for security, you’ll need to define server-side roles within GreyCat and associate permissions with them. While this definition happens within GreyCat, you should also define and assign Entra App roles to Microsoft users in Azure Entra. This ensures user linkage to corresponding GreyCat roles. Essentially, each Entra role value should match a GreyCat role name for proper mapping. For example, by default, Greycat generates a set of roles in [GreyCat_Project_Root]/gcdata/security/user_policy.json including admin. To map this GreyCat role to an Entra App role, create an Entra App role with the value ‘admin’. To do this, navigate to Manage -> APP roles and click on the button of Create app role on the top left of work zone.

role config

Step 3.2 - Assign roles

Once you have defined App roles which are automatically mapped to the GreyCat roles by value, you can assign these roles to the users of specific users. To do this, you have to access the setting from the most left side menu by navigating to Applications -> Enterprise applications -> YOUR_ENTRA_APPLICATION. Then, using the left navigation panel of your application, navigate to Manage -> Users and groups. Use the Add user/group button to add users and assign roles directly. You can also edit existing user assignments with the Edit assignment button. Remember, only one unique role can be assigned to each GreyCat user.

assign role

GreyCat configuration

Find the values

To configure GreyCat to use your newly created MS Azure Entra application, you need two pieces of information, which can be provided either through command-line arguments or a .env file at your GreyCat application’s root.

key information

Use the values for configuration

To check how to pass the configurations using command line arguments, you can always run greycat serve -h.

To pass the values by environment variables using a .env file, just create the file named exactly ".env" at the root directory of your GreyCat project and set the two values that we just found:

GREYCAT_OID_CLIENT_ID={$YOUR_APPLICATION_ID (Client ID)}
GREYCAT_OID_CONFIG_URL=https://login.microsoftonline.com/{$YOUR_TENANT_ID}/v2.0/.well-known/openid-configuration

Quick Start - Using Google as SSO service provider to protect GreyCat access

Back to the beginning

Step 1 - Create a project

We suppose that you already have a Google Cloud account and you have completed all the basic account configurations. Before using Google’s OAuth 2.0 authentication system as SSO service, you must set up a project in the Google API and services console. As illustrated in the screenshot, on the top right, we can click on the CREATE PROJECT button.

Create project

Once you click the button, you will see the page that allows you to name your project and attach it to an organization. You can name the project as you want, just keep in mind that the project cannot be renamed afterwards. Regarding the organization, you do not have to provide one; in this demo, we would leave it as it is.

project creation

Step 2 - Create a credential

Once we have our project created, we will navigate to the Credentials panel using the left-side menu. Then, we click on the Create credentials button and select OAuth client ID in the drop-down menu.

try create credential

If you followed the exact instructions, you will find out that it doesn’t work. But please do not curse yet; it is an expected failure. It just wants us to configure the consent screen. To do so, we just need to click on the Configure consent screen on the right side.

Force customize consent screen

Once you click the button, you will be redirected to the OAuth consent page configuration. The configuration process needs us to specify our target users, it could be either internal users of the organization that we previously defined or external users, which means any Google Account holder. Since we didn’t attach this application to any organization, we will select external and click on Create.

users

Now, we are going to customize the content to be displayed on the consent page. For this step, you can fill the blanks as you want. Just make sure that you meet the minimal demand. Click Save and continue when you are ready.

consent page

This following step is essential and important for the SSO service to work with GreyCat. Here, we are going to define the scopes to be included in the SSO response. As explained earlier in this documentation, GreyCat adopts the Implicit flow of OIDC protocol which needs the ID_Token during the authentication. Also, GreyCat relies on the user’s email to distinguish users; make sure this scope is also included in the responses of the SSO service. To add these two scopes, click on Add or remove scopes. Then, on the right side of your screen, in the popped-out panel, check at least .../auth/userinfo.email and openid, then click update.

edit scopes

Afterwards, you should see a result similar to this:

scopes

This next step allows us to add Test users. Basically, you can add from zero to one hundred users, but for test purposes, you might want to add at least yourself as a test user. To do so, click Add users, and again, type your Gmail address in the popped-out panel then click Add.

test users

As demonstrated in the following image, all users will be displayed in the list once they are added. To keep all your modifications and move on, click on Save and continue.

added test users

Now you should see the summary page similar to what’s illustrated in this image below. If everything’s fine, just click on Back to dashboard and the configuration for the consent page is completed.

summary

Step 2.2 - Create credentials

Having the consent page well configured, again, we will navigate to the Credentials panel using the left-side menu. Then, we click on the Create credentials button and select OAuth client ID in the drop-down menu to eventually create the credentials.

restart credential creation

Now we need to select the type of application that uses this Google OAuth service. In the case of GreyCat, we need to select Web application.

pick application type

Then, in this following step, you will define more information related to this OAuth service. Of course, you can name the application as you want, just make sure the other fields are carefully filled before you click the Create button:

origins

Now, you should have your OAuth service ready to be used. In the popped-out panel, you can see the key information related to your OAuth service. Copy and save the Client ID in a notebook since we will use it immediately.

summary

Step 3 Greycat configurations

To check how to pass the configurations using command-line arguments, you can always run greycat serve -h.

To pass the values by environment variables using a .env file, just create the file named exactly ".env" at the root directory of your GreyCat project and set the two values as shown below:

GREYCAT_OID_CLIENT_ID=Google_OAuth_Client_ID
GREYCAT_OID_CONFIG_URL=https://accounts.google.com/.well-known/openid-configuration

The value of Google_OAuth_Client_ID is the one that we asked you to save in a notebook earlier. If ever you lost it, go back to Google API and services console, navigate to the Credentials panel using the left side menu. Try to find the OAuth application that you just created and copy its Client ID.

Client ID

Once you created and saved the .env file, you are ready to use the Google SSO service in your GreyCat application. Launch GreyCat by running greycat serve from the root directory of your GreyCat application, then open your browser and go to the host address of your GreyCat application. By default, the address is http://localhost:8080. If everything goes well, you will see a page like this image below.

login page

If you saw such a screen, basically, your configuration “works”. But still, you will find out your application falls into an infinite authentication loop which is “normal”. Check the FAQs session to fix it.

GO to FAQs