Build a private application
How to build a basic private application with CARTO login
Here you will learn how to create an application that requires a login to access. This application will be only accessible to users inside your CARTO organization (regardless of their role), so you will need a CARTO user to access it.
If you're building an application for an Enterprise organization that requires an integration with your own login system, you'll need to first connect and enable the Single Sign-On (SSO) feature in CARTO.
The CARTO login uses the popular OAuth 2.0 Authorization Framework protocol, so in this guide you will find an easy process to implement it, including login and logout methods.
After completing this guide you will be familiar with the following concepts:
- Scaffolding your application.
- Creating a Single Page Application (SPA).
- Managing the user login using Auth0 SDK.
- Visualizing a dataset.
- Executing a query against CARTO APIs.
Architecture diagram of a private application with Login
During this guide, we're using the CARTO Data Warehouse. The process explained here is also compatible with other Warehouses like BigQuery, Snowflake, Redshift, or Postgres. Instead of using
connection=carto_dw, you need to use connection=<your_connection>.To make this guide faster, we're going to start using the basic CARTO template in Vite that already includes a Basemap and deck.gl.
git clone https://github.com/CartoDB/viz-doc.git
cp -r viz-doc/guides/template private-app
cd private-app
npm install
npm run dev
As explained in Key Concepts section we need to create a Single Page Application (SPA) to obtain a client_id + client_secret that we will use to then obtain an OAuth token after the user successfully authenticates (with user and password or other methods)
Then, go to the .env file, and uncomment VITE_CLIENT_ID with the value of the app that was just created.
CARTO platform uses Auth0 under the hood to manage the authentication and authorization. When you created a SPA application in the previous step, CARTO created a SPA application in Auth0.
Auth0 provides SDKs to manage the OAuth 2.0 workflow for Angular, Vue, React, and Vanilla Javascript. In this guide, we're going to use the Vanilla Javascript SDKs to manage the login with CARTO.
We're going to implement here two things:
- Authenticate a user following the standard OAuth 2.0 workflow.
- 1.Install the Auth0 SDK:
npm install @auth0/auth0-spa-js
- 2.Create a file src/auth.ts:
import { Auth0Client, createAuth0Client } from '@auth0/auth0-spa-js';
let auth0Client: Auth0Client
export async function initAuth() {
let accessToken: string | undefined;
const clientId = import.meta.env.VITE_CLIENT_ID;
auth0Client = await createAuth0Client({
domain: 'auth.carto.com',
clientId,
authorizationParams: {
redirect_uri: window.location.origin,
audience: 'carto-cloud-native-api'
}
})
if (location.search.includes('state=') &&
(location.search.includes('code=') ||
location.search.includes('error='))) {
await auth0Client.handleRedirectCallback();
window.history.replaceState({}, document.title, '/');
}
const isAuthenticated = await auth0Client.isAuthenticated();
const appEl = document.getElementById('app');
if (isAuthenticated) {
appEl?.classList.add('isAuthenticated');
const userProfile = await auth0Client.getUser();
accessToken = await auth0Client.getTokenSilently();
if (userProfile) {
const profileEl = document.getElementById('profile')!;
profileEl.innerHTML = `
<p>${userProfile.name}</p>
<img width="50px" height="50px" src='${userProfile.picture}' />
`;
}
} else {
appEl?.classList.remove('isAuthenticated');
}
// Logout
const logoutButton = document.getElementById('logout');
logoutButton?.addEventListener('click', (e) => {
e.preventDefault();
auth0Client.logout();
});
// Login
const loginButton = document.getElementById('login');
loginButton?.addEventListener('click', (e) => {
e.preventDefault();
auth0Client.loginWithRedirect();
});
return accessToken
}
- 3.Replace src/main.ts with:
import './style.css'
import { initAuth } from './auth'
import { createMap } from './map'
document.querySelector<HTMLDivElement>('#app')!.innerHTML = `
<button id="login">Login</button>
<div id="login-content">
<header>
<button id="logout">Logout</button>
<div id="profile"></div>
</header>
<div id="map"></div>
<canvas id="deck-canvas"></canvas>
</div>
`
initAuth().then((accessToken) => {
if (accessToken) {
createMap()
}
})
- 4.Add this at the end of src/style.css:
header {
z-index: 1;
position: absolute;
padding: 10px;
}
#login-content {
display: none;
}
.isAuthenticated #login-content {
display: block;
}
.isAuthenticated #login {
display: none;
}
Your application is now ready to authenticate users by sending them to the CARTO login, which will require the user to enter their own credentials, before successfully returning to the application in a classic OAuth 2.0 workflow that returns an OAuth Access Token.
Once the user is logged in an OAuth Access Token will be available, and we just need to tell deck.gl to use this token.
Let's modify src/main.ts:
import { setDefaultCredentials }from '@deck.gl/carto/typed'
initAuth().then((accessToken) => {
if (accessToken) {
const apiBaseUrl = import.meta.env.VITE_API_BASE_URL;
setDefaultCredentials({ apiBaseUrl, accessToken})
createMap()
}
})
Then add the following layer to the Deck instance at src/map.ts:
new CartoLayer({
id: 'places',
connection: 'carto_dw',
type: MAP_TYPES.TABLE,
data: 'carto-demo-data.demo_tables.populated_places',
pointRadiusMinPixels: 3,
getFillColor: [200, 0, 80],
})
Remember that OAuth Access Tokens impersonate the user, so it will inherit all the permissions of the user.
At this point, we're all clear to execute a query against the CARTO SQL API using the OAuth Access Token we've previously obtained.
Create a file src/api.ts:
interface ExecuteQueryProps {
apiBaseUrl: string
connection: string
query: string
accessToken: string
}
async function executeQuery ({apiBaseUrl, connection, query, accessToken}: ExecuteQueryProps) {
const url = `${apiBaseUrl}/v3/sql/${connection}/query?q=${encodeURI(query)}`
const options = {
method: 'GET',
headers: {
'Authorization': `Bearer ${accessToken}`
}
};
const response = await fetch(url, options);
return await response.json();
}
interface GetAirportsProps {
apiBaseUrl: string,
accessToken: string
}
export function getAirports ({apiBaseUrl, accessToken}: GetAirportsProps) {
const query = `select * from carto-demo-data.demo_tables.world_airports`
const connection = 'carto_dw'
return executeQuery({apiBaseUrl, connection, query, accessToken})
}
Modify src/main.ts to call the
getAirports function: initAuth().then((accessToken) => {
if (accessToken) {
const apiBaseUrl = import.meta.env.VITE_API_BASE_URL;
setDefaultCredentials({ apiBaseUrl, accessToken})
createMap()
getAirports({apiBaseUrl, accessToken}).then((airports) => {
console.log(airports)
})
}
})
Congratulations! You now have successfully built a private application that will require the user to log in. And after a successful login, you're able to show the user a map layer, and you're able to query an airports dataset right from your application.
git clone https://github.com/CartoDB/viz-doc.git
cd viz-doc/guides/private-app
We recommend you to visit CARTO for deck.gl to learn more about the visualizations you can create in deck.gl. There are many examples in our gallery that might be useful to improve your application!
Last modified 1mo ago