You can now use the already existing and accepted OAuth 2.0 protocol for authentication. For more information about the OAuth 2.0 protocol, including how to implement it in your application, see RFC 6749.

Setting up OAuth 2.0 authentication ¶

Follow these steps to set up OAuth 2.0 for your application:

Register your application to receive OAuth 2.0 credentials. These values are requried for obtaining an access token. Implement these credentials in your application.
Use the Authorization Code Grant workflow defined in the OAuth 2.0 specification to retrieve an access token (either by writing code to support that workflow, or using an available library of your choice); these are the relevant Brightspace service endpoints you will contact:
- Authorization endpoint: https://auth.brightspace.com/oauth2/auth
- Token endpoint: https://auth.brightspace.com/core/connect/token
Send your retrieved access token in the HTTP authorization header of each API call. The authorization header should be in the form of Bearer accessToken, where accessToken is the value of the access token provided by the Authentication Service. For more information about bearer tokens and implementation details, see RFC 6750.

Warning

Note that your authentication is a bearer token, meaning anyone making the API call can use this token to authentication the call. Accordingly, you should always use HTTPS to make API calls when using this authentication method, to keep your authentication token secure.

OAuth2 scopes in our APIs ¶

It’s useful to understand how our API platform uses OAuth 2.0 scopes, both before you seek to register your application and before your application tries to retrieve an access token to use one or more API action.

Specific scopes ¶

Our API actions that have specific scopes assigned to them will have a scope of this form:

<resource-group>:<resource>:<action>

For example, the action to retrieve the details for a user has the associated specific scope users:userdata:read.

When you register your application you should include each specific scope you want your application to use. When your application requests an access token, it should include each specific scope that it wants the access token to give it access to (note that, this list of scopes must be a subset of the ones the application was registered with).

Wildcarding within scopes. For convenience, when you register your application, you can use the * wildcard within the lists of scopes, for brevity’s sake. For example, instead of registering with users:userdata:delete, users:userdata:read, users:userdata:create, and users:userdata:update, you can instead register your app with users:userdata:*. The wildcard here stands in for all actions associated with that resource-group and resource combination.

You can also use the wildcard in this way when you request an access token.

General fallback scope ¶

Not all our API actions have specific scopes assigned to them yet. To support these actions, we have a single general fallback scope:

core:*:*

Note that this fallback scope does not appear in our scopes index nor in the API reference documentation for individual API actions.

In order to let your application use these you need to register to use the general fallback scope, and also ask for that scope when you request an access token.

As we continue to provide new specific scopes for API routes, you should use those scopes; however, if an API action used the general fallback scope in the past it will continue to support that scope for access.

Registering using OAuth 2.0 ¶

Register your application ¶

From the Admin Tools menu, click Manage Extensibility.
Click OAuth 2.0.
Click Register an app.
In the Application Name field, enter the name of your app. Brightspace Learning Environment users see this name on the consent page.
In the Redirect URI field, enter the URI for the page that you want users to be redirected to after authorization is successful.
In the Scope field, enter a value that represents the scope of the resources you want the app to be able to access on behalf of the user. This value must take the form of a space-delimited string that describes the resource group type, the resource, and the permissions you want the app to have (group:resource:permissions group2:resource2:permissions2). For example, data:aggregates:read.

There are two ways you can find the scope you need. The first is to use the scopes table that provides a list of scopes grouped by all the API calls that use each particular scope. Alternatively, you can look in the API reference for particular routes to see the scope(s) required for each route.
In the Access Token Lifetime field, enter a value in seconds that represents the amount of time that you want the token to be valid for. After this time, the token becomes invalid and the user is prompted to log in again.

Note that you must provide a value between 1800 seconds (30 minutes) and 72000 seconds (20 hours).
To prompt users to grant the app consent to use their account, select the Prompt for user consent check box.
To enable the use of refresh tokens, select the Enable refresh tokens check box.
After reading the Non-Commercial Developer Agreement, select the I accept the Non-Commercial Developer Agreement check box stating you agree to the terms.
Click Register.

Retrieve OAuth Credentials ¶

From the Admin Tools menu, click Manage Extensibility.
Click OAuth 2.0.
Click the name of the application for which you want to retrieve credientials.
Make a note of the values in the Client ID and Client secret fields.

Warning

Failure to store and transmit these credentials securely compromises the security of your application and related data.

In the event that a set of credentials has been compromised, delete the application from the Manage Extensibility > OAuth 2.0 application list and register a new application to receive new credentials. Use caution when deleting an application, as this action cannot be reverted.