By Sarah-Beth Bianchi – January 26, 2015
With the latest changes to the app registration process, we've been talking a lot about authentication lately, mostly focused on App Id-Key FAQs and related best practices. But an equally important part of the Id-Key authentication mechanism is the User Id-Key pair. Questions about the intricacies around User Id-Key pairs have been popping up in the forums and in direct conversations with developers using the Brightspace APIs. In this post, we'll tackle some of the key questions and best practices around user authentication.
What is a User Id-Key pair?
Brightspace generates a User Id-Key pair when a user logs in via the Brightspace API authentication process. An app built using the Brightspace APIs uses that User Id-Key pair to identify the calling user when making API calls.
Can I reuse the User Id-Key pair in other apps?
The User Id-Key pair is unique to the calling app, so it cannot be reused to make calls on behalf of that user in a different app. This is by design, based on the principle that authentication with one app cannot be inferred as permission to authenticate that user with a different app. In the worst case, this mechanism prevents a bad actor from stealing user tokens from one app to use in another app.
How does Allowlisting impact User Id-Key pairs?
With the new allowlisting feature available in D2L Learning Environment version 10.3 SP13 and above, the User Id-Key pair will only be sent to location identified in the Trusted URL for an app. The goal of allowlisting is to ensure that even if your App Id-Key pair is leaked, the ability to utilize those tokens is limited by making it difficult to retrieve a User Id-Key pair. Put another way, this mechanism requires that the bad actor in possession of a leaked App Id-Key pair cannot retrieve a User Id-Key pair unless they also have access to the location specified in the Trusted URL.
Do user tokens expire?
User tokens can be set to expire after a period of time, or they can have an infinite lifespan. This setting is controlled using a Config Variable that can be set by D2L Support. It's important to note that this is a Org-level variable - there is no mechanism to allow some user tokens to expire while others remain infinite within the same Org.
When do expired tokens become invalid?
If you set a timeout value (i.e. 30 days) the tokens will be cleaned up during the first scheduled cleanup process that occurs after they expire. For example, if they expire after 30 days, and the scheduled task runs every 5 days, at most the tokens will be cleaned up 35 days after initial creation.
How can I revoke user tokens?
If you ever need to revoke a set of user tokens - perhaps because a physical device has been lost or compromised - there are two ways to accomplish this task.
- Change the user's password. When the password for an LMS account changes - whether initiated by the user or by an administrator - the user tokens associated with any apps become invalid. When the app attempts an API call on behalf of that user, the call will fail and the app should be designed to prompt the user to log back in to generate new user tokens.
Revoke app access. An administrator can force user tokens for a given user to become invalid. Just as with a password change, the next time an app attempts an API call on behalf of that user, the call will fail and the app should prompt the user to log in to generate user tokens. Administrators can use this function to force re-authentication with apps without having to also cause an update the LMS account password. This mechanism is especially useful in scenarios where LMS authentication is achieved through an SSO solution that relies on a static LMS password that the end-user is never privvy to.
- In the Admin > Users tool, click the checkbox next to a user and then click More Actions > Revoke App Access.
What best practices should I follow to keep user tokens secure?
Once a User Id-Key pair is generated for an app, it's important to keep these tokens secure by following a few best practices.
- Don't store user tokens in client-side apps, such as an app deployed in the browser using Javascript. Anything delivered on the client side is accessible to the end user, which opens up the ability to exploit those tokens. This is especially risky in cases where a service account is used to provide elevated privileges that a user should not have access to outside of a tightly controlled use case in a well-designed application.
- For the same reasons that you shouldn't store user tokens in a client-side app, you should never send them over an unsecure channel like plaintext email. In the rare case where you need to share user tokens - for example, if you need to provide service account tokens to an administrator to deploy into a server-side app - you should communicate these values via an encrypted channel like a secure FTP service or encrypted email.
- Take the time to evaluate apps that you registered prior to the introduction of the allowlisting feature so that you can set a Trusted URL. Setting this Trusted URL activates the allowlisting feature to provide the protections around user token generation explained above.
- If you're ever concerned that a user's account has been compromised, revoke the user tokens as explained above.
- If you're ever concerned that a specific app has compromised the security of user tokens, disable that app via the Manage Extensibility screen in any affected environments. If it's an app that you've built, you can generate a new App Id-Key pair. When you redeploy the app with the new App Id-Key pair, users will have to re-authenticate in order to generate new user tokens. In the case of a third-party app, contact the vendor directly to ask them to redeploy their app with a new App Id-Key pair. Contact D2L Support if you have concerns about a third-party app so that we can assist with resolving the matter.
