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.

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 and Access Tokens expire after 10 minutes

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
  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"
  5. The user is now logged in to the vendor’s website, and can continue their activity there.