GitHubCommunityWhat's NewContact Us
Edit

Development and Integration with eSignet

This guide provides a step-by-step approach for developers who want to integrate their application as a Relying Party (RP) with eSignet.

Prerequisites

Before integrating your Relying Party application with eSignet, ensure the following are in place:

Requirement
Description

Client registered with eSignet

RP must be onboarded and issued a client_id. client_secret is not applicable.

eSignet well-known endpoint access

/.well-known/jwks.json

/.well-known/openid-configuration

Client Authentication Method

Only private_key_jwt is supported for token endpoint client authentication. Access to RSA/EC Private Key used by RP to sign the JWT during token request. Note: Should be securely stored and rotated periodically.

Registered Redirect URI

Must be pre-configured with eSignet(during onboarding ). It may be:

  • A frontend page

  • A mobile app deeplink / custom scheme

  • Or even a backend endpoint

Scopes/Claims required by RP

openid is mandatory. Optional scopes → profile, email, phone, or custom scopes if supported.

Note: Check the /.well-known/openid-configuration for supported scopes and claims.

Choose libraries for JWT Creation, Signing & OIDC Integration

Since private_key_jwt authentication requires the RP to generate a signed JWT for token requests, we recommend using well-supported cryptographic and OIDC client libraries. Developers may choose one based on their language/platform.

Reference: https://openid.net/developers/certified-openid-connect-implementations/

Always fetch the authorize, PAR, token, userinfo endpoint URL dynamically from .well-known/openid-configuration. This ensures your integration remains compatible even if environments or endpoints change.

🛠️ Step-by-Step implementation:

Step 1: Redirect user to eSignet Authorization Endpoint

Add a Sign-in with eSignet button to your login page that links to the authorize URL. A lightweight JavaScript plugin is available from eSignet to render this button automatically. By default, the plugin can be loaded from:

https://<eSignet-domain>/plugins/sign-in-button-plugin.js

The button may follow specific branding guidelines such as name, logo usage, color scheme, and size. These are typically defined by the Identity Provider. eSignet provides a UI Storybook that demonstrates recommended styles and customization options for relying party implementations: Additionally, sign-in-button-plugin.js provides PAR and DPoP support. Refer storybook to know more details on how to configure and use the par_callback and dpop_callback parameter.

{% details title="eSignet Authorization Endpoint Specification" %}

openapi: 3.0.1
paths:
  /authorize:
    get:
      tags:
        - OIDC
      summary: Authorization Endpoint
      description: |-
        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.

        All the validations on the query parameter values will be performed in the "/authorization/oauth-details" endpoint.

        **Authentication & Authroization**: None
      operationId: get-authorize
      parameters:
        - name: scope
          in: query
          description: 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.
          required: true
          schema:
            type: string
            enum:
              - openid profile
              - openid
              - profile
              - email
              - address
              - phone
              - offline_access
            default: openid profile
        - name: response_type
          in: query
          description: 'The value set here determines the authorization processing flow. To use the Authorization Code Flow, the value should be configured to "code".'
          required: true
          schema:
            const: code
        - name: client_id
          in: query
          description: Valid OAuth 2.0 Client Identifier in the Authorization Server.
          required: true
          schema:
            type: string
            maxLength: 256
        - name: redirect_uri
          in: query
          description: Redirection URI to which the response would be sent. This URI must match one of the redirection URI values during the client ID creation.
          required: true
          schema:
            type: string
            format: uri
        - name: state
          in: query
          description: '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.'
          schema:
            type: string
            maxLength: 256
        - name: nonce
          in: query
          description: '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.'
          schema:
            type: string
        - name: display
          in: query
          description: ASCII string value that specifies how the Authorization Server displays the authentication and consent user interface pages to the end user.
          schema:
            type: string
            enum:
              - page
              - popup
              - touch
              - wap
        - name: prompt
          in: query
          description: Space delimited case-sensitive list of ASCII string values that specifies whether the Authorization Server prompts the End-User for re-authentication and consent.
          schema:
            type: string
            enum:
              - none
              - login
              - consent
              - select_account
            examples:
              - consent
        - name: max_age
          in: query
          description: 'Maximum Authentication Age. This specifies the allowable elapsed time in seconds since the last time the end user was actively authenticated by the OP. If the elapsed time is greater than this value, then the OP MUST attempt to actively re-authenticate the end user. The max_age request parameter corresponds to the OpenID 2.0 PAPE [OpenID.PAPE] max_auth_age request parameter. When max_age is used, the ID Token returned MUST include an auth_time claim value.'
          schema:
            type: number
        - name: ui_locales
          in: query
          description: '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.'
          schema:
            type: string
        - name: acr_values
          in: query
          description: 'Requested Authentication Context Class Reference values. 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 Authentication Context Class satisfied by the authentication performed is returned as the acr Claim Value, as specified in Section 2. The acr Claim is requested as a Voluntary Claim by this parameter.'
          schema:
            type: string
            enum:
              - 'mosip:idp:acr:password'
              - 'mosip:idp:acr:static-code'
              - 'mosip:idp:acr:generated-code'
              - 'mosip:idp:acr:linked-wallet'
              - 'mosip:idp:acr:biometrics'
              - 'mosip:idp:acr:knowledge'
              - 'mosip:idp:acr:id-token'
        - name: claims_locales
          in: query
          description: 'End-User''s preferred languages and scripts 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.'
          schema:
            type: string
        - name: claims
          in: query
          description: 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.
          schema:
            type: string
        - name: code_challenge
          in: query
          description: 'A challenge derived from the code_verifier, This is required if its a VC scoped request.'
          schema:
            type: string
        - name: code_challenge_method
          in: query
          description: 'A method that was used to derive code challenge, This will be required if code_challenge is provided.'
          schema:
            type: string
        - schema:
            type: string
          in: query
          description: ID Token previously issued by the Authorization Server being passed as a hint about the End-User's current or past authenticated session with the Client.
          name: id_token_hint
        - schema:
            type: string
          in: query
          description: 'The request URI corresponding to the pushed authorization request posted. This URI is a single-use reference to the respective request data in the subsequent authorization request.'
          name: request_uri
      responses:
        '200':
          description: |-
            OK

            Loads JS application, and validates the provided query parameters using oauth-details endpoint.
      servers:
        - url: 'https://esignet.collab.mosip.net/v1/esignet'
      x-stoplight:
        id: bx55bzakduy97

{% enddetails %}

PAR Support in Authorization Request

eSignet supports Pushed Authorization Requests (PAR) as per OAuth 2.0 standards. Using PAR, the RP first submits authorization request parameters directly to eSignet through a secure back-channel PAR endpoint, then receives a request_uri which is used in the authorize URL.

{% details title="eSignet PAR Endpoint Specification" %}

{% enddetails %}

Notes:

  • scope defines what user attributes RP can request.

  • claims enables RP to decide which user attributes are optional & mandatory.

  • Always generate fresh state & nonce to prevent replay & CSRF.

  • acr_values defines authentication method options, RP must choose based on the required assurance level.

  • The redirect_uri provided must be an absolute, fully qualified URL (without any wildcard or regex). This URI is then matched against the redirect URIs stored in the eSignet database for the same Client ID. Since the stored URIs may include wildcards or patterns, the matching process allows partial or regex-based checks rather than requiring an exact match.

  • The prompt=consent parameter should be used if the Relying Party (RP) requires eSignet to present a consent screen to the user during every authentication flow. If this parameter is omitted, consent is shown only during the first authorization request, and will be shown again only when the previously granted consent expires (expire duration is configured per client).

Step 2: User Authenticates and Consent on eSignet Screen

eSignet handles:

🔐 Authentication with the chosen authentication method. Eg: OTP / Biometrics / Wallet 🔐 Consent screen (only if claims are shared)

Successful authentication

If authentication succeeds, the user is redirected to the redirect_uri specified in the authorization request, along with an authorization code returned in the code query parameter.

Failed authentication

If authentication fails, the user is redirected to the same redirect_uri, but with an error code returned in the error query parameter. It is the RP’s responsibility to handle the error appropriately.

Step 3: Exchange Code for Tokens

Exchange authorization code for an Access token using the token endpoint. It is always suggested to use the token endpoint URL published in the .well-known/openid-configuration. This ensures your integration remains compatible even if environments or endpoints change.

Refer the below for token endpoint details:

{% details title="eSignet Token Endpoint Specification" %}

{% enddetails %}

Step 4: Verify & Parse the Access & ID Token

Access token generated by eSignet follow [RFC9068] JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens.

  • Validate JWT signature using public key published on eSignet /.well-known/jwks.json

  • Validate aud, iss, exp, iat in both the tokens.

  • Additionally validate auth_time, nonce, acr, at_hash in the ID token.

💡Key Notes:

  • eSignet does not support user claims in ID token.

  • The sub claim in ID and access token is a pairwise pseudonymous identifier.

Avoid storing ID Tokens or Access Tokens in browser localStorage or sessionStorage. If an attacker gains access to the browser context, they can extract the tokens and impersonate the user.

Instead, it is recommended to perform the token exchange and validation on the RP backend and maintain a secure server-side session. The user’s browser should only store a short-lived, HTTP-only, SameSite cookie that maps to this session for stronger protection model.

Step 5: Get Consented User Claims Using Access Token

If the Relying Party (RP) needs user attributes (e.g., eKYC data), the developer must implement a call to the userinfoendpoint using the Access Token obtained during token exchange. Always fetch the endpoint URL dynamically from .well-known/openid-configuration

This ensures your integration remains compatible even if environments or endpoints change.

The userinfo response is returned as a signed JWT (JWS) by default. The RP must validate the JWT signature using the public keys from /.well-known/jwks.json

If required, the RP can be configured to request an encrypted (JWE) userinfo response for additional security.

💡Key Notes:

  • The sub claim in the userinfo JWT will match the sub present in both the Access Token and ID Token, ensuring user identity continuity.

  • Use the claims_locales parameter in the authorize request if user attributes need to be returned in a specific language. (This is supported only when the identity system maintains multilingual claims.)

Refer the below for userinfo endpoint details:

{% details title="eSignet Userinfo Endpoint Specification" %}

{% enddetails %}

📄 Sample userinfo JWT payload:

📄 Sample userinfo JWT payload (with claims in 2 languages):

Last updated

Was this helpful?