Information and public services for the Island of Guernsey

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.

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:

  1. Client prepares an authentication request containing the desired request parameters.
  2. Client sends the request to the OpenID Connect provider.
  3. OpenID Connect provider authenticates the user.
  4. OpenID Connect provider sends the user back to the client with an ID token and, if requested, an access token.
  5. 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:

  1. Client prepares an authentication request containing the desired request parameters.
  2. Client sends the request to the OpenID Connect provider.
  3. OpenID Connect provider authenticates the user.
  4. OpenID Connect provider sends the user back to the client with an authorisation code.
  5. Client sends the authorisation code to the OpenID Connect provider to receive an access token and ID token in the response.
  6. 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:

  1. Client prepares an authentication request containing the desired request parameters.
  2. Client sends the request to the OpenID Connect provider.
  3. OpenID Connect provider authenticates the user.
  4. 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.
  5. Client sends the authorisation code to the OpenID Connect provider to receive an access token and ID token in the response.
  6. 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

Application architecture

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.