Authentication & Security

Access to the web services interface is limited to the HTTPS protocol only.  The minimum supported TLS version is 1.2

Web service clients are authenticated using OAUTH2 with the OpenID Connect extension.  This allows direct machine-to-machine communication where the application is provided its own account, as well as delegated end-user access where the api may be called on behalf of an authenticated Case Manager user.

Use of the web services API is subject to the security and fair-use terms and conditions described at https://www.iizuka.co.uk/terms-and-conditions.  Failure to adhere to these terms may result in termination of access without warning.

Machine-to-Machine Access

The integrator will be provided with a client identifier and secret key.  These are confidential and must be adequately protected from unauthorised use.  Using these credentials, the application can request a time-limited access token by issuing a POST request to the OAUTH2 token endpoint at <TODO>.  The application must provide the following parameters in the request body using the application/x-www-form-urlencoded encoding:

• grant_type=client_credentials

• audience=https://<to be supplied>.casemanager.co.uk

e.g. the following curl command:

curl -X POST -u <client id>:<client secret> -d "grant_type=client_credentials" -d "audience=https://api.casemanager.co.uk/" https://<a url>

Would result in a JSON response payload with the following structure:

{
  "access_token":"<your_access_token>",
  "scope":"https://casemanager.co.uk/tenant",
  "expires_in":86400,
  "token_type":"Bearer"
}

The value of the "access_token" is used as a 'bearer' authentication token for subsequent requests to the API. Each api request has the following HTTP header added:

Authorisation: Bearer <your_access_token>

If the token has expired or is otherwise invalid you will receive an HTTP 401 response code with the following header:

WWW-Authenticate: Bearer error="invalid_token", error_description="<description of error>"

You should request another token from the token endpoint before repeating the request.

End-user access

Case Manager provides an OpenID Connect endpoint that allows a registered third-party web application to establish the identity of a Case Manager user and then optionally make requests into Case Manager as that user. If your application is purely a Case Manager front-end then you can rely on this mechanism for authentication to your portal thereby removing any need for a local user database or authentication system. If you do have a separate user database, this mechanism can be used to link together the local and Case Manager identities.

An integrating web application must implement an OpenID Connect callback endpoint. There are existing well-tested and mature libraries for most popular languages and frameworks that require very little integration effort.  It is strongly recommended that you use one of these libraries.  The OpenID Connect configuration file is available from <TODO>.

You will need to supply the callback URL to IIZUKA. In return, IIZUKA will issue an application identity, distinct from any machine-to-machine identifier you may already have been issued. This identifier is not confidential but can only be used with your application.

Authentication is initiated by redirecting the user to the Case Manager OpenID Connect endpoint described in the configuration file.  Once authentication is complete, the user will be redirected back to your callback URL.