Skip to main content

SLUDI & Verifiable Credentials Integration Guide

This guide outlines how to integrate Login with SLUDI (OIDC Authentication) and Verifiable Credentials (VC) into your applications.

Architecture Overview​

All client communications (authentications, token requests, and VC downloads) between relying party applications and core identity/credential services are routed and managed by the API Gateway.

The API Gateway:

  • Secures all core service endpoints.
  • Validates request signatures and OAuth 2.0 access tokens.
  • Manages rate-limiting and access policy enforcement.

1. Integrating Login with SLUDI (OIDC)​

Step 1: Create an OIDC Client​

To start, you need to register your application as an OIDC Relying Party (RP):

  1. Navigate to the Developer Dashboard and select My SLUDI → Issuer Configuration.
  2. Click Create OIDC Client.
  3. Provide your application parameters:
    • Organization Name: Your company or university name.
    • Application Display Name: The name shown to users on the SLUDI authentication screen.
    • Redirect URI: The callback URL on your server (e.g. https://your-domain.com/callback).
  4. Click Submit. Your client credentials will be generated.
  5. Download Private Key: Save the generated private key (private-key.pem) securely. It is required to sign JWT assertions when requesting access tokens.

Step 2: Implement OIDC Code Flow with PKCE​

We recommend using the standard OIDC Authorization Code Flow with PKCE for maximum client-side security:

  1. Generate PKCE Parameters: Create a random code_verifier (a high-entropy cryptographic string) and its SHA-256 hash code_challenge.
  2. Redirect to SLUDI Authorize Endpoint: Redirect the user to the gateway-proxied authorization endpoint: 
    GET https://api.dev.digieconcenter.gov.lk/authorize?
      client_id=YOUR_CLIENT_ID&
      response_type=code&
      redirect_uri=YOUR_REGISTERED_REDIRECT_URI&
      scope=openid profile individual_id&
      code_challenge=YOUR_CODE_CHALLENGE&
      code_challenge_method=S256&
      state=RANDOM_STATE&
      nonce=RANDOM_NONCE&
      acr_values=mosip:idp:acr:generated-code
  3. Capture Callback: Once authenticated, the user redirects to your redirect_uri with a code and state. Verify the state matches your original request.

Step 3: Exchange Code for Access Token (private_key_jwt)​

To request an access token, authenticate your app against the token endpoint using a Client Assertion (signed JWT) instead of a static client secret:

  1. Sign the Client Assertion: Generate a JWT containing:
    • iss: Your client_id
    • sub: Your client_id
    • aud: https://api.dev.digieconcenter.gov.lk/v1/esignet/oauth/v2/token
    • exp: Short expiration (e.g., 5 minutes) Sign this JWT using the private key (private-key.pem) downloaded from the portal.
  2. Send Token Request: Send a POST request to the API Gateway: 
    POST https://api.dev.digieconcenter.gov.lk/v1/esignet/oauth/v2/token
    Content-Type: application/x-www-form-urlencoded

    grant_type=authorization_code
    &code=RECEIVED_AUTHORIZATION_CODE
    &redirect_uri=YOUR_REGISTERED_REDIRECT_URI
    &client_id=YOUR_CLIENT_ID
    &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
    &client_assertion=SIGNED_CLIENT_ASSERTION_JWT
    &code_verifier=YOUR_PKCE_CODE_VERIFIER

2. Integrating Verifiable Credentials (VC)​

Once you authenticate a user via SLUDI, you can issue signed Verifiable Credentials representing official documents (e.g., University Degrees, ID Cards).

:::important Manual Onboarding Notice Due to security, policy, and cryptographic trust requirements, Verifiable Credentials cannot be fully automated.

Issuing VCs requires manual steps:

  1. Define the Template: Create your credential template layout and attribute mappings inside the developer portal (My SLUDI → Verifiable Credentials).
  2. Submit Verification Request: Contact the sandbox operations support team to request template activation.
  3. Manual Verification: The admin team will manually register the credential configuration on the Certify issuer registry, establish cryptographic trust bindings, and reload Mimoto service mappings. :::

OpenID4VCI Download Flow​

Once your template is activated, your application can request credential issuance:

  1. Request the credential from the Mimoto service via the API gateway.
  2. Deliver the downloaded JSON credential payload directly to the user (e.g., as a W3C-compliant Verifiable Credential file), or prompt them to import it into their Inji Wallet app.