Relying Party
Last updated
Was this helpful?
Last updated
Was this helpful?
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.
This guide helps the developers of the relying party to get started with their development environment.
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).
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.
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 .
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.
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.
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.
Sample /authorize Request:
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.
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.
Sample ID token JWT header and payload
Sample Access token JWT header and payload
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.
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.
User info endpoints response example is listed below:
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.
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:
Here is the 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 file in the respective eSignet provider.
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
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'
openidAvailable options: The value set here determines the authorization processing flow. To use the Authorization Code Flow, the value should be configured to "code".
Valid OAuth 2.0 Client Identifier in the Authorization Server.
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:/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.
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.
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.
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.
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.
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.
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.
A challenge derived from the code_verifier, This is required if its a VC scoped request.
A method that was used to derive code challenge, This will be required if code_challenge is provided.
OK
Loads JS application, and validates the provided query parameters using oauth-details endpoint.
No content
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
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.
Authorization code grant type.
Authorization code, sent as query param in the client's callback URI.
Client Id of the OIDC client.
Type of the client assertion part of this request.
Private key signed JWT, This JWT payload structure is defined above as part of request description.
Valid client redirect_uri. Must be same as the one sent in the authorize call.
A cryptographically random string that is used to correlate the authorization request to the token request.