Sign in journey

CIS2 Authentication conforms to the open standard OpenID Connect (OIDC). OIDC defines three types of authentication flow to cater for different client types: the Authorization Code Flow, the Implicit Flow and the Hybrid Flow. The Authorization Code Flow is the most commonly used flow and is designed for use with web applications. It is the only flow we currently support.

The following sequence diagram shows how your application interacts with CIS2 Authentication to sign in a user:

In words:

1. The user (a healthcare worker) launches the healthcare application.
2. Because the user isn't signed in, the healthcare application redirects the user's browser to CIS2 Authentication's authentication endpoint.
3. The user signs in to their CIS account (using their chosen authenticator).
4. CIS2 Authentication redirects control back to the healthcare application, with an authorisation code.
5. The healthcare application calls CIS2 Authentication's token endpoint, with the authorisation code, and receives an ID token and an access token in return.
6. Optionally, the healthcare application calls CIS2 Authentication's user info endpoint, with the access token, and receives the user information in return.

Request

To sign a user in, send their browser to our authorisation endpoint using an HTTP GET request (you must use TLS i.e. HTTPS).

To find the URL for our authorisation endpoint, discover it dynamically via the configuration document for the relevant environment.

You may generate the request either:

• indirectly via an HTTP 302 redirect response, for example in response to a user attempting to access a protected resource, or
• directly, for example as a result of a login button being selected

An example of each is given below:

The OpenID Connect Core Specification defines a number of mandatory and recommended parameters to use in the request. The minimum recommended set is as follows:

We also support the following optional parameters:

If you need to use an optional parameter not described above, contact us to discuss.

We only formally support the response_mode value of query - this is the default value so there's no need to specify it. Other response mode values are not supported and may stop working in the future.

If the user is successfully authenticated, we'll return an authorisation code to your application. This is achieved by returning an HTTP 302 redirect request to the user's browser requesting that the response is redirected to the redirection URI you specified in the authentication request.

The response will contain a code parameter and state parameter. You must ignore unrecognized response parameters.

The code parameter holds the authorisation code which is an opaque string value. You can present it to our token endpoint to obtain ID, access and refresh tokens (see below). The code is valid for 120 seconds and can only be used once.

The state parameter contains the state value provided in the original authentication request.

You must implement CSRF protection for its redirection URI. This is typically accomplished by requiring any request sent to the redirection URI endpoint to include a value that binds the request to the user-agent's authenticated state (e.g. a hash of the session cookie used to authenticate the user-agent). You should use the state parameter to achieve this as described in the OAuth 2.0 Authorization Framework. For more details, see Security considerations.

If the authentication request fails, we'll return an error response. As for a successful response this is achieved by returning an HTTP 302 redirect request to the user's browser requesting that the response is redirected to the redirection URI you specified in the request.

The response will contain error, error_description and state parameters. 

Most error codes are due to an invalid request format, for example a response_type other than code. However the following error may occur as the result of a valid request:

If the client identifier or redirection URI specified is invalid an error will be returned directly to the browser. Similarly HTTP errors unrelated to OpenID Connect will be returned to the browser using the appropriate HTTP status code.

Failure of the user to authenticate successfully, for example failure to enter valid credentials, will result in a response not being returned to your application at all.

After we redirect the user's browser to your redirection URL, you'll need to display a web page of some sort. This might be the home page of your application, or another page within your application. If we returned an error response, it might be an error page.

Depending on how your code works, your redirection URL might be displayed in the user's browser, along with the one-off authorisation code. If the user bookmarks the page, it won't work for them because in a future session the URL won't be valid.

Therefore, you should include a mechanism to ensure the URL reflect the page being displayed, and is therefore bookmarkable. For example, you could:

• redirect the user's browser to the relevant page
• return the page directly from the redirection URL but rewrite the URL using JavaScript within the web page

Request

Once you've received an authorisation code, you can request the associated ID, access and refresh tokens. Do this by sending an HTTP POST request over TLS directly to our token endpoint.

To find the URL for our token endpoint, discover it dynamically via the configuration document for the relevant environment.

You must send the following parameters, using the "application/x-www-form-urlencoded" format with a character encoding of UTF-8 in the HTTP request entity-body:

When calling our token endpoint, your application needs to prove its identity so we can be sure your request is genuine.

We provide three methods for this, as follows:

You'll need to decide which method to use, and tell us about it when you register to access an environment.

Authentication JWT

For both the private key JWT and client secret JWT mechanisms, you must construct a JWT that must contain the following required claim values and may contain the following optional claim values:

The JWT may contain other claims. Any claims used that are not understood will be ignored.

Private key JWT

For private key JWT authentication, you must sign the JWT using a private key owned by you.

The example below shows the use of a JWT signed with a private key to authenticate (in this example the JWT value has been abbreviated).

The JWT consists of three Base64URL encoded elements separated by a . character. The first element is the token header. Decoding the value from the example above gives the following JSON document object:

This specifies that the token has been signed with ECDSA utilising a P-256 curve and SHA-256 hash algorithm using the key identifier 16.

