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.
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.
Note
Not all of the Learning Framework API action yet have specific scopes defined for them. All these actions without specific scopes defined can be used with a single, “legacy” scope (core:*:*), so if your application uses any such actions, you should register to use that scope and declare it when requesting access tokens.
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.
Revoke consent from an authenticated app¶
When a user has consented to an app, the authentication service remembers the consent indefinitely unless it is revoked. If you revoke consent from an authenticated app, users are prompted for consent again the next time they attempt to authenticate.
Navigate to the My Settings widget.
Click Account Settings.
In the Application Settings section, click Manage applications registered with OAuth 2.0.
On the Manage Applications page, click the app that you want to revoke authentication from.
Click Remove App.