OpenID Connect Guide

// By Dropbox Platform Team • Jul 27, 2022


OpenID Connect—or OIDC—is an identity layer. It lets you build support for signing into your application via the user’s email verified Dropbox identity, which reduces the number of steps for a user to sign up for your service.

This provides the end user with a simple consent screen, and returns basic profile information to your application.

Screenshot of the authorization page using OIDC

OIDC is built on top of OAuth 2.0 so be sure to read our OAuth Guide before proceeding. The remainder of the guide assumes familiarity with the OAuth code flow and scopes.

Implementing OIDC

Scope Selection

To use OIDC in your request, be sure to select the openid scope and at least one of profile or email. The profile scope is required to view first and last name, and email to view email.

Screenshot of the available OpenID Connect scopes in the Permissions tab in the app settings for a Dropbox app

OpenID Connect scopes in the Permissions tab in the app settings for a Dropbox app

Authorization URL

To use OIDC, be sure to specify them in the scope parameter of your /oauth2/authorize authorization URL: email profile

Note that the OIDC scopes must be explicitly requested via the scope parameter—they will not be included by default if not included in the scope parameter.

OIDC is only supported when using the code grant, that is, with response_type=code.

Retrieving Identity

When OIDC scopes are requested, the result of the /oauth2/token call will contain the return value id_token in addition to its other return types. The id_token is a JSON Web Token which is a series of three character strings separated by periods: header, payload, and signature. They can be parsed with standard JWT libraries; header and payload are base64-encoded.

The parsed JWT will contain identity information in this format:


Alternatively, the identity information may be retrieved via the /openid/userinfo endpoint.

Email verification

The OIDC flow guarantees email verification—email_verified will always return true. If the user has not verified their email address on Dropbox, they will be prompted to do so during the OAuth app authorization flow when requesting OIDC scopes.

Email verification is not required for non-OIDC authorization flows. To verify identity, use OIDC.

OIDC Standard

OIDC is an open standard. It is supported by many tools and libraries which can simplify your implementation. Dropbox has implemented mandatory parts of the specification.

Discovery Documents

Dropbox has published standard discovery documents:


Dropbox’s OIDC implementation supports the following claims:

Claim Description
iss The Issuer Identifier (always
sub An identifier for the user. This is the Dropbox account_id, a string value such as dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc.
aud The audience this ID token is intend for. This will be your application’s client_id.
iat The time the ID token was issued, as a Unix timestamp.
exp The time the ID token expires, as a Unix timestamp.
family_name Last name
given_name First name
email Email address
email_verified If the email address has been verified (always true).

Authorization URL

Dropbox support mandatory parameters specified by OIDC on the authorization URL. 

The prompt consent and login parameter values are aliases of the force_reapprove and force_reauthentication parameters, respectively.

The OIDC display, preferred_locales, and acr_values are accepted for compatibility but are non-operational.


OIDC makes it easier to incorporate Sign in with Dropbox functionality into your applications.

The feature is now available as developer preview. As OIDC is a standard we do not envision incompatible changes, and consider the functionality safe to use in production environments. SDK coverage of OIDC functionality is limited; the functionality will be marked fully supported upon larger SDK coverage.

// Copy link