Creating an OAuth Application: Vendor Workflow

Overview

Because OAuth is a standard approach for enabling SSO, there is a lot of material on the internet about how to set up an integration with an OAuth provider.

• https://www.oauth.com/ 
• https://oauth.net/getting-started/ 

In most cases we expect that vendors will use OAuth libraries (typically available publicly, not provided by Veracross) to integrate with an OAuth provider. However, to get a picture of how it all works, the basic HTTP request/responses are listed below. 

• The authorization base url is “https://accounts.veracross.com/[school route]”.
• The necessary OAuth grant type is “authorization code”.
• Authorization Codes expire after 10 minutes and must be exchanged for Access Tokens as described below. When an Access Token is provided, it will include information about when it expires.

Process

1. When it’s time for a user to go to a vendor site, if they’re not already logged in they need to visit our authorization url. Authorization URLs are formatted like so:
   Request: https://accounts.veracross.com/[school route]/oauth/authorize
   ?client_id=[from OAuth Application]
   &redirect_uri=[encoded version of one of the pre-registered Redirect URIs from the OAuth Application]
   &scope=sso
   &response_type=code
   Note: the authorization url must include scope=sso in order for Single Sign On to work. Additionally, the `sso` scope is required to make the call to the userinfo endpoint below.
2. If the user isn’t logged in to Veracross yet, they’ll have the opportunity to do so. After they log in (or if they were already logged in), the user will then be redirected to the Redirect URI, with an authorization code. For example:
   Redirect: https://your-site.com/oauth/callback?code=[some string of digits]
3. Vendors need to exchange the authorization code for an access token. This is done with a POST request to the authorization server, for example:
   Request: https://accounts.veracross.com/[school route]/oauth/token
   ?client_id=[from OAuth Application]
   &redirect_uri=[encoded version of one of the pre-registered Redirect URIs from the OAuth Application]
   &client_secret=[from OAuth Application]
   &code=[from the redirect]
   &grant_type=authorization_code
   Response: This will be JSON that includes the access token 
4. The access token is used to retrieve info about the user that has logged in, such as their Veracross account ID and username. This is done with a GET request to the authorization server, following this format:
   Request: https://accounts.veracross.com/[school route]/oauth/userinfo
   Request Headers: Authorization: Bearer [the user's access token]
   Reponse: This will be JSON that includes a "sub" (subject) field and "preferred_username"
   Note: sub is the internal account id, and uniquely identifies a user at a school. It must be combined with the school route to become globally unique. For example, different users at different schools might have the same sub value. Also note that schools may configure their own format for preferred_username, so it should only be used for display purposes (eg, some schools use email, some schools use other id's, etc)
5. The user is now logged in to the vendor’s website, and can continue their activity there.