Last updated
Was this helpful?
Last updated
Was this helpful?
In this guide you will learn how to build a custom application that is integrated with your own Identity Provider (IdP) to authenticate and authorize your users, in a process typically known as Single Sign-On (SSO).
After completing this guide, you'll learn how to:
Set up an SSO integration between CARTO and your IdP
Modify a regular private application to use your SSO integration
Set up Just-in-time provisioning in your CARTO organization
Modify your application to use just-in-time provisioning for new users
To give you a quickstart, we're providing a sample private application with the changes covered in the . We will then add the specific code that we need to use SSO.
After that, you should have a project up and running at
From now on, we'll be assuming that a valid SSO integration has already been enabled and users are already accessing the CARTO Workspace using your Identity Provider.
To start using SSO in your application to seamlessly authenticate users, we need to add the SSO organization ID (provided by our support team after the SSO integration has been configured) to the .env file:
Then, we need to add the organization property to the authorizationParams property used to create the Auth0Client:
When users now click on the "Login" button, they will be redirected to their corporate login page where they will need to enter their credentials. After authentication is completed, we will be able to call the getTokenSilently method that will return an access token used to authorize the requests to the CARTO API.
🎉 Great! Your CARTO application is now using Single Sign-On to authenticate users.
However, at this point, your app won't be able to authenticate brand-new users that didn't exist previously in CARTO. These users will still be required to access first through the regular CARTO Workspace.
If you need to handle the provisioning of new users, keep advancing on this guide.
To continue with this guide and seamlessly onboard new users into your application using just-in-time, enable this setting.
The first step to onboard new users is to register a new environment variable with your Accounts URL. Your Accounts URL is the base URL where users go for login/signup.
For cloud deployments, this is always https://app.carto.com
For self-hosted deployments, this is a custom URL, like https://carto-instance.acme.com
Add this line to your .env file with your Accounts URL.
Finally, we need to update our authentication flow to accept new users, redirect them to the proper just-in-time provisioning flow, and complete their first login flow after CARTO sends them back to the application. This flow takes a few seconds and no user input is required, making it seamless and easy for new users to authenticate and use your application.
To make things easier, just replace your auth.ts file with the following code:
With these changes, our application now displays a login button that redirects the user to your Identity Provider (IdP). If the user already exists in CARTO, they will go straight to your app. If the user is completely new, they will also go straight to your app, but a new CARTO user will be provisioned in the process.
Here's what the experience looks like for a completely new user, after enabling just-in-time provisioning.
🎉 Congratulations! Your CARTO application is now using Single Sign-On to authenticate users and is also able to seamlessly create new users if they access your app for the first time.
Now that your application is successfully authenticating users via SSO, let's focus on creating interesting content.
A prerequisite for this guide is to set up the integration in your CARTO organization. When this integration is enabled, CARTO delegates authentication to your Identity Provider (IdP), and users who have not logged in are redirected to your IdP's login page.
After the user is authenticated, some of the user information from the IdP is available to CARTO, including the groups that this user is a member of. We synchronize this information as covered in the section in CARTO Workspace.
When SSO is enabled, you can configure CARTO to create users as soon as they successfully log in for the first time using your IdP login flow, without any additional steps or signup questions. We call this process Just-in-time provisioning. Check our documentation to learn .
We recommend you to visit to learn more about the visualizations you can create in deck.gl. There are many examples in our that might be useful to improve your application!
Use your company's identity management system to seamlessly control access to your application
