Login.Gov.GG - documentation for developers
Sample code
We recommend using a standard OpenID Connect/OAuth2 library for your platform. A brief summary of terminology and authentication flows is provided below; consult the documentation provided with your library of choice for implementation-specific details.
- Client-side JavaScript: See the sample provided with the oidc-client library.
- Angular.js: See the samples for the angular-oauth2 or angular2-oauth2 libraries.
- .Net: For .Net sample code, including an example of authenticating API access, see the IdentityServer4.Samples repository.
- Libraries for other platforms: The OpenID Foundation maintains a list of OpenID Connect libraries for various platforms.
Scopes and authenticating API access
The client must always request the openid
scope. If you require the user's email address, you should also request the email
scope. If you require the user's name, you should also request the profile
scope.
When you register your client, you may also register one or more custom scopes which you can use to authenticate access to your API(s). You should include these custom scope(s) in your request in addition to the standard scopes above.
Once you have retrieved an access token, that access token can be passed to your API. The API server can then verify the access token and use it to retrieve information about the user.
The ticket
scope
Login.Gov.GG exposes an API which issues application-specific 'tickets', which can have an expiration date and time. A ticket is a 32 character string which can be used to log into your application with a sub
which is associated only with the ticket, has no email address or password, and can log into only your application.
Authenticating against the ticket API
If your application is registered to use the ticket API you may access it by requesting the ticket
scope and passing an access token to the ticket API as described in Scopes and authenticating API access above.
The response status for all API requests without a valid access token will be 401
.
Error responses
The response body for all error responses (i.e. those not in the 2xx
range) will contain an error message, and may contain one or more additional messages describing details of the error:
{
"message": "Ticket has expired",
"details": [
"Ticket with ID \"5736BD657C7B16B563BBA20F8F91C529\" has expired."
]
}
Creating a ticket
POST <API root>/Ticket?expiryDays={expiryDays}
The expiryDays
parameter, which is optional, is an integer which specifies the number of days before which this ticket should expire. Omit this parameter to create a ticket which does not expire.
The response status will be 201
on success. The response body will contain details of the ticket:
{
"id": "5736BD657C7B16B563BBA20F8F91C529",
"expires": "2016-09-27T10:15:39.4697023Z",
"sub": 7
}
Listing tickets
To retrieve a list of all tickets your application has created which have not yet expired:
GET <API root>/Ticket
The response status will be 200
. The response body will contain a list of tickets:
[
{
"id": "18283E81A5DC566663804FE67AE36618",
"expires": null,
"sub": 5
},
{
"id": "5736BD657C7B16B563BBA20F8F91C529",
"expires": "2016-09-27T10:15:39.4697023",
"sub": 7
}
]
Retrieving ticket details
GET <API root>/Ticket/{ticket}
The response status will be 200
on success; the response body will contain details of the ticket:
{
"id": "5736BD657C7B16B563BBA20F8F91C529",
"expires": "2016-09-27T10:15:39.4697023",
"sub": 7
}
The response status will be 403
if the ticket has expired, or 404
if your application has not created a ticket with the given ID.
Expiring a ticket
If you set an expiration date and time when creating a ticket, that ticket will not be usable after that date and time.
To immediately expire a ticket which has not yet expired:
DELETE <API root>/Ticket/{ticket}
The response status will be 204
with an empty response body on success, 403
if the ticket has already expired, or 404
if your application has not created a ticket with the given ID.
Logging in with a ticket
A user of your application can log in using a ticket by visiting the following URL in a browser, where {ticket}
should be replaced by the ticket ID.
https://login.gov.gg/Ticket/{ticket}
A valid ticket will redirect to the ticket redirect URL specified when registering your client. Requests with invalid tickets will be shown an error page.
Upon receiving a request to the registered redirect URL, your application should log out the currently logged in user (if any), then initiate any OpenID Connect flow to obtain the ticket user.
Note that you should only log the user out from your local application, do NOT redirect the user's browser the end_session_endpoint
URL of Login.Gov.GG.
Identifying ticket users
If your application needs to distinguish ticket users from standard users, inspect the authentication method (amr
) claim, which will be pwd
for a standard user and ticket
for a ticket user.
Which OpenID Connect flow should I use?
OpenID Connect authentication requests can follow one of three paths: the authorisation code flow, the implicit flow, or the hybrid flow.
For a JavaScript-based application, you would typically use the implicit flow.
If you want to use the access token purely on the server side of a web application you would typically use the authorisation code flow.
Native mobile or desktop applications would typically use the the authorisation code flow.
The hybrid flow is an alternative to the authorisation code flow which may reduce the number of round-trips to the OpenID Connect provider.
Implicit flow
The implicit flow consists of the following steps:
- Client prepares an authentication request containing the desired request parameters.
- Client sends the request to the OpenID Connect provider.
- OpenID Connect provider authenticates the user.
- OpenID Connect provider sends the user back to the client with an ID token and, if requested, an access token.
- Client validates the tokens and retrieves the user's subject identifier (
sub
).
For the implicit flow, the client should request a response_type
of id_token
or id_token token
. For a list of other required and optional request parameters, see the implicit code flow spec.
Authorisation code flow
The authorisation code flow consists of the following steps:
- Client prepares an authentication request containing the desired request parameters.
- Client sends the request to the OpenID Connect provider.
- OpenID Connect provider authenticates the user.
- OpenID Connect provider sends the user back to the client with an authorisation code.
- Client sends the authorisation code to the OpenID Connect provider to receive an access token and ID token in the response.
- Client validates the tokens and retrieves the user's subject identifier (
sub
).
For the authorisation code flow, the client should request a response_type
of code
. For a list of other required and optional request parameters, see the authorisation code flow spec.
Hybrid flow
The hybrid flow follows the following steps:
- Client prepares an authentication request containing the desired request parameters.
- Client sends the request to the OpenID Connect provider.
- OpenID Connect provider authenticates the user.
- OpenID Connect provider sends the user back to the client with an authorisation code and, depending on the response type, one or more additional parameters.
- Client sends the authorisation code to the OpenID Connect provider to receive an access token and ID token in the response.
- Client validates the ID token and retrieves the user's subject identifier (
sub
).
For the hybrid flow, the client should request a response_type
of code id_token
, code token
, or code id_token token
. Other required and optional request parameters are the same as for the authorisation code flow.
Terminology
OpenID Connect provider
Login.Gov.GG is an OpenID Connect provider - it implements the OpenID Connect protocol. It is a piece of software that issues security tokens to clients.
Client
A client is a piece of software that requests tokens from IdentityServer - either for authenticating a user or for accessing a resource. A client must be registered with the OpenID Connect provider.
Examples of clients are web applications, native mobile or desktop applications, server processes etc.
User
A user is a human that is using a registered client to access his or her data.
Scope
Scopes are identifiers for resources that a client wants to access. This identifier is sent to the OpenID Connect provider during an authentication or token request.
They come in two flavours.
Identity scopes
Requesting identity information (aka claims) about a user, e.g. his email address is modelled as a scope in OpenID Connect.
There is e.g. a scope called email
that includes the email address.
Resource scopes
Resource scopes identify web APIs - e.g. a scope named calendar
could represent a calendar API.
Authentication/Token Request
Clients request tokens from the OpenID Connect provider. Depending on the scopes requested, the OpenID Connect provider will return an identity token, an access token, or both.
Identity Token
An identity token represents the outcome of an authentication process. It contains at a bare minimum an identifier for the user (called the sub
aka subject claim). It can contain additional information about the user.
Access Token
An access token allows access to a resource. Clients request access tokens and forward them to an API. Access tokens contain information about the client and the user (if present). APIs use that information to authorise access to their data.