Relying Party Onboarding

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

Pre-requisites

Before integrating with eSignet, ensure the following setup is completed:

1. Prepare Your Development Environment

• Select your preferred technology stack (e.g., PHP, Python, Java, Node, Kotlin, Swift, etc.).

• Choose an appropriate OpenID Connect client library for your selected stack. (Refer to the library list here.)

2. Plan for UserInfo JWT Handling

• eSignet returns the UserInfo response as a signed or signed-and-encrypted JWT.

• Choose a compatible JWT plugin to decrypt, verify, and parse the UserInfo JWT.

3. Generate and Manage Cryptographic Keys

• eSignet supports only confidential clients using the private_key_jwt client authentication method.

• Generate a key pair and store the private key securely in password-protected, hardened storage (machine, vault, HSM).

• Share the public key with eSignet in JSON Web Key (JWK) format.

• Use different key pairs for development, test, and production—never reuse keys across environments.

• Rotate keys every 6–12 months, or immediately if compromised.

• The generated key pair must default to "signing" usage.

Only RSA key format is currently supported; additional key formats are planned.

4. Design Your Callback API

• The callback API is the endpoint to which eSignet redirects the user’s browser after authentication success or failure.

• Ensure the callback can render a user interface promptly, keeping the user informed of the authentication result.

• On successful authentication, the user is redirected with an authorization code.

• On failure, the user is redirected without a code, but with an error code.

• The relying party must handle the callback response appropriately before allowing the user to proceed.

Onboarding Your Relying Party (RP) as an OIDC Client with an ID Provider

To onboard your application or service as an OpenID Connect (OIDC) client with an Identity Provider (IDP) such as eSignet, follow the steps below. These steps ensure that your RP is registered correctly and can request user authentication and claims securely.

1. Prepare Your Public Key

Before registration, generate a key pair and have your public key ready. This public key will be shared with the ID provider to establish trust and enable secure communication.

2. Request Client Registration

Contact the eSignet provider (or relevant ID provider) and provide the following details:

• Public Key: The same public key generated earlier.

• Client/Application Name: This name will be displayed to users on the eSignet authentication and consent screens.

• Claims (Attributes) Required: Specify the list of user attributes your application needs.

  • Clearly indicate mandatory vs. optional claims.

  • Claim values and formats can be referenced from the eSignet .well-known configuration endpoint.

3. Submit Application Branding

To provide a seamless user experience, submit the following for display during authentication:

• Application Logo

• Organization Logo

These visuals will appear on the eSignet authentication and consent pages.

4. Define Callback URLs (Redirect URIs)

Specify the redirect URIs that the ID provider will use to return authentication responses. For development and QA environments, use the following patterns:

Supported for Development/QA:

• http://localhost:<portnumber>/*

• http://127.0.0.1:<portnumber>/*

• http://<your-server-ip>:<portnumber>/*

• my.phone.app://oauth/* (For mobile apps with deep linking)

Wildcard patterns (*) are acceptable for development but should be avoided in production due to security risks._

Unsupported URL Patterns:

• \\*

• http* (invalid wildcard usage)

• https://* (invalid wildcard usage)

• https://domain*

• residentapp://*

5. Await Client ID

Once the required information is submitted, the ID provider will process your registration and issue a Client ID. This ID will uniquely identify your application in all future authentication requests.