Using SSO With Retool (OpenID Connect)

This document outlines the process to configure Descope SSO Authentication with Retool. This configuration will help you securely access your Retool apps and protect your resources and APIs.

This guide will show you how to configure SSO with the Cloud and Self-Hosted versions of Retool.

Retool supports both OIDC and SAML SSO, however because of the additional features OIDC allots (such as being able to use information from ID tokens in your Retool apps), it is the preferred method of SSO with Descope. If you've already configured SAML, but would like to switch to using OIDC, you can follow the guide here.

Note: Custom Authentication only works with Enterprise level subscriptions to Retool. Make sure you have the right type of Retool account before continuing with this guide.

Table of Contents

• Retool OIDC Configuration
  • Protecting Retool Apps and Workflows
  • Protecting APIs
• Role Mapping
• Referencing JWT claims

Retool OIDC Configuration

You'll need the following items to configure integrate Descope with OIDC:

• Client ID: Your Descope Project ID, which can be found under Project Settings in the Descope Console
• Client Secret: Access key generated under Access Keys in the Descope Console
• Scopes: The scopes that are defined for authorization of Descope resources, such as - openid email profile
• Authorization URL: https://api.descope.com/oauth2/v1/authorize
• Token URL: https://api.descope.com/oauth2/v1/token

Protecting Retool Applications and Workflows

For Cloud-Hosted versions of Retool - use the Retool SSO Settings page in your Retool dashboard to configure SSO.

For Self-Hosted versions of Retool - create environment variables to configure SSO.

NOTE: If self-hosting, make sure that the BASE_DOMAIN environment variable is set as well. This will ensure links using your domain (e.g. new user invitations and forgotten password resets) are correct.

This image is an example of the setup procedure in a cloud-hosted deployment of Retool:

If you wish to use role-based authorization with Retool, you can map the corresponding roles defined in Descope, with roles you've already defined in Retool. You can read about this in the Role Mapping section below.

Finally, you can consider enabling a few of the other options you see at the bottom of the configuration page, such as JIT - Just in Time Provisioning.

Once you've configured SSO, hit Save in the top right corner, and the next time you login with Retool you should see your login page look like this:

Now you can use authentication methods not supported by Retool, such as Passkeys, and also Descope as an IdP for handling all of your user identities.

Protecting APIs

Whether you're using Self-Hosted or Cloud-Hosted Retool, the process for building a Custom Auth workflow to authenticate with protected APIs is the same and fairly straightforward.

The steps below will show you how to create a Resource and utilize Descope JWTs for authentication:

1. Visit the Retool Resources page in your dashboard, and create a new resource in the top right corner
2. Select REST API from the list, and then select Custom Auth underneath Authentication
3. Click Add a new step to the auth workflow, and then fill in the necessary OIDC information listed above
4. Add another step to the auth flow, and then select Define a Variable

The access token that Descope will provide (which contains all of your custom claims), will be exported as {{oauth1.accessToken}}. In order to access it, to include in your HTTP header, you will need to define it as another variable like this:

5. Once you're variable has been defined, you can include the variable as an Authorization Bearer token in the HTTP header above:

Role Mapping

You can also map the roles returned from the OpenID response to your Retool permission groups. Any Retool groups that are not specified in the role mapping are overwritten.

The following example maps teacher and student roles to specific Retool permission groups.

Here is an example of how this is configured in both Retool and Descope:

NOTE: There are more detailed instructions you can read about in the Role Mapping section of the Retool documentation.

Once you've configured mapped the roles, you'll need to re-authenticate with OIDC or SAML in order to sync the group and user roles across Descope and Retool. Since the roles are mapped, you can use them to define specific permissions for each user role.

Referencing JWT claims

You can use custom claims included in the JWT to personalize Retool apps or control component permissions. Retool automatically includes these claims as the values of the {{current_user.metadata.accessToken}}.

You can access them using curly braces anywhere in your Retool app, such as: {{current_user.metadata.accessToken.picture}}

If you have any other questions about using Descope with Retool, feel reach to reach out to us!