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

get

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

Query parameters

scopestring · enum · default: openidrequired

Specifies what access privileges are being requested for Access Tokens. The scopes associated with Access Tokens determine what resources will be available when they are used to access OAuth 2.0 protected endpoints. OpenID Connect requests MUST contain the OpenID scope value. Developers who are interested in VCI flow should use the VC scope without opendid scope, For example 'mosip_identity_vc_ldp'

Options: openid, profile, email, phone, address

response_typestring · enumrequired

The value set here determines the authorization processing flow. To use the Authorization Code Flow, the value should be configured to "code".

Options: code

client_idstring · max: 256required

Valid OAuth 2.0 Client Identifier in the Authorization Server.

redirect_uristring · urirequired

The redirect URI is the callback URL of your application. This URI must match one of the redirection URI values during the client ID creation. The callback is the URL where the relying party wants to be redirected upon successful or failed authorization. In case of a development environment please use the http://localhost:<portnumber>/url-to-callback. Most often the URL is expected to load the user interface to keep the user informed of the action that's taking place.

statestring · max: 256

Opaque value used to maintain state between the request and the callback. Typically, Cross-Site Request Forgery (CSRF, XSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie.

noncestring

String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token.

ui_localesstring

End user's preferred languages and scripts for the user interface, represented as a space-separated list of BCP47 [RFC5646] language tag values, ordered by preference. For instance, the value "fr-CA fr en" represents a preference for French as spoken in Canada, then French (without a region designation), followed by English (without a region designation). An error SHOULD NOT result if some or all of the requested locales are not supported by the OpenID Provider.

acr_valuesstring

Space-separated string that specifies the acr values that the Authorization Server is being requested to use for processing this Authentication Request, with the values appearing in order of preference. The possible values can be discovered from the eSignet .well-known. The acr_values are used to force the eSignet the preferred authentication mechanism. In case you need only biometric authentication then you can specify the acr_values as "mosip:idp:acr:biometrics" This will ensure to show only the biometric authentication to the user and would provide no other alternative login mechanism.

claims_localesstring

End-User's preferred language for Claims being returned, represented as a space-separated list of BCP47 [RFC5646] language tag values, ordered by preference. An error SHOULD NOT result if some or all of the requested locales are not supported by the OpenID Provider.

claimsstring

This parameter is used to request specific claims to be returned. The value is a JSON object listing the requested claims. The claims parameter value is represented in an OAuth 2.0 request as UTF-8 encoded JSON. The same is displayed to the end user during consent. This has to be in line with the approval that you received at the end of the client Id creation with the ID provider.

code_challengestring

A challenge derived from the code_verifier, This is required if its a VC scoped request.

code_challenge_methodstring

A method that was used to derive code challenge, This will be required if code_challenge is provided.

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://esignet.collab.mosip.net/v1/esignet/authorize?scope=openid&response_type=code&client_id=text&redirect_uri=https%3A%2F%2Fexample.com'

200

200

No body

OK

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

• 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 the authorization code for an access token using the token endpoint.

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

• Exchange authorization code for an Access token using the token endpoint.

  • The 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 the relying party should delegate the token request to the backend server.

  • eSignet only supports private_key_jwt client authentication methods.

  • 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

post

Body

grant_typestring · enumrequired

Authorization code grant type.

Options: authorization_code

codestringrequired

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

client_idstring

Client Id of the OIDC client.

client_assertion_typestring · enumrequired

Type of the client assertion part of this request.

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

client_assertionstringrequired

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

redirect_uristringrequired

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.

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://esignet.collab.mosip.net/v1/esignet/oauth/v2/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --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

200

400

200

{
  "token_type": "Bearer",
  "access_token": "eyJraWQiOiJLT19tVHBfc1QwemxGRVVkX25UdGhmbzl0RTlTX21GQnJ6OTFwZjd5RFFBIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJQVlJtZkRwZ1pKcXZMTWZZcTZwcUItTDNZQTZXR3dYZmxiTlJpVWF6THJjIiwiYXVkIjoiaHR0cHM6XC9cL2VzaWduZXQtbW9jay5jb2xsYWIubW9zaXAubmV0XC92MVwvZXNpZ25ldFwvdmNpXC9jcmVkZW50aWFsIiwiY19ub25jZV9leHBpcmVzX2luIjo0MCwiY19ub25jZSI6IkN0OXJwUUZiOTZRU1N3Z0hBZkRPIiwic2NvcGUiOiJzYW1wbGVfdmNfbGRwIiwiaXNzIjoiaHR0cHM6XC9cL2VzaWduZXQtbW9jay5jb2xsYWIubW9zaXAubmV0XC92MVwvZXNpZ25ldCIsImV4cCI6MTY5ODYzNTczOSwiaWF0IjoxNjk4NjMyMTM5LCJjbGllbnRfaWQiOiI4OFZqdDM0YzVUd3oxb0oifQ.EAWkcaDUTMH1FcrXdsj4s-y9t8gVB1YBiIZ6VqZD3ZSGR3OrkIQUN2y8vbtvXJv8WAVV_0pvphFjIa9gVRP63_vdZipJ3h04vYcpyfTn50Yml-77uhB_JgHeQWZ0rnCQ1LQGSdSYKro9A1smevVCb1vyPf6QoQPumzKHJ9Jg7SojyhXON2sdIn94Xc5-gok-jGQEapbIBm3RhUEsFPGl7MjaMqBpodV-JOuEi0j_7VfxhLTXXoYZm_-h2aZCWJ9MQDtUC8TwNp-ap5f-O4lQx_M79jyn2mXa0NtoPPIQeffnCPq-uS43C0LZ9CQTfwIC4xV8-x2ema2fHWvtebSsmQ",
  "expires_in": 3600
}

OK

• 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 the 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

get

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

<ul> <li>sub - Partner Specific User Token (PSUT)</li> <li>name</li> <li>address</li> <li>gender</li> <li>birthdate</li> <li>profile photo</li> <li>email</li> <li>phone</li> <li>locale</li> <li>Custom - individual_id (You share this claim as a system-level config and it can be UIN, perceptual VID or temporary VID)</li> </ul>

Authorizations

Responses

application/jwt

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://esignet.collab.mosip.net/v1/esignet/oidc/userinfo' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

401

200

eyJraWQiOiJlU0dtNm5LcGppUHRJMnAzbVVWNHBWWm9nY0VHaExMV2dCNXNuUzNvbUNzIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiIyNTgwMDg2NDcxMDgzMDEzNjAzMjA2NDYwMDYwMDU4NDE3NTEiLCJhZGRyZXNzIjp7ImxvY2FsaXR5IjoiUmFiYXQgIn0sIm5hbWUiOiJhcnZpbmQiLCJwaG9uZV9udW1iZXIiOiI3ODY0ODQ2MzQzIiwiZW1haWwiOiJhcmF2aW5kaDIwOTBAZ21haWwuY29tIn0.WqkXaalFJu1nzAgoSmLKOHddX7_tkgcTEZRK8uedfl6rbNRZ7Lv0uayTT--3r4Z0Wlnjh1pUMreFvKd1yfirIf0LaPvuTBe5AVRRUMGPhPkSCq_ietytg75uNUH-Z91jLluh8mIZ5BlsGf_MfdkKD10pvzG9cWowWeWlD2hj-YNw05SUAdvZtHeN8ayMTaPOa-Jc0Sv3kXS0xM6Geizq5QCpIWaavZNw9GJF8GEizGK3klq3od9PfHKrh8XruUFM849iyAShIUTgr9mFlWzHVuTqbpcc2ZptLY_egOq8qKA5guBEplB92PlaxQQeyxRvMezZtDiRdzf5BSpM_1ok0g

OK

• User info endpoints response example is 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 the 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 convert to JWK.

• install pem-jwk tool

• Use the below command to convert the 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