Decoding the second element would give the JSON object containing the claims about your application, such as the client identifier and expiration date.

The third element is the signature. We advertise our supported signing algorithms via our configuration documents as described in Discovery - for client authentication, these are listed in the token_endpoint_auth_signing_alg_values_supported field.

For details on how to use a JSON Web Key Set Endpoint to publish the details of the key associated with kid, see Key management.

Client secret JWT

For client secret JWT authentication, the JWT is signed using an HMAC SHA algorithm, such as HMAC SHA-256. The HMAC (Hash-based Message Authentication Code) is calculated using the octets of the UTF-8 representation of client_secret as the shared key.

If the request validation is successful, we'll return an HTTP 200 OK response including ID, access and refresh tokens as in the example below:

The response body will include the following parameters:

ID token

The ID token is a security token that contains claims about the user's authentication. It is represented as a JWT as described in the JSON Web Token Specification and is signed using JWS as described in the JSON Web Signature Specification.

The ID token consists of three Base64URL encoded elements separated by a . character. The first element is the JOSE (JSON Object Signing and Encryption) header describing the signing algorithm used, the second element contains the claims and the third the signature.

You can decode JWTs for inspection using an online website such as https://jwt.io/.

This specifies that the token has been signed with an RSA Signature utilising the SHA-256 hashing algorithm and the key identified by the string b/O6OvVv1+y+WgrH5Ui9WTioLt0=. For details on how to obtain the public key associated with kid, see Key management.

Decoding the second element gives the JSON object containing the claims about the user's authentication. For example:

The third element is the signature for the JSON object. For details on how this signature is created and how to validate it, see the JSON Web Signature Specification.

The ID token contains the following claims of interest.

Any claims contained in the ID token other than those listed in the table above must be ignored.

You must validate the ID token as follows:

1. The value of the iss claim must exactly match our Issuer identifier as specified in the relevant configuration document (see Discovery for more details).
2. The aud claim must contain your client identifier.
3. If the ID token is received via direct communication between your application and our token endpoint, then TLS server validation may be used to validate the issuer in place of checking the token signature (see TLS requirements). You must validate the signature of all other ID tokens according to  JSON Web Signature Specification using the algorithm specified in the JWT alg header parameter. You must use the keys provided by us as described in Key management section. 
4. The current time must be before the time represented by the exp claim.
5. If a nonce parameter was sent in the authentication request, a nonce claim will be present and its value must be checked to verify that it is the same value as the one that was sent in the authentication request. You should check the nonce value for replay attacks. 
6. If the acr claim was requested, you should check that the asserted claim value is appropriate for your use case. For details, see the Authenticator guidance for developers.
7. You should check the auth_time claim value and request re-authentication if you determine too much time has elapsed since the last user authentication. For further guidance, see Session management.

You may validate the integrity of the access token using the value of the at_hash claim. Its value is the Base64URL encoding of the left-most half of the hash of the octets of the ASCII representation of the access_token, where the hash algorithm used is the hash algorithm used in the alg parameter of the ID token's JOSE header. The alg value is always RS256 so to obtain the value, hash the access_token value with SHA-256, then take the left-most 128 bits and Base64URL-encode them.

If your token request is invalid or unauthorized, we'll return an HTTP 400 response as in the following example:

The ID token retrieved above only contains claims about the authentication event and the identity of the user. You can get other information about the user from our user info endpoint.

To find the URL for our user info endpoint, discover it dynamically via the configuration document for the relevant environment.

You can call our user info endpoint using either HTTP GET or HTTP POST. You must send the access token you obtained from the token endpoint as a 'bearer token'.

We recommend that you use HTTP GET and the access token be sent using the Authorization header as in the example below:

We'll return the user info claims as a JSON document in an HTTP 200 OK response as in the example below:

The user info claims will always include a sub claim. You must verify this check it exactly matches the sub claim in the ID token; if they do not match, you must not use the user info response values.

You should authenticate the OpenID provider either by checking the TLS certificate (see TLS requirements) or by validating the signature of the JWT if provided. For details on how to obtain a signed user info response see the next section.

The claims you receive depend on the scopes you requested (via the scope parameter when you made the authentication request).

For details of the scopes and claims for the user info endpoint, see Scopes and claims.

During registration, you may request that the user info response is signed, in which case the user info response:

• will be a signed JWT containing the claims, rather than a JSON document
• will contain iss and aud claims

You should validate:

• the signature according to the JSON Web Signature Specification - see Key management for details
• that the iss value matches our issuer identifier
• the aud claim matches your client identifier

When a request fails, we'll respond with the appropriate HTTP status code (typically, 400, 401, 403, or 405) and include an error code in the response.

The response will contain error and error_description fields.

You should only require access to the user info endpoint at the time of the original user authentication. This should only happen once as part of the authentication journey and you can use the access token immediately and the discard it. You should have no other need to retrieve the user info after this point in time. 

Therefore the use of the refresh token to obtain a new access token is not recommended.

If you do want to use the refresh token, contact us to discuss your use case.