Authentication overview
OAuth 2.0
Our products make use of an OAuth 2.0 base authentication server. Full details of the OAuth 2.0 spec are outside the scope of this document, but we will give a brief overview of some of the critical concepts.
How is authentication used?
On the whole when accessing a service that we provide that requires authentication you will be acting in one of two ways:
- As a user
- As an organisation, on behalf of a user
The second is the more complex, and usual situation, which we will discuss here.
Acting on behalf of a user
When accessing one of our APIs you will often be accessing data, or performing actions as a user, or for them. This is a common situation on the web; for example if you use a social media account to log into another service and allow that service to read some of your details.
As a provider of that 3rd party service, you are said to be a "client" accessing a "resource" owned by a "user-agent".
For the process to continue we need to be sure of a few things:
- That the user-agent is who they say they are (they have successfully logged in)
- That the user-agent has access to the resource
- That the user-agent wants to let you access the resource (they "grant" access to it)
- That you are who you say you are
- That you are trusted by Registers of Scotland to access the resource the user is granting access to
- Finally, that we are Registers of Scotland, and that no-one has spoofed access
How this works in practice
You can follow the interactive Authentication tutorial to try this in a browser right now.
- You will start the journey by directing the user to a specially crafted login request to our authentication server
- This request contains:
- A "client id" (provided by us beforehand), which tells us who you are
- A "scope" (provided by us beforehand), which identifies which resources you want access to
- A "redirect URI", which will redirect the user's browser to your application telling you about the outcome of the login
- An optional but recommended "state", which helps to prevent cross-site request forgery
- Once the user has logged in they will:
- Be told who you are
- What resource of theirs, you would like access to
- And be asked to grant access to it
- If all goes well, we will follow the redirect URI provided and give you an "auth code"
- If you have used a "state" parameter in your initial request, at this point you should check that the returned "state" matches the provided one
- You then talk directly to us to check the auth code is valid.
- You provide a "client secret" to prove you are who you say you are
- We will then give you an "access token", which you must store securely and never expose to the front-end
- Provided that you have used a "state" parameter in your initial request, you should check that it matches with our response
- The access token is transmitted with all API calls from now on, and is all you need to use the service in future
Access tokens expire, but can be refreshed
The access token you are given has a fixed life span. When it expires you will need to start the authentication process again.
To prevent you from having to ask the user to login again, when you are provided with a "refresh token" along with the access token. You can use the refresh token any time before the access token expires to get a new access and refresh token pair.
- Access tokens are:
- Used to access the service
- Used many times until they expire
- Refresh tokens are
- Used to get new access and refresh tokens
- Are only used once and then expire
What happens when things go wrong?
The process is designed to stop if any thing is wrong at any point. Here are a few situations that can occur in the flow:
When getting an auth code
| Situation | HTTP response | Outcome |
|---|---|---|
| Registers of Scotland determines you are not allowed to access the resource | 302 - Redirect | ?error=invalid_scope |
| The user doesn't log in | n/a | No feedback |
| The user doesn't have the ability to grant access | 302 - Redirect | ?error=insufficient_permissions |
| The user denies you access | 302 - Redirect | ?error=access_denied |
When using an access token
| Situation | HTTP response |
|---|---|
| The user revokes permission they previously granted on a resource | 401 - Unauthorised |
| Your access token expires | 401 - Unauthorised |
Note: You must code expecting that the authorisation workflow will fail. You should expect any call to our services to potentially return a "401 - Unauthorised" response.
To aid you testing these scenarios, we provide users who do not have the correct priviledges to grant access. Most other situations can be simulated yourself, by failing to login, or refusing to grant access.