OAuth Scopes and Provider Tokens

Descope allows you to customize the scopes requested from the provider when you have configured your authentication account for the provider within the OAuth Authentication Methods for the applicable provider.

This feature also pairs with the option to Manage tokens from provider for later use within your application when you would like to use the provider token to take action on the user's behalf or load further data for the user.

Use Cases

Using customized scopes offers a wide variety of use cases. These use cases can be as simple as getting further contact information for a user to make a FaceBook post on a user's behalf. Below are a few examples that you may be interested in using:

• Adding the pages_manage_posts scope to your FaceBook provider to allow your application to post to Facebook on the user's behalf.
• Adding the read:org and read:project scopes to your GitHub provider to capture detailed information about the user's org and associated projects.
• Add the calendar scope to your Google provider to allow your application to read and write to the user's calendar.

Example Use Case

This example will cover adding the calendar scope to your Google provider to allow you to read and write to the user's calendar.

Google Configuration

Add the Scope

If not completed, step through the guide for creating a Custom Social Login With Google.

When you create your consent screen, add https://www.googleapis.com/auth/calendar as a scope. If you've already created your social login within Google, ensure you add this scope to your current consent screen.

Below is an example of what this configuration would look like within your Google consent flow.

Enable Google Calendar API

Go to Enabled APIs & Services within Google, and click +Enable APIs and Services at the top of the page, search for and enable Google Calendar API

Descope Configuration

Click on the Google provider within the Social Authentication Methods. If you've not already configured your provider, configure the provider per the Custom Social Login With Google guide, and then also configure the additional scope https://www.googleapis.com/auth/calendar. To utilize the provider's token later, select the toggle for Manage tokens from provider. Below, you can see a configured Google provider with the necessary configuration.

Once you have successfully configured the provider, log in with Google, and you will see the updated consent flow, which asks for your permission to allow the application access to the user's calendar. Below is an example of the consent flow.

Using Stored Provider Tokens

Get the Provider Token

After the user logs in, Descope securely stores the provider token. You can retrieve it using the API Endpoint or Management SDK.

These requests require:

• loginId - The user's login ID
• provider - The provider name in lowercase (e.g., google, apple, facebook, github, microsoft) or your custom provider name

Below is an example of the Descope API or Management SDK response.

{
    "provider": "google",
    "providerUserId": "xxxx",
    "accessToken": "xxxxxxxxxxxx",
    "expiration": 1695915480,
    "scopes": [
        "openid",
        "email",
        "profile",
        "https://www.googleapis.com/auth/calendar"
    ]
}

Use the Provider Token

You can then utilize the provider token to interact with the user's Google Calendar. These actions are documented within the Google Developer Guide.

The API endpoints available within CURL can also be found on the Developer Google Docs.

Get a list of Calendars

To start, you will want to get a list of the user's Calendars; below is an example of using an access key to list the user's calendars. The response will include the id's of the user's calendars for use in the following steps. These IDs can be the user's email, custom calendars, or generic calendars the user has added to their Google calendar.

curl -H "Authorization: Bearer <accessToken>" "https://www.googleapis.com/calendar/v3/users/me/calendarList"

Get Events from a Calendar

You can then utilize the access token to get the user's events with different query parameter flags.

curl -H "Authorization: Bearer <accessToken>" "https://www.googleapis.com/calendar/v3/calendars/user@email.com/events?maxResults=2&timeMin=2023-09-01T10:00:00-07:00"

Create Events within Calendar

You can utilize the access token to create an event on the user's calendar via the various supported methods. The below example uses the quickAdd method. This endpoint creates the event based on text data for the name and when. The created event is in the response.

curl -H "Authorization: Bearer <accessToken>" "https://www.googleapis.com/calendar/v3/calendars/user@email.com/events/quickAdd?text=Event%20Tomorrow%20at%2012pm"