Relying Party

A relying party refers to a service provider that relies on an eSignet based identity provider for authentication and identity verification. This enables users to provide their identity details/ biometrics securely and conveniently to access the services provided by the relying party.

Getting Started

This guide helps the developers of the relying party to get started with their development environment.

Pre-requisites

Setup your development machine:

• Choose the technology stack (PHP, Python, Java, Node, Kotlin, Swift etc).

• Choose the OpenId plugins for the respective technology stack.

• Choose the JWT plugins for the respective technology stack.

• Create the keys (a password-protected private key & store it safely).

  Please do not use the same key for production. Its extremely dangerous. Create keys in safe production-grade hardened machines/vault/HSM.

• Design your callback API. The callback API is redirected by eSignet over the user's browser upon successful authentication. As best practice please ensure the callback API can render the UX as soon as possible so the user is aware of the progress. Please note that the user is redirected on both success and failure authentication. On failure, the user will be redirected without an auth-code. So based on the authentication response relying party portal needs to take the necessary action before allowing the user to move forward.

Register / Onboard as OIDC client with ID provider

Once the above steps are completed the relying parties developers/managers are required to follow these steps:

• Work with the respective ID provider (eSignet provider) and request a client ID. You would need to share your public key to obtain your client ID. It is the same public key created in the above steps.

• Provide the name that you want to register with the ID provider, the same name will be displayed on the eSignet authentication and consent page to the end user.

• List the fields/attributes that you need from the eSignet ID provider upon the user’s consent. This is also called a claim. It's expected that the relying party indicates the mandatory and optional claims. The possible values can be discovered from the eSignet .well-known.

• Provide the logo for your application and organization to be utilized for display on the eSignet authentication page.

• Provide any of the following callback URL patterns for local development & QA.

    http://localhost:<portnumber>/*

    http://127.0.0.1:<portnumber>/*

    http://ipaddrress-of-your-server:portnumber/*

    my.phone.app://oauth/*

These callback URL are for development purpose and choose them according to the URL in your development/qa environment. As much as possible * should avoided as it could result in security issues. For development its ok to provide the * as above. For the phone app the app callback deeplink should be provided. The following are the unsupported URL patterns.

  \\*
  
  http*
  
  https://*
  
  https://domain*
  
  residentapp://*

• Upon receiving the above information the ID provider should be able to process the request and provide you back with the client ID.

The eSignet providers may have additional non-technical requirements. Those are specific to the provider. This document will not cover those.

Development of Relying party application

Setup your development environment. Once done you need to follow the following steps

• Invoking eSignet authorize URL

  • Add a button on your login screen. The button might have standards in terms of logo, colour, and size. The ID provider usually provides these guidelines.

Here is the UI storybook deployed by eSignet which can help relying party developers build the buttons for their website.

• The button upon click should get a unique state (a random value) & nonce (a random value) from the server and redirect to the "/authorize" endpoint of the ID provider. A sample URL is listed here. The details of what is supported are listed on the .well-known file in the respective eSignet provider.

  • Sample /authorize Request:

    GET https://esignet.id.provider.domain.name/authorize?nonce=ere973eieljznge2311&state=eree2311&client_id=Mv45rBnfuu0ocWDy9APT5k5LZbGE_l0wX7P9vQXXswg&redirect_uri=https://relyingparty.dev.net/userprofile&scope=openid profile&response_type=code&acr_values=mosip:idp:acr:generated-code mosip:idp:acr:biometrics mosip:idp:acr:linked-wallet&claims={"userinfo":{"given_name":{"essential":true},"phone_number":{"essential":false},"email":{"essential":true},"picture":{"essential":false},"gender":{"essential":false},"birthdate":{"essential":false},"address":{"essential":false}},"id_token":{}}&claims_locales=en&display=page&ui_locales=en-US

Authorization Endpoint

This is the authorize endpoint of Open ID Connect (OIDC). The relying party applications will do a browser redirect to this endpoint with all required details passed as query parameters.

This endpoint will respond with a basic HTML page to load a JS application in the browser. UI JS application will then echo all the query parameters received in this endpoint to the "/authorization/oauth-details" endpoint as the request body.

Authentication & Authroization: None

GEThttps://esignet.collab.mosip.net/v1/esignet/authorize

Query parameters

Response

200

OK

Loads JS application, and validates the provided query parameters using oauth-details endpoint.

Request

JavaScriptCurlPython

const response = await fetch('https://esignet.collab.mosip.net/v1/esignet/authorize?scope=openid&response_type=code&client_id=text&redirect_uri=https%3A%2F%2Fexample.com', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

• This will navigate the user to the ID provider’s eSignet UI screen for the authentication page. If you have reached here and there is no error on the screen then congrats on your achievement.

• Now the user is expected to enter his credentials on eSignet. Upon success or cancellation, the user's browser will be redirected to the approved callback URL.

• Callback

  • The callback URL is the landing page/URL after the completion (Success|Failure) of authentication. The relying party developers are requested to provide this callback URL. The following signatures apply for the same.

https://relyingparty.domain.name/callbackurl?state=same-that-you-supplied&nonce=same-that-you-supplied&code=authorization_code&error_description=in_case_of_error_this_is_sent&error=error_code

https://relyingparty.domain.name/callbackurl is based on the domain pattern you sent during OAuth client registration.

• Once the redirection happens the relying party is expected to perform the following

  • Send the state to the server. Validate if they are the same as expected. The server should also ensure the combination of state is valid.

  • On Success, proceed with exchanging authorization code for access token using token endpoint.

  • On failure, use the error and error description to decide on the user flow in your portal.

• Exchange authorization code for Access token using token endpoint.

  • Token endpoint should include client_assertion (JWT signed using OAuth Client private key). As this needs a private key to build the request, we suggest relying party should delegate token request to backend server.

  • eSignet only supports private_key_jwt client authentication method.

  • The server should generate a JWT with the following payload.

    {
    "iat": <current time>,
    "nbf": <current time>,
    "exp": <1-6 minutes from current time>,
    "jti": <random nonce>,
    "sub": <client id>,
    "iss": <client id>,
    "aud": <id provider domain uri's token end point>
    }

Token Endpoint V2

POSThttps://esignet.collab.mosip.net/v1/esignet/oauth/v2/token

Body

application/x-www-form-urlencoded

grant_type*enum

Authorization code grant type.

authorization_code

code*string

Authorization code, sent as query param in the client's callback URI.

client_idstring

Client Id of the OIDC client.

client_assertion_type*enum

Type of the client assertion part of this request.

urn:ietf:params:oauth:client-assertion-type:jwt-bearer

client_assertion*string

Private key signed JWT, This JWT payload structure is defined above as part of request description.

redirect_uri*string

Valid client redirect_uri. Must be same as the one sent in the authorize call.

code_verifierstring

A cryptographically random string that is used to correlate the authorization request to the token request.

Response

200400

OK

Headers

Body

application/json

id_tokenstring

Identity token in JWT format. Will have the below claims in the payload.

It is non-null only in OIDC flow. otherwise the id_token is not returned.

access_token*string

The access token in JWT format. This token that will be used to call the UserInfo endpoint.

token_type*enum

The type of the access token, set to Bearer

Bearer

expires_in*number (duration)

The lifetime of the access token, in seconds.

c_noncestring

This is returned only when authorize request was sent with VC scope. This is a string containing a nonce to be used to create a proof of possession of key material when requesting a Credential.

c_nonce_expires_innumber

This is returned only when authorize request was sent with VC scope. This is integer denoting the lifetime in seconds of the c_nonce.

Request

JavaScriptCurlPython

const response = await fetch('https://esignet.collab.mosip.net/v1/esignet/oauth/v2/token', {
    method: 'POST',
    headers: {
      "Content-Type": "application/x-www-form-urlencoded"
    },
    body: JSON.stringify("--data grant_type=authorization_code --data code=tyemdnjdfornfedg --data client_id=WMX5pO6dYdCFR3iaVWGclVPNxTNSADDv-kV7VBcnzvY --data client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer --data client_assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2OTg2MzE0NjAsIm5iZiI6MTY5ODYzMTQ2MCwiZXhwIjoxNjk4NjMxNTI1LCJqdGkiOiI1ZFFjaWhtb2lfQTlXMmlERGpYcDgiLCJzdWIiOiJXTVg1cE82ZFlkQ0ZSM2lhVldHY2xWUE54VE5TQUREdi1rVjdWQmNuenZZIiwiaXNzIjoiV01YNXBPNmRZZENGUjNpYVZXR2NsVlBOeFROU0FERHYta1Y3VkJjbnp2WSIsImF1ZCI6Imh0dHBzOi8vZXNpZ25ldC5jb2xsYWIubW9zaXAubmV0L3YxL2VzaWduZXQvb2F1dGgvdG9rZW4ifQ.G-OxPmb2wBq7R52PELNss9FCwvv_i2456FE4oag25BuZjwH6CgB8LDLmfCJdzeLGRuFp_MrKskGTkpsWI0RWLNtqZ7jvQTvSq8zQICusIFh9kcciWbkMsOZQqN91gPtdrn3WRS6xD7TxzwvrAeuqx4lTBbWNYTF2GQ3Zagq0t6ogOtPWg0wNioW3m11jWIdwooJ8jI2Z5oN772Lerrs1AXMnipLxQm4rdMM54taeHFrrXyxqFjoiq-bglrpHtCqeG6QFqhpQrRlIsLLoli8F1LU8Mu3Fw7ifCd6KEj9JNM_sPHjAy-JRg_dgjNdHL5tqtHzUsD5sSmLop33U4WH3Ow --data redirect_uri=https://relyingparty.doman.name/callbackurl --data code_verifier=MN1Q0nNAKkqOu5EaNBKf2gYD4maYv9ZxLd-48N2_kTM"),
});
const data = await response.json();

Response

200400

{
  "id_token": "text",
  "access_token": "text",
  "token_type": "Bearer",
  "expires_in": 0,
  "c_nonce": "text",
  "c_nonce_expires_in": 0
}

• Sample ID token JWT header and payload

    header: 
    {
      "kid": "NOt7BZBkG4nAAX0vE_-S4wT8S5cKUqDTLPOyaTJAu_w",
      "alg": "RS256"
    }
  
    payload: 
    {
      "at_hash": "ggJyqKcuYHdwARpWzeHKMMgDdRRNe61oN6O7xzEuyiY",
      "sub": "268524736272681240519736297238054502",
      "aud": "yzLgU7sj8fr2qcqL-MZjwYnl-5ADiClp7Ycj8LiUV5I",
      "acr": "mosip:idp:acr:generated-code",
      "auth_time": 1672759590,
      "iss": "https://esignet.id.provider.domain.name",
      "exp": 1672766837,
      "iat": 1672759637,
      "nonce": "973eieljzng"
    }

• Sample Access token JWT header and payload

  header:
  {
  "kid": "NOt7BZBkG4nAAX0vE_-S4wT8S5cKUqDTLPOyaTJAu_w",
  "alg": "RS256"
  }
  
  payload:
  {
  "sub": "268524736272681240519736297238054502",
  "aud": "yzLgU7sj8fr2qcqL-MZjwYnl-5ADiClp7Ycj8LiUV5I",
  "iss": "https://esignet.id.provider.domain.name",
  "exp": 1672766837,
  "iat": 1672759637
  }

• If the developer is only interested in login/verify then we could consider the return of access token as a successful login. The remaining steps are optional.

The access token & ID token are considered as a piece of confidential information and its expected to be kept safe by the relying party.

• Get userinfo with access token

  • In case the developer is interested in the user’s information (eKYC) like given_name or anything that the claim has then Using the access token you can call the user info endpoint to get the user information as a signed JWT.

UserInfo Endpoint

Once the access token is received via the token endpoint, relying party backend application can call this OIDC compliant endpoint to request for the user claims.

Consented user claims will be returned as a JWT. This JWT will be a nested JWT which is a signed using JWS and then encrypted using JWE.

Example: Assuming the below are the requested claims by the relying party

name : { "essential" : true }

phone: { "essential" : true }

Response 1: When consent is provided for both name and phone number:

{ "name" : "John Doe", "phone" : "033456743" }

Response 2: When consent is provided for only name:

{ "name" : "John Doe" }

Response 3: When Claims are requested with claims_locales : "en fr"

{ "name#en" : "John Doe", "name#fr" : "Jean Doe", "phone" : "033456743" }

Supported User Info Claims

GEThttps://esignet.collab.mosip.net/v1/esignet/oidc/userinfo

Authorization

Authorization-access_token

Response

200401

OK

Body

application/jwt

string (jwt)

The response is signed and then encrypted, with the result being a Nested JWT. Signed using the authentication system's private key. Signed full JWT will then be encrypted using OIDC client's public key.

Request

JavaScriptCurlPython

const response = await fetch('https://esignet.collab.mosip.net/v1/esignet/oidc/userinfo', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

200

text

• User info endpoints response example listed below:

  Example 1: 
  
  {
    "sub": "63EBC25D699305A26EE740A955852EAB2E6527BFF2F5E9E5562B502DACECD020",
    "address": {
      "street_address": "#991, 47 Street, 6 block",
      "country": "KTA",
      "locality": "KNT",
      "region": "RSK",
      "postal_code": "14022"
    },
    "gender": "Male",
    "phone": "91600395660",
    "name": "Manoj",
    "email": "[e-mail]"
  }
  
  Example 2: 
  
  {
    "sub": "63EBC25D699305A26EE740A955852EAB2E6527BFF2F5E9E5562B502DACECD020",
    "name#en": "Manoj",
    "address#en": {
      "formatted#en": "#991, 47 Street, 6 block"
    },
    "phone": "91600395660",
    "gender#kn": "ಗಂಡು",
    "name#kn": "ಮನೋಜ್",
    "address#kn": {
      "formatted#kn": "#991, 47 ಸ್ಟ್ರೀಟ್, 6 ಬ್ಲಾಕ್"
    },
    "gender#en": "Male",
    "email": "[e-mail]"
  }

eSignet by design does not maintain any session. So the entire session management and logout are features beyond what eSignet supports.

Key pair creation for registering OAuth client

openssl genrsa -aes256 -out esignet_private.pem 2048

The above command would ask you for a passphrase. Please provide a complex passphrase and ensure that it's remembered safely. Ensure to regenerate a new key when you go live the first time and keep the password/keys only on the server/HSM with restricted access.

openssl rsa -pubout -in esignet_private.pem -out esignet_public.der

The above command would extract the public key to esignet_public.der file. When prompted for password, enter the same passphrase as before.

Tools to convert Public key to JWK format

Use any of the online platforms or tools of your choice to convert the esignet_public.der to JWK format. You can open the file in any text editor and copy its contents and use the tools listed below to conver to JWK.

• install pem-jwk tool

• Use the below command to convert public key in PEM format to JWK

pem-jwk esignet_public.der > ./esignet_public.jwk

Other online tools are listed below:

• https://pem2jwk.vercel.app/

• https://8gwifi.org/jwkconvertfunctions.jsp

• https://irrte.ch/jwt-js-decode/pem2jwk.html