Authentication & Authorisation
Note
To request access to the GMS CIP-API please refer here
Attention
It is highly recommended that the client credentials flow is used for system<->system queries.
E.g. If you are configuring a TPI tool to communicate to the CIP-API, please use this method.
Only use the get-token endpoint in the CIP-API for authentication if you are planning to only use ad hoc scripts
on your local machine.
Client Credentials Flow Authentication with AD¶
Attention
LDAP authentication in the CIP-API is no longer available
Authentication in the CIP-API is manged by Microsoft Azure AD.
A Third Party Integrating (TPI) system, will have one client_id, and one client_secret for a specific Azure AD tenant.
The token retrieved from the AD can be universally used for the following applications:
- GMS CIP-API
- GMS OpenCGA
- GMS Sample Matching Service (SNP Service)
- GMS re-identification Service
Each application will authorise uniquely, but will accept the JWT token as a Bearer token in the header of any request.
The systems do not need to login to any of these applications specifically. Instead, the systems need to authenticate to the AD tenant, retrieve the token, and then query directly to any desired endpoint in these applications with the token in the header of the request.
Authentication¶
The authentication method is based on a Bearer Token present in the header of each request. This token will have an expiration time, clients should get a new one when this happens. The Authentication flow we will be using is called OAuth 2.0 Client Credentials Grant Flow. You can review this in the official documentation
The OAuth 2.0 Client Credentials Grant Flow permits a web service (confidential client) to use its own credentials instead of impersonating a user, to authenticate when calling another web service.
In this scenario, the client is typically a middle-tier web service, a daemon service, or web site. For a higher level of assurance, Azure AD also allows the calling service to use a certificate (instead of a shared secret) as a credential.
Client Creds flow summary¶
- The client application authenticates to the Azure AD token issuance endpoint and requests an access token.
- The Azure AD token issuance endpoint issues the access token.
- The access token is used to authenticate to the secured resource.
- Data from the secured resource is returned to the client application.
In the example above, the client application is e.g. a GeL2MDT application; and the Resource Web API is the CIP-API.
Obtaining a token¶
Only applications that have been through the NGIS TPI Onboarding Process can obtain a token
Clients need both a client_id (appid) and a client_secret, both of them will be long-lasting, clients won't need to update them unless Genomics England consider they are compromised or they are about to expire - in this case Genomics England will ensure this is communicated within a reasonable window.
The following examples have been created using Genomics England non-prod AD tenant
Warning
Content-type: application/x-www-form-urlencoded method for passing client_id and client secret
e.g. curl equivalent of curl -F 'grant_type=client_id={client_id}&client_secret={client_secret}')
is not stable with the current GeL AD client creds flow due to specific characters in some of the generated
client_id and client_secret values.
Therefore, please use the following examples with Basic Auth with base64 encoding in the header instead.
See Basic Auth documentation here: https://en.wikipedia.org/wiki/Basic_access_authentication
The method to get the token is described in this link and a working example in different programming languages, can be found below:
Curl
curl -X POST \
https://login.microsoftonline.com/afee026d-8f37-400e-8869-72d9124873e4/oauth2/token \
-H 'Accept: application/json' \
-H 'Accept-Encoding: gzip, deflate' \
-H 'Authorization: Basic OWQ0ODYzYjEtYmU4ZC00ZTMyLWFmOTktNDM1NWVasdsadZUWVBPdWJQdUliUUYyTUJFL1VrSHVEdzNuUWZvSGlWdTNPVlJ6TkdrZWM9' \
-H 'Cache-Control: no-cache' \
-H 'Connection: keep-alive' \
-H 'Content-Type: multipart/form-data; boundary=--------------------------052831142206095611213706' \
-H 'Host: login.microsoftonline.com' \
-F grant_type=client_credentials
This python example passes the client_id and client_secret as base64 encoded as a "Authorisation: Basic " header.
import requests
client_id = "ad-client-id-here"
client_secret = "ad-client-secret-here"
tenant_id = "ad-tenent-id-here"
url = "https://login.microsoftonline.com/{tenant_id}/oauth2/token".format(tenant_id=tenant_id)
payload = "grant_type=client_credentials"
headers = {
'Content-Type': "application/x-www-form-urlencoded",
}
response = requests.request("GET", url, data=payload, headers=headers, auth=(client_id, client_secret))
print(response.text)
Azure AD Non-Production Host¶
This Azure AD host is used in UAT environment instance.
Azure AD Host Information For Non-Prod/E2E/Alpha Release
----------------------------------------------------------------------------------------
Tenant ID: afee026d-8f37-400e-8869-72d9124873e4
Tenant Name ngisnonprod.onmicrosoft.com
Discovery Document URL https://login.microsoftonline.com/afee026d-8f37-400e-8869-72d9124873e4/.well-known/openid-configuration
Authorization End point https://login.microsoftonline.com/afee026d-8f37-400e-8869-72d9124873e4/oauth2/authorize
Token Endpoint https://login.microsoftonline.com/afee026d-8f37-400e-8869-72d9124873e4/oauth2/token
Key Endpoint https://login.microsoftonline.com/common/discovery/keys
----------------------------------------------------------------------------------------
Azure AD Host Client Credentials Response Example¶
The JWT contains very little information about the application other than some basic info such as 'AppID' that can be used to perform authorisation. You can decode the access_token with any JWT decoder e.g. https://jwt.io/
Example POST Response from AD Host
+-----------------------------------------------------------------------+
| {\ |
| "token\_type": "Bearer",\ |
| "expires\_in": "3600",\ |
| "ext\_expires\_in": "3600",\ |
| "expires\_on": "1554737233",\ |
| "not\_before": "1554733333",\ |
| "resource": "00000002-0000-0000-c000-000000000000",\ |
| "access\_token": |
| "eyJ0eXAiOiJKV..."\ |
| } |
+-----------------------------------------------------------------------+
Example Client Credentials JWT Access Token
+-----------------------------------------------------------------------+
| { |
| "aud": "00000002-0000-0000-c000-000000000000",\ |
| "iss": |
| "<https://sts.windows.net/99515578-fda0-444c-8f5a-2005038880f2/>",\ |
| "iat": 1554733333,\ |
| "nbf": 1554733333,\ |
| "exp": 1554737233,\ |
| "aio": "42ZgYHj4fm/p0X2W/y7cflZ8Le7EPgA=",\ |
| "appid": "4595462a-dcb7-414d-9cf1-2c32b7187f41",\ |
| "appidacr": "1",\ |
| "idp": |
| "<https://sts.windows.net/99515578-fda0-444c-8f5a-2005038880f2/>",\ |
| "oid": "bdb378f2-ddba-4b7d-b9c2-f1104f5daf8d",\ |
| "sub": "bdb378f2-ddba-4b7d-b9c2-f1104f5daf8d",\ |
| "tenant\_region\_scope": "EU",\ |
| "tid": "99515578-fda0-444c-8f5a-2005038880f2",\ |
| "uti": "Q5IsMin5DEOyU1F9jfAuAA",\ |
| "ver": "1.0"\ |
| } |
+-----------------------------------------------------------------------+
Note
The 'appid' claim indicates the unique identifier of the application.
E.g. one specific TPI application at one specific Trust/Lab/GLH.
Example: how to Use AD client credentials and query the CIP-API¶
Please go the following jupyter notebook to test how to access the CIP-API using client credentials AD auth flow: https://github.com/genomicsengland/ACGS_GeL_API_workshop/blob/master/gms_integration/gms_authentication.ipynb
Authorisation¶
Azure Active Directory User groups and Roles (GMS and 100K)¶
In 100K, all clinical users (Clinical Scientists and Clinical Managers at the GMC) can only see cases that are specific to their set of labs (local delivery partners, LDPs) in their respective GMC. This will remain the same.
In the GMS, a Clinical Scientist and Clinical Manager can see any referral that belongs to their country (England, Wales, Northern Ireland, Scotland).
Depending on the attributes of the users, specific authorisation will be granted in the CIP-API, every user will have a role which will determine what can they get.
Only the following roles will be allowed to retrieve data from the CIP-API:
| Role ID | Description | Notes |
|---|---|---|
| NCR003 | Clinical Scientist | Ability to read from the bioinformatics applications (interpretation portal, CIP-API, OpenCGA, CVA) in GMS and also 100k if having particular attributes. |
| NCR004 | Clinical Manager | Same permissions as NCR003 above. |
| NNR501 | GEL Users | Internal Users to GeL. |
| NNR502 | 3rd Party Clinical User | DSSs, 3rd Party Interpretation Services (e.g. a real DSS user troubleshooting their system and front end from a test environment). Note: these users will have strict permissioning based on group membership. |
| NNR503 | 100K Legacy Users | These are users which will not be able to see any GMS cases, but will be part of new Azure AD instance. Only 100K data that is part of the LDPs of the "primaryLdpCode100k" and "secondaryLdpCodes100k" attributes will be available. |
| NNR504 | NHS Management | This is a management role where everything is read only, but will be used for audit purposes.Currently undecided if bioinformatics audit is also required. |
Azure Active Directory Client Credential Authorisation (GMS and 100K)¶
All systems which authenticate via client credentials flow will be uniquely registered in CIP-API, CVA, OpenCGA, etc. S
ystem accounts do not have any user attributes, such as Role (e.g. Clinical Scientist) or other attributes
e.g primaryEntityCodeNgis. Therefore, each GMS application will authorise these clients by their client appId or
client oid from their JWT bearer token.
For example, a TPI system will have the following rights in the CIP-API:
- GET all endpoints --> Retrieve any data in cipapi-gms-beta
- POST clinical-report --> Add a Summary of Findings to a case
- PUT exit-questionnaire --> Add an exit questionnaire to a case
- PUT interpretation-request/{ir_id}/{ir_version}/snp_check/{sample_id} --> Re-run sample matching service for a given sample