Represent Multiple APIs Using a Single Logical API

If you have multiple distinct API implementations that are all logically a part of the same API, you can simplify your authorization process by representing them with a single logical API in the Auth0 Dashboard. Doing this allows you to implement just one authorization flow, while still controlling access to the individual APIs by assigning the appropriate scopes.

This tutorial explains how to use and represent multiple APIs as a single Resource Server in Auth0. As a learning tool, we provide a sample application that you can follow along with as you read.

The sample application uses a microservices architecture and contains:

1 Single-Page Application (SPA)
2 APIs (services), called contacts and calendar

We will represent the two APIs using just one Auth0 API called Organizer Service. We will then create two scopes to demonstrate how you can use the Implicit Flow to access the calendar and contacts APIs from the SPA.

Before beginning this tutorial:

Register your Application with Auth0
- Select an Application Type of Single-Page App.
- Add Allowed Callback URLs of http://localhost:3000 and http://localhost:3000/callback.html.
Download the sample application, so you can follow along as you read. Please see the README for additional information on setting up the sample on your local environment.

Enable a Connection for your Application: Configure a source of users for your new application.
Create a test user: Associate a test user with your new connection.
Register a logical API in Auth0: Register a single logical API to represent your multiple APIs.
Configure scopes for the logical API: Create the scopes that will allow the logical API to represent your multiple APIs.
Grant access to the logical API: Configure the login link in your sample application, initiate the authorization flow, and extract the Access Token to be used to call your multiple APIs.

Optional: Implement Single Logout (SLO) or Single Sign-on (SSO)

Set up a Database Connection: You will need a source of users for your newly-registered application, so you will need to configure a Connection. For the purpose of this sample, we'll create a simple Database Connection that asks only for the user's email address and a password.

Create a test user: Since you're working with a newly-created Connection, there won't be any users associated with it. Before we can test the sample application's login process, we'll need to create and associate a user with the Connection, so make sure you choose your newly-created Connection when you create your user.

Register an API: Register a single logical API that you will use to represent the multiple APIs contained within the sample application. For the purpose of this sample, call your API Organizer Service and set its unique identifier to organize. By default, the signing algorithm for the tokens obtained for this API is RS256, which you should leave as is.

Add API permissions: To allow the logical API to represent the APIs included within the sample application, you will need to create the proper permissions (scopes).

Scopes allow you to define which API actions will be accessible to calling applications. One scope will represent one API/action combination. For the purpose of this sample, you want calling applications to be able to read from one API called calendar and another one called contacts, so you will need to create the following permissions:

read:calendar
read:contacts

You can think of each one as a microservice.

You are now ready to provide access to your APIs by allowing the logical API to obtain Access Tokens. By including the necessary scopes, you can control an application's access to the APIs represented by the logical API.

Authorization - Rest of article uses Implicit Flow, but can use whichever flow you need

The rest of this article uses the Implicit Flow to reflect the sample. However, you can use whichever flow best suits your needs. For example:

If you have a Machine-to-Machine Application, you can authorize it to request Access Tokens for your API by executing a Client Credentials Flow.
If you are building a Native App, you can implement the Authorization Code Flow with Proof Key for Code Exchange (PKCE).

For a full list of available Authorization flows, see Authentication and Authorization Flows.

The user clicks Login within the SPA, and the app redirects the user to the Auth0 Authorization Server (/authorize endpoint). To learn more about the call's parameters, see our tutorial: Call Your API Using the Authorization Code Flow with PKCE.
to configure this snippet with your account
https://YOUR_AUTH0_DOMAIN/authorize? scope=read:contacts%20read:calendar& audience=organize& response_type=id_token%20token& client_id=YOUR_CLIENT_ID& redirect_uri=http://localhost:3000& nonce=NONCE
Was this helpful?/
Your Auth0 Authorization Server redirects the user to the login page, where the user authenticates using one of the configured login options.
If this is the first time the user has been through this flow, they see a consent prompt listing the permissions Auth0 will give to the SPA. In this case, the user is asked to consent to the app reading their contacts and calendar.
If the user consents, Auth0 redirects the user back to the SPA with tokens in the hash fragment of the URI. The SPA can now extract the tokens from the hash fragment using JavaScript and use the Access Token to call your APIs on behalf of the user.
function getParameterByName(name) { var match = RegExp('[#&]' + name + '=([^&]*)').exec(window.location.hash); return match && decodeURIComponent(match[1].replace(/\+/g, ' ')); } function getAccessToken() { return getParameterByName('access_token'); }
Was this helpful?/

In our sample, after you successfully log in, you will see buttons that allow you to call either of your APIs using the Access Token obtained from the logical API.

Authorization - Represent Multiple APIs using Single API - APIs

In some multi-application scenarios, where Single Logout is desired (a user logging out of one application needs to be logged out of other applications), an application can be set up to periodically poll Auth0 using checkSession() to see if a session exists. If the session does not exist, you can then log the user out of the application. The same polling method can be used to implement silent authentication for a Single Sign-on (SSO) scenario.

The poll interval between checks to checkSession() should be at least 15 minutes between calls to avoid any issues in the future with rate limiting of this call.

Docs