Enabling users to log in to Retool with Auth0 credentials via OpenID Connect (OIDC) enhances security and streamlines the authentication process.
This integration offers several benefits, including improved user experience, centralized identity management, and a suite of robust security features that ensure the safety of user data. Understanding both Retool and Auth0 configurations is required to ensure a smooth and secure implementation.
By integrating Auth0 with Retool using OIDC, users can authenticate seamlessly using their Auth0 credentials. This integration leverages the OIDC protocol to facilitate secure and efficient authentication flows, ensuring that user identities are managed centrally and securely. This article will give you complete guidance on auth0 retool authentication.
Overview of Benefits and Requirements for Integration
Benefits:
Improved User Experience: Users can log in with their existing Auth0 credentials, reducing the need to remember multiple usernames and passwords.
Centralized Identity Management: Auth0 provides a centralized platform for managing user identities, making enforcing security policies and managing access easier.
Enhanced Security: OIDC and Auth0 offer robust security features, including multi-factor authentication (MFA), anomaly detection, and advanced threat protection.
Scalability: Auth0’s scalable infrastructure supports many authentication scenarios, making it suitable for small and large organizations.
Requirements:
Auth0 Account: A configured Auth0 account with the necessary applications and user database.
Retool Instance: Access to a Retool instance where you can configure authentication settings.
OIDC Configuration: Proper configuration of OIDC settings in both Auth0 and Retool, including client IDs, secrets, and redirect URIs.
SSL/TLS: Secure communication channels (SSL/TLS) between Retool and Auth0 to ensure that authentication data is transmitted securely.
By integrating Auth0 with Retool via OIDC, you can enhance the security and efficiency of your user authentication processes, providing a seamless and secure login experience for your users.
Requirements for Enabling Auth0 Login in Retool via OIDC
To enable users to log in to Retool with Auth0 credentials using OpenID Connect (OIDC), the following requirements must be met:
1. Admin Permissions on Retool Cloud or Permissions to Add Environment Variables on Self-Hosted Instances
Retool Cloud: Ensure you have admin permissions to access and configure the authentication settings in Retool Cloud.
Self-Hosted Instances: Have the necessary permissions to add and configure environment variables on your self-hosted Retool instance.
2. Necessary Permissions to Create an OIDC Application in Auth0
Auth0 Permissions: Obtain the required permissions to create and manage OIDC applications within your Auth0 account. This typically involves having admin or developer-level access to your Auth0 tenant.
3. Retool Enterprise Cloud or Self-Hosted Version
Version Requirement: Ensure you are using either Retool Enterprise Cloud or the self-hosted version of Retool, as these versions support custom OIDC integrations.
4. Resolved Domain with SSL/TLS Certificate
Domain Configuration: Configure and resolve a domain name for your Retool instance.
SSL/TLS Certificate: Ensure the domain has a valid SSL/TLS certificate to secure communication between Retool and Auth0.
5. Auth0 Developer Account
Auth0 Account: Create an Auth0 developer account if you still need to get one. This account will configure the OIDC application and manage user authentication.
Once you meet these requirements, you can proceed with configuring Retool and Auth0 to enable secure and seamless user authentication via OIDC.
Creating a New Auth0 Application
To enable users to log in to Retool with Auth0 credentials via OIDC, you need to create a new application in Auth0 and configure it correctly. Follow these steps to set up the Auth0 application:
1. Navigate to Auth0 Dashboard and Create a New Application
Steps:
Log in to your Auth0 account.
Navigate to the Auth0 Dashboard.
Click on "Applications" in the left-hand menu.
Click the "+ Create Application" button.
Enter a name for your application (e.g., "Retool OIDC Integration").
Select the application type as "Regular Web Application."
Click "Create".
2. Save Client ID, Client Secret, OAuth Authorization URL, OAuth Token URL
Steps:
After creating the application, you will be redirected to the application settings page.
Locate and save the following details:
Client ID: This is a unique identifier for your Auth0 application.
Client Secret: This is a secret key used for authentication. Keep this confidential.
OAuth Authorization URL: Typically in the format https://<your-domain>.auth0.com/authorize.
OAuth Token URL: Typically in the format https://<your-domain>.auth0.com/oauth/token.
3. Set Callback URL
Steps:
Scroll down to the "Allowed Callback URLs" on the application settings page.
Enter the callback URL in the following format
https://<subdomain>.retool.com/oauth2sso/callback
Replace <subdomain> with your specific subdomain used for Retool.
Example
4. Replace <subdomain> with Your Specific Subdomain
Steps:
Ensure that you have correctly replaced <subdomain> with the subdomain you use to access Retool.
This step is crucial for the authentication flow, which redirects users back to the correct Retool instance after successful authentication.
Following these steps, you can successfully create and configure a new Auth0 application to work with Retool via OIDC. This setup allows Retool to authenticate users using their Auth0 credentials securely.
Configuring SSO Settings in Retool
Once you have created and configured your Auth0 application, the next step is configuring the Single Sign-On (SSO) settings in Retool. This involves accessing the Retool settings UI and potentially adjusting environment variables.
1. Accessing the Settings UI for Streamlined Setup
Log In: Log in to your Retool instance with admin credentials.
Navigate to Settings: Click on your profile icon or the gear icon to open the settings menu.
SSO Configuration: Find the " Authentication " section or "SSO" within the settings menu.
Add New Provider: Click the option to add a new authentication provider and select "OIDC" or "OpenID Connect".
2. Environment Variables Might Pre-Populate, Allowing for Overrides or Acceptance of Defaults
Pre-Populated Fields: When you open the SSO configuration settings, you might see some fields pre-populated with values from environment variables. These typically include fields like Client ID, Client Secret, OAuth Authorization URL, and OAuth Token URL.
Override or Accept Defaults: Review the pre-populated values and decide whether to override or accept the defaults.
Override: If the pre-populated values are incorrect or must be changed, manually enter the correct values.
Accept Defaults: If the pre-populated values are correct, you can accept them and proceed with the configuration.
Fields to Configure:
Client ID: Enter the Client ID from your Auth0 application.
Client Secret: Enter the Client Secret from your Auth0 application.
OAuth Authorization URL: Enter the OAuth Authorization URL from your Auth0 application.
OAuth Token URL: Enter the OAuth Token URL from your Auth0 application.
Callback URL: Ensure the callback URL matches the one configured in Auth0 (e.g., https://<subdomain>.retool.com/oauth2sso/callback).
Example Configuration:
Client ID: <Your Auth0 Client ID>
Client Secret: <Your Auth0 Client Secret>
OAuth Authorization URL: https://<your-domain>.auth0.com/authorize
OAuth Token URL: https://<your-domain>.auth0.com/oauth/token
Callback URL: https://<subdomain>.retool.com/oauth2sso/callback
SSO Settings Page
Configuring the Single Sign-On (SSO) settings in Retool allows you to integrate with Auth0 for secure and streamlined user authentication via OpenID Connect (OIDC). Below are the specific settings you'll need to configure to enable SSO in Retool using Auth0 credentials.
Setting Details
Client ID
Description: The unique identifier for your Auth0 application.
Example: your-auth0-client-id
Client Secret
Description: The secret key associated with your Auth0 application. Ensure this is kept confidential.
Example: your-auth0-client-secret
Scopes
Description: The permissions that your application is requesting. These define the scope of access for the authenticated users.
Required Scopes: openid email profile offline_access
openid: Required for OIDC authentication.
email: Access to the user's email address.
profile: Access to the user's profile information.
offline_access: Allows the application to request refresh tokens.
Auth URL
Description: The URL where the authorization request is sent.
Token URL
Description: The URL used to exchange an authorization code for tokens.
Email Key
Description: The key used to extract the user's email address from the ID token.
Value: idToken.email
First Name Key
Description: The key used to extract the user's first name from the ID token.
Value: idToken.given_name
Last Name Key
Description: The key used to extract the user's last name from the ID token.
Value: idToken.family_name
Roles Key
Description: The key used to extract the user's roles from the ID token.
Value: idToken.groups
Role Mappings
Description: Maps roles from Auth0 to roles in Retool.
Mappings:
admin -> admin
user -> viewer
By configuring these details in the SSO settings page, you ensure that Retool can properly authenticate users using Auth0 and map their roles appropriately.
Optional Settings for SSO in Retool
In addition to the mandatory SSO settings, optional configurations can enhance the integration between Retool and Auth0, allowing for more granular control and access management.
1. Authorization to Access Resources When a User Logs in with SSO
Description: Ensure that users logging in through SSO have the necessary permissions to access specific resources within Retool. This involves setting up roles and permissions both in Auth0 and Retool to manage access effectively.
Action:
Define roles in Auth0 that correspond to the required permissions in Retool.
Map these roles to Retool roles to ensure users have the appropriate access levels.
Example:
Role mappings: admin -> admin, user -> viewer
2. Setting the API Audience Configured in Auth0
Description: The API audience specifies the intended recipient of the access token. This setting ensures that tokens issued by Auth0 are valid for the APIs your Retool application will access.
Action:
In Auth0, navigate to the API settings and note the audience value.
Configure this audience value in Retool to ensure tokens are validated correctly.
Example:
API Audience: https://your-api-audience/
3. Using CUSTOM_OAUTH2_SSO_AUDIENCE Environment Variable in the Retool Deployment
Description: This environment variable allows you to specify the API audience directly in your Retool deployment configuration, ensuring that Retool accepts the tokens issued by Auth0.
Action:
Add the CUSTOM_OAUTH2_SSO_AUDIENCE environment variable to your Retool deployment settings.
Set the value to the API audience configured in Auth0.
Example:
export CUSTOM_OAUTH2_SSO_AUDIENCE=https://your-api-audience/
By configuring these optional settings, you can enhance the integration between Retool and Auth0, providing more secure and controlled access to resources.
Ensure that users logging in with SSO have the appropriate permissions, set the API audience to validate access tokens, and use the CUSTOM_OAUTH2_SSO_AUDIENCE environment variable in your Retool deployment for seamless configuration.
Also Read: Understanding Retool Environment Variables
Implications if CUSTOM_OAUTH2_SSO_AUDIENCE is Not Configured
If the CUSTOM_OAUTH2_SSO_AUDIENCE environment variable is not configured in your Retool deployment, Retool may receive an opaque token from Auth0 instead of a JWT (JSON Web Token). This has significant implications for access control and security:
Opaque Token Limitations:
No User Information: Opaque tokens do not contain user information or claims, making it difficult for Retool to identify the authenticated user and their permissions.
Limited Access Control: Without the detailed claims provided by a JWT, Retool cannot enforce fine-grained access control based on user roles and permissions.
Debugging Challenges: Opaque tokens are harder to debug compared to JWTs, as they cannot be decoded to reveal their contents.
Best Practice:
Ensure the CUSTOM_OAUTH2_SSO_AUDIENCE environment variable is properly set to match the API audience configured in Auth0. This will ensure that Retool receives a JWT, which contains the necessary claims for access control and user identification.
Example:
export CUSTOM_OAUTH2_SSO_AUDIENCE=https://your-api-audience/
By configuring the CUSTOM_OAUTH2_SSO_AUDIENCE correctly, you ensure that Retool receives a JWT, enabling robust access control and secure user authentication.
Final Steps
1. Saving Your Settings
Ensure all your configurations in Retool are saved properly:
After entering all necessary details in the SSO settings page, click the "Save" button to apply the changes.
Double-check that all fields are correctly filled, especially the Client ID, Client Secret, Auth URL, Token URL, and optional settings like the API audience.
2. Testing Configuration by Logging In from an Incognito Window
Verify that the SSO integration is working correctly:
Open a new incognito window in your browser to ensure no cached data or existing sessions interfere with the test.
Navigate to your Retool login page and attempt to log in using Auth0 credentials.
Confirm that the login process was completed successfully and that you have the expected access within Retool.
3. Restarting Retool Instance if Environment Variables Were Added
If you added or modified environment variables, you need to restart your Retool instance to apply these changes:
For self-hosted Retool instances, restart the server or service hosting Retool.
Ensure the environment variables are correctly set and loaded during the startup process.
These are the final steps in finishing up your auth0 retool configuration successfully.
Conclusion
Configuring Auth0 integration and SSO in Retool using OIDC significantly enhances security and streamlines the authentication process. This setup improves user experience, centralizes identity management, and ensures robust security features.
Toolpioneers can assist you in implementing these configurations, ensuring a smooth and secure integration process. Our expertise ensures your Retool applications are optimized for efficient and secure authentication.
Ready to enhance your Retool authentication? Contact Toolpioneers today for expert guidance and comprehensive support.