How to Build an OAuth Integration with the Assembly Platform
Please don’t hesitate to get in touch if you have questions. You can email us at email@example.com or give us a call at 020 8506 6100.
What is OAuth?
OAuth is an open standard designed to allow a 'resource owner' (in our case a school) grant limited access to data which is held on an resource server (the Assembly Platform) to a third party (you, the app developer). Data access is usually scoped to particular items or sets of data.
Why does Assembly use OAuth?
At Assembly we strongly believe in data security and a school's right to choose (opt-in rather than be forced to opt-out) which data a third party application may access. We believe that schools should be able to revoke access to the data held on the Assembly Platform at any time and we feel that OAuth provides an excellent mechanism to facilitate this process and help schools own their data properly.
Whats the basic flow to authorise my app?
Here's what needs to happen in order for a school to authorise your app to access their data:
- A school user can initiate the authorisation request from the Assembly Platform but you can also provide a page on your app to initiate the process.
- From the Platform a user would hit the 'Authorise Now' button for your app. All this button does is send the user to the Install URI that you provide when you configure your app on the Platform.
- At this point your app can either:
- Allow the user to sign in to your app so that you know who they are (or do any other initial setup that you want) and then provide a link to being the authorisation process OR
- Re-direct the user straight back to https://platform.assembly.education/oauth/authorize to start the OAuth process.
- Once the user accepts the authorisation request the Platform will use the Redirect URI you provided to callback to your app with a temporary code.
- Your app must use the temporary code from the step above to request an access token and a refresh token which it must then store in a secure location.
- Your app can now use the access token to make requests for the school's data.
How can I test my application's OAuth flow on Assembly Sandbox?
We provide a sandbox environment which is completely separate from our production environment.
Because OAuth is a protocol that requires interaction from both the user and the application it can be difficult to test the flow fully. For this reason, on our sandbox environment, you are able to act as both the developer and as the school user in order to fully test your application's OAuth flow.
Once you have signed up to sandbox, you will need to create a New Sandbox App:
Give the app a name and fill out any other information you desire (this is more important when you promote your application to production).
In order to test the OAuth flow you must add a Redirect URI that points to where your application is being served from. It should be a special URI that the Assembly Platform will call back to when a user accepts your app's data request.
The install URI will link to where the user kicks off the authorisation process - this will be where the Authorise Now button links to for your test school.
In our simplified Sinatra OAuth example, this takes the user to a button on the third party site that then initiates the Authorisation request to the Platform:
Of course, users could access this page directly from your site (without being directed there from the Assembly Platform). You may also want the user to sign in or sign up on your site before they reach this button.
These URIs can be an address on your local machine whilst you are building your application (as in the above screenshots) because the OAuth flow takes place in the browser.
Ensure that the List this App for other schools to find? check box is selected and click Create App to finish the process.
IMPORTANT: When you click the Create App button you'll be given a
client_secret. You must make a note of these now. This is the only time you will be able to see this information.
Implementing the OAuth flow
The OAuth flow that your application must complete in order to get an
refresh_token for each school is a multi-step process that takes place both on your app server and in the browser:
client_id: The ID you received when you registered your application with Platform sandbox or production
redirect_uri: The URI the the Platform will callback to when the user accepts or rejects the app authorisation request.
state: You should provide a unique code here generated by your app for each request. You'll use this code later to guard against CSRF.
scope: A list of scopes to which your application needs access. The available scopes are defined here.
When you created your app you provided a Redirect URI. The Assembly Platform will callback to this URI. The Platform will also check the URI you provided in your app configuration against the
redirect_uri parameter in Step 2, above so they must be identical.
HTTP GETand will include the following URI parameters:
code: A temporary authorisation code. You will exchange this for an access token in the next step.
state: The anti CSRF token that you provided above. You should check to see they are the same.
You can now exchange the temporary code received in step 3 for an access token and a refresh token. You do so with a POST request to the Platform with the following URI parameters:
code: The temporary code from step 3.
redirect_uri: You must still provide the original
redirect_uriat this stage otherwise the request will be rejected.
client_secretthat you received when you registered your application with Platform sandbox or production. They must be sent in a
Basic Authorizationheader and must be Base64 encoded.
Step 5 (optional)
access_tokenyou received in Step 4 to get some basic information about the school who have authorised your app.
HTTP GETcall to https://api-sandbox.assembly.education/me (or https://api.assembly.education/me on the live environment) with the
Authorizationheader will return a school's name and URN. You can read more about that here.
Once you're happy that your OAuth integration is working, you're ready to move across to the live environment and start onboarding schools. Please contact firstname.lastname@example.org for more information on how to proceed.