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.
OAuth 2 Overview¶
This section provides an overview of the various components of using OAuth 2 to grant your application API access.
Registration. Before you can use OAuth to gain access to API actions, you must register your application. Resulting from your registration, Brightspace will provide you with a set of credentials you will later use to identify your application to the Brightspace authentication service. For more information about registration, see the following section on application registration matters.
Note that, as part of the registration process you must also declare the OAuth 2 scopes that your application will use to identify the particular API actions it will later want access to.
Access token request. Once provisioned, your application can make API access token requests of the Brightspace authentication service.
Note that you must use these Brightspace service endpoints as appropriate to the OAuth 2 authentication workflow type your app uses:
Authorization endpoint: https://auth.brightspace.com/oauth2/auth
Token endpoint: https://auth.brightspace.com/core/connect/token
Making access token requests¶
The workflow your application uses to make access token requests depends upon the type of application you have registered.
Authorization Code Grant. Authorization code grant applications 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).
As part of this workflow you will use both the Client ID and Client Secret assigned to your application during the registration process.
Client Credentials Grant. Client credentials grant applications use the Client Credentials Code Grant workflow defined in the OAuth 2.0 specification using JWT client assertions to identify themselves to the authentication service (see RFC 7521 and RFC 7523).
Your JWT client assertion must include the following properties in the header:
Header property |
Notes |
|---|---|
alg |
Supported algorithm values are RS256, RS384, RS512, ES256, ES384, and ES512 |
aud |
Must be the Brightspace token endpoint URL |
kid |
The key identifier for the key found in your JWKS Brightspace must use to validate your JWT client assertion |
Your JWT client assertion must include the following properties in the payload:
Payload property |
Notes |
|---|---|
iss |
Your application’s Client ID value given during registration |
sub |
Your application’s Client ID value given during registration |
iat |
Issued-at time for your JWT (the date-time it was created) |
exp |
Intended expiration time for your JWT (we recommend a short lifespan of 60 seconds or less) |
jti |
Unique, one-time-use value for the JWT |
Brightspace supports signing your JWT with RSA and EC (P-256, P-384, P-521) encrypted signatures.
Here is a simple example of the access token request that you’d use in the client credentials grant workflow:
curl --location 'https://auth.brightspace.com/core/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
--data-urlencode "client_assertion=${CLIENT_ASSERTION}" \
--data-urlencode 'scope=organizations:organization:read'
Note the following details about this request:
grant_type=client_credentials is required by the OAuth 2.0 specification.
client_assertion_type and client_assertion are defined by the JWT profile (RFC 7523) that uses JWT assertions to identify clients.
The scope value you provide must be a subset of the scopes you provided when you registered your application within Brightspace (it can be the entire list of scopes you registered with, but every scope you specify in this request must appear in the registered list of scopes).
Using your access token¶
Once you have received an access token from the access token request workflow, you can proceed to use it to make API requests. Note that you will only be able to use your access token for API actions that correspond to the various scopes you have been granted for use with your token.
Send your retrieved access token in the HTTP Authentication header of each API call. The value for this header must be Bearer {your access token} as in the following example:
GET https://someLMShost.edu/d2l/api/lp/1.50/users/whoami HTTP/1.1 Authentication: Bearer eyJ0eXAiOiJKV1Q ... {rest of bearer token}
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.
OAuth 2 scopes in our APIs¶
It’s useful to understand how our API platform uses OAuth 2 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. Scopes determine which Brightspace API actions your application will have access to call; however, they don’t in any way limit what your application can do with the actions they have access to: it’s always the calling user context (the Brightspace user on behalf of whom the API action takes place) and that user’s enrollment role in the relevant org unit context that ultimately determines what the application can do with Brightspace API actions.
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.
Insufficient scopes. If you attempt to use an API action without having the correct scopes bound to the access token, you will get an error informing you that you have insufficient scopes to use the action.
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.
In the case of getting an error for insufficient scopes, the error message will signal that the general fallback scope could be used with the API action you attempted to use if it could apply to that action.
OAuth 2 registration details¶
This section describes various procedures and topics related to OAuth 2 application registration:
Registering your application
Retrieving credentials for your application
Removing user consent for an application
Application registration procedure¶
You use the Manage Extensibility admin tool to register your application. From within that tool, follow these steps:
Choose OAuth 2.0, and then Register an app.
Select what type of OAuth 2 authentication workflow your application will use:
Authorization grant - Implemented with refresh tokens. Uses the context of the logged in user (requiring their consent). Recommended for applications that interact with end users.
Client Credential grant - Implemented using JWT client assertion. Uses the context of the assigned service user. Recommended for server-to-server applications.
In the Application Name field, enter the name of your app. Brightspace Learning Environment users see this name on the consent page.
If your application is an Authorization grant type application, you must provide a valid Redirect URI; enter the URL for the location Brightspace will redirect the user authentication workflow after the user successfully authenticates with Brightspace.
Client Credentials grant type applications need not provide this value.
If your application is a Client Credentials grant type application, you must provide a valid, HTTPS JWKS URL identifying the location of your application host’s signing-key sets. Brightspace will use this URL to retrieve public keys for verifying the signature on your JWT client assertion. Note that you must host your key sets on an HTTPS endpoint.
Authorization grant type applications need not provide this value.
In the Scope field, list all the scopes that correspond to the API actions you want your application to have access to.
This value must be a space-delimited string containing all the scopes that your application may later specify in access token requests.
If an API action has a specific scope to govern its use, its entry in the API reference will list this scope. API actions that do not have a specific scope for use will use the general fallback scope.
Note that the reference also contains an index page for all specific scopes you may refer to.
In the Access Token Lifetime field, enter a value in seconds that represents the amount of time that you want your access token to be valid for. After a token’s lifetime, it will expire and no longer be valid: your application use the authentication workflow again to get a new token. Note that Authorization grant type applications (and only those types) may use the Refresh workflow to refresh their access (see following).
Note that you may only request a lifetime value between 1800 seconds (30 minutes) and 72000 seconds (20 hours). Note also that the Brightspace authorization service may give you an access token with a lifespan that doesn’t exactly match your request, so you must be sure to note the access token’s actual lifetime.
If your application is a Client Credential grant type application, you must choose a service user to associate with your application. Each service user can be associated with only a single application.
A Brightspace administration must prepare your service user and role ahead of time, with only the permissions and enrollments required for your application.
If your application is an Authorization grant type application, then you can also chose whether it needs user consent for access and whether it can refresh its access using the Refresh workflow.
Users can be prompted for explicit consent to grant access to an application during the authorization code grant wofklow: to enable this, select the Prompt for user consent check box.
To allow the application to make use of the Refresh workflow (exchange a single-use, unexpired refresh token in for a new access token/refresh token pair), 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 to register your application.
Registered application credentials¶
Once you register your OAuth 2 application, you will need to know its application credentials so you can provision them in your application. You can find these in the Manage Extensibility Admin tool, in the entry for your registered application; from within that tool, follow these steps:
Choose OAuth 2.0, and then choose the name of your registered application.
Make a note of the values in the Client ID and/or Client secret fields.
Authorization Grant applications will provide both a Client ID and Client Secret; your application will later prove its identity using the client secret provided here.
Client Credentials Grant applications will provide only a Client ID; your application will prove its identity later with a JWT signed with one of your public/private key-pairs listed in your JWKS URL.
Warning
Failure to store and transmit your application’s 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.
Revoking an application’s consent¶
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.
Security & Operational Best Practices¶
Here are some best practices you should consider when using OAuth2 with your application and Brightspace.
Short assertion and token lifetimes. Treat your client application identity assertions as one-time credentials using a unique jti value, and keep them short-lived with a tight exp value. We recommend that client assertions have a lifetime of less than 60 seconds, and no longer than five minutes.
Key rotation. Rotate the keys in your JWKS key set periodically and monitor for failures on key rollover (see RFC 7517). Brightspace supports RSA and EC (P-256, P-384, and P-512) encrypted JWT signatures. When you rotate keys, we recommend you follow the best practice of a limited grace period to ensure receiving parties can validate assertions that you may have signed with an older key (but have not yet expired).
No shared secrets. Prefer asymmetric keys over client_secret for machine clients. This reduces the risk of shared secret sprawl and replay risks common with basic/POST secret authentication.
Good client assertion contents. The Brightspace authentication service validates the iss, sub, aud, exp and iat properties and will reject tokens with invalid clocks or reuse of jti (see RFC 7519 and RFC 7523).