HealthID Knowledge 102 - OIDC with HealthID

[Dhawal]

Hi All,
Welcome to next topic in HealthID Knowledge series.
Let me explain OIDC flow here while we are also creating a document for the same.
Let us agree on few terms before explaining the flow.

1. Client Application : Any application who wants to integrate with HealthID using OIDC here.
2. Redirect : Http Redirect over browser.
3. Redirect Url : An environment specific url which is shared by client application during registration process.
4. OIDC AccessToken : A short lived one-time access token created by HealthID application which can be used to get User Token.

Flow

1. User lands on client application which has option to login to healthId.
2. Upon clicking login Client Application needs to do browser redirect to https://healthidsbx.ndhm.gov.in/oidc?response_type=code&client_id=<your_client_id>&redirect_uri=<registered_redirect_url_for_clientId>&action=login
3. User will login on HealthID application and upon succesful login, Browser will redirect to redirect_url provided in Step#2 with a parameter called as accessToken (This is OIDC AccessToken).
   Example Redirect Url:
   https://<client_application_redirect_url>?action=login&accessCode=be77c31a-10ba-431e-96cc-aa5ac5ae92e3
4. Client Application will read the OIDC accessToken and then call /v2/oidc/covertCodeToToken API with OIDC accessToken recieved in step#3. Upon succesful validation (i.e. same ClientId and OIDC accessToken is not expired), it will respond with user token which can be further used to access user specific APIs under /v2/account/ like getting profile etc.

Important Notes :

1. API (/v2/oidc/covertCodeToToken) is secured in same way as all other HealthID APIs i.e. must be called with token generated from sessions API from gateway.
2. OIDC AccessToken is short-lived (5 sec in production and 5 min in sandbox), one-time usable user-specific token only.
3. You must ensure that you have correct redirect_url registered with gateway as HealthID system will validate redirect_url from gateway.
4. There is no need to implement/consume any API mentioned under /v2/oidc (except covertCodeToToken API).