Pass additional scopes/permissions to a Social Connection

Knowledge Articles
1

Question: Can I add additional scopes to a Social Connection if I don’t see them in the permissions list?

When you configure a Social Connection, Auth0 gives you the option to configure additional permissions (scopes) to request to the identity provider, so that your application can use the identity provider access token to access other protected resources (see Identity Provider Access Tokens for instructions on how to obtain these tokens).

The Google Social Connection, for example, shows this:

image
image1318×1184 54.2 KB

What happens if you want a scope/permission that is not listed here? For example, Google defines a https://www.googleapis.com/auth/calendar.events.readonly scope that gives you read-only access to calendar entries.

Answer:

First of all, tell us! Leave a comment at Auth0: Secure access for everyone. But not just anyone., mentioning the connection type and the scope or scopes you need.

Until proper support is added, there are two basic workarounds:

Use the connection_scope parameter

The connection_scope parameter, described at Add scopes/permissions to call Identity Provider’s APIs, is a practical way to add additional scopes in the interactive token request (/authorize). It should always be used in combination with the connection parameter, where you specify the connection name to use (it doesn’t really make sense to add an additional scope for “any” connection type).

So, for the Google example mentioned above, applications would issue an authorize request like this:

https://{your_auth0_domain}/authorize?[...]
  &connection=google-oauth2
  &connection_scope=https://www.googleapis.com/auth/calendar.events.readonly

(the syntax to add parameters to the authorize request will vary depending on the SDK being used).

When receiving the above request, Auth0 will merge the pre-selected scopes from the permissions list with the scopes provided in connection_scope.

The disadvantage of this method is that the application needs to be explicit about the connection to use. This is often not a problem (after all, if the application wants a specific scope, then it knows about the authentication method). In some cases, it’s actually a nice feature to have: it lets you reduce the number of scopes/permissions requested by default, and allows only a specific application to ask for additional permissions.

Patch the connection with upstream_params.scope

If you want to isolate the application from this having to send a connection and connection_scope parameters, and you want the additional scopes to be present in all authentication requests to the identity provider, you can use the options.upstream_params configuration for social connections.

This method takes advantage of the Pass Parameters to Identity Providers feature to set a fixed value for the scope parameter when Auth0 sends a request to the upstream identity provider.

What we’ll do is configure the connection using Management API v2’s Update a connection endpoint to add a key to the options object. Remember that when patching a connection you need to provide the full options object, so you’ll need to “Get” a connection first to get the previous contents of the object.
Once you have that, the payload would look like this:

{
  "options": {
    [....] // all pre-existing options
    "upstream_params" : {
      "scope": {
        "value":"the scopes to send"
      }
    }
  }
}

In this case, Auth0 will not merge previously selected permissions, or scopes that are added by default (to get things like the user profile). In the case of Google connections, for example, email profile is the default scope. So you would need to ensure that they are present in addition to the scopes you want. E.g.:

{
  "options": {
    [....] // all pre-existing options
    "upstream_params" : {
      "scope": {
        "value":"email profile https://www.googleapis.com/auth/calendar.events.readonly"
      }
    }
  }
}

How do you know what are the default scopes? You’ll have to fiddle a bit inspecting the network requests (using the browser’s developer tools), to check the request made by Auth0 when you click on the “Use xxxx” button. E.g. for Google Auth0 redirects to something like this:

https://accounts.google.com/o/oauth2/auth?
  response_type=code
  &redirect_uri=[...]%2Flogin%2Fcallback
  &scope=email%20profile
  &state=[...]
  &client_id=[...]

If your change works, then you should see the scope sent to the IdP changing as well.

For other providers you’ll see different default scopes that you’ll need to take into consideration. You might also find out that this doesn’t work on all providers, as not all of them use the OAuth2 protocol or the scope parameter for permissions.

The benefit here is that all requests to Google will include these scopes, and individual applications don’t need to do anything special about it.

Supporting Documentation:

6 Likes