Call an Identity Provider API
Once you successfully authenticate a user with an external Identity Provider (IdP), such as Facebook or GitHub, the IdP often includes an SAMLAccess Token in the user profile it returns to Auth0.
You can retrieve and use this token to call the IdP's API.
The process you will follow differs, depending on whether your code runs in the backend or the frontend:
If your code runs in the backend then we can assume that your server is trusted to safely store secrets (as you will see, we use a secret in the backend scenario). If that's the case proceed to the backend section of this article.
If your code runs in the frontend (for example, it's a SPA, native desktop, or mobile app) then your app cannot hold credentials securely and has to follow an alternate approach. To see your options proceed to the frontend section of this article.
1. Download Auth0 Metadata File
From the backend
Once you authenticate a user, the IdP often includes an Access Token in the user profile it returns to Auth0.
Auth0, for security and compliance reasons, does not send this token to your app as part of the user profile. In order to get it you will have to access the Auth0 Management API and retrieve the full user's profile.
The steps to follow are:
- Get an Access Token that allows you to call the Auth0 Management API.
- Call the Auth0 Management API's Get Users by ID endpoint, using the Access Token obtained in step one. This endpoint returns the full user's profile, which contains the IdP Access Token.
- Extract the IdP Access Token from the response and use it to call the IdP's API.
2. Create a new SP Connection
Step 1: Get a Token
You will need an Access Token to call the Management API.
If this is the first time you are requesting a Management APIv2 Token, you will need to create and configure an application that can be used to call the API.
To do so, go to Dashboard > APIs > Auth0 Management API > API Explorer and click Create & Authorize a Test Application.
This will create a new application and grant all scopes of the Management API. This means that the tokens generated for this application will be able to access all Management API endpoints.
Can't see the button?
If you don't see this button, it means that you have at least one authorized application already. In this case you can either update the scopes of an existing application and use that, or create a new one following these steps:
- Go to Dashboard > Applications
- Click + Create Application, select Machine to Machine Applications and click Create
- At the Select an API dropdown select
Auth0 Management API
- Click Navigate to the API and Authorize
- Set the toggle to Authorized and enable the required scopes
It is recommended, for security reasons, that you only assign the required scopes to the application you will be using. For this particular case, the scopes you need are:
You can grant or remove scopes from an application, at the Dashboard > APIs > Auth0 Management API > Machine to Machine Applications tab.
You are now done with the configuration part, and you are ready to get your Management API token.
To do so, go to the Test tab. There you can find ready-to-use snippets that you can use to get a token.
Pick your application using the dropdown at the top, and choose your language of preference for the snippet.
Copy and run the snippet. Extract the
access_token property from the response. This is what you will use to access the Management API.
More info on the snippets
The snippets make a
POST operation to the /oauth/token endpoint of the Auth0 Authentication API, using the OAuth 2.0 Client Credentials grant. This is the grant that machine-to-machine processes use to access an API. For more information on the flow, refer to Client Credentials Flow.
3. Configure the SP Connection
The token you received has, by default, an expiration time of 24 hours (86400 seconds). To change this, update the Token Expiration (Seconds) field, at the Settings tab and save your changes. The next token you generate will use the updated expiration time. The maximum value you can set is 2592000 seconds (30 days) however our recommendation is to keep the default value.
These tokens cannot be revoked. To minimize the risk, we recommend issuing short-lived tokens (and granting only the necessary scopes for each application). For a production environment you can configure a simple CLI that will fetch a new token when the old one expires. You can find a sample implementation in Python here.
4. Configure Browser SSO
Step 2: Get the full User Profile
Using the Access Token you got in the previous section, call the Get a User endpoint of the Management API, in order to get a user's profile:
Replace these values:
USER_ID: The ID of the user for whom you want to call the IdP's API.
YOUR_ACCESS_TOKEN: The token you got from the previous step.
Where do I find the User ID?
- For testing purposes, you can find a user ID at Dashboard > Users. Select a user and copy the value of the user_id field.
- For your implementation, you can either extract this information from the ID Token (get the value of the claim sub), or call the /userinfo endpoint of the Authentication API (get the value of the response property user_id).
5. Configure Protocol Settings
Step 3: Extract the IdP Access Token
Within the user's
identities array, there will be an Access Token that you can extract and use to make calls to the IdP's API:
In most cases, the user will only have one identity, but if you have used the account linking feature, there may be more.
In this sample response we can see that our user had only one identity:
You are now ready to call the IdP's API. Please refer to the IdP's documentation for specifics on how to do so.
6. Configure Credentials
From the frontend
If you are working with a public application (SPA, native desktop, or mobile app) then this is the place to be.
As you might have read earlier in this article, the process for calling IdP APIs from a backend process includes the following steps:
- Get an Access Token in order to access the Auth0 Management API
- Use said token to retrieve the user's full profile from the Auth0 Management API
- Extract the IdP's Access Token from the user's full profile, and use it to call the IdP's API
You cannot follow the same process from a frontend app because it's a public application that cannot hold credentials securely. The credential we are referring to, is the machine to machine application's secret which you use to make the call to
/oauth/token, at the first step of the process.
SPA's code can be viewed and altered and native/mobile apps can be decompiled and inspected. As such, they cannot be trusted to hold sensitive information like secret keys or passwords.
There are some alternatives you can use.
7. Activation of the SP Connection
Option 1: Build a proxy
You can build a process in your backend and expose it to your application as an API.
The backend process will implement the steps of the backend section. You will call the IdP's API from the same backend process so the Access Token is never exposed to your public application.
Then, you will call your proxy API from your public application using the respective flow for your case:
- Implicit Flow if you are working with a SPA
- Authorization Code Flow with Proof Key for Code Exchange (PKCE) if you are working with a mobile application
Show me how to do it
If you haven't implemented this before, you might find our SPA + API article useful. It covers a different scenario but it does explain how to configure Auth0, call an API from a SPA, and implement the API validations. It comes with a sample that uses Angular 2 and Node.js. We also offer a Mobile + API variation (the sample uses Android and Node.js).
Option 2: Use webtasks
If you don't have a backend server, and you don't want to set up one, then you can leverage serverless technology, using webtasks.
Webtasks are the Auth0 way to create HTTP endpoints with Node.js and access them from anywhere. It's a way to safely execute server-side logic, when you do not have a backend. They come with a command line tool and an editor. For more info, see the webtask.io documentation.
In this scenario, you will create a webtask and implement the steps of the backend section. Then the webtask will call the IdP's API so the Access Token is never exposed to your public application.
Your application will invoke the webtask with a simple HTTP request and manipulate the response appropriately (for example, render the user's GitHub repositories in the UI).