Skip to main content

Technical Documentation for Integration with Identity Assurance Service

Introduction​

This documentation describes how to integrate your application with the Open Finance Identity Assurance service. The service enables one financial institution (hereinafter “Relying Party”) to receive verified identity information about a user from another financial institution (hereinafter “Identity Provider”).

The process is based on the OpenID Connect for Identity Assurance 1.0 standard and is fully compatible with the Financial-grade API (FAPI) security profile.

Key Concepts​

Relying Party: Your application or service that wants to verify the identity of the user.

Identity Provider: An organization (e.g., a bank) that verifies the user's identity and provides related information.

Verified Claims: Information about the user (e.g., first name, last name, personal ID number, etc.) that has been verified by the Identity Provider.

Evidence: Information about the document or method the Identity Provider used to verify the user’s identity (e.g., ID card, passport).

Trust Framework: A set of rules under which the identity verification was performed. For Georgia, the use of the ge_aml framework is mandatory, which ensures compliance with anti-money laundering legislation.

Integration Process​

The integration process follows the standard OpenID Connect (OIDC) flow, but includes specific parameters for requesting verified claims.

Step 1: Prerequisites​

  1. Legal Agreement: The relying party must be a participant in the “data exchange agreement for user identification and verification through a third party/intermediary”.
  2. Client Registration: The relying party must obtain a unique client_id and authentication credentials from the Identity Provider.
  3. Using Identity Assurance services: the client (Relying Party) authentication is performed over a secure communication channel that requires the mutual presentation of X.509 certificates (mTLS), in accordance with the standards defined for Open Banking.

Step 2: Constructing the Authentication Request​

The relying party must redirect the user to the Identity Provider’s authorization_endpoint with the following parameters:

  • response_type=code
  • client_id
  • scope=openid (and other required scopes, e.g., https://openfinance.ge/ns/scope/kyc)
  • redirect_uri
  • state
  • code_challenge (if using PKCE)
  • code_challenge_method (if using PKCE)
  • nonce
  • claims (most important parameter): A JSON object that specifies which verified information is being requested.

The claims parameter must comply with the OpenID Connect for Identity Assurance 1.0 standard and the User Identification and Authentication Service Standard 0.3.RC3 developed by the Open Banking Association of Georgia:

  1. https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html
  2. https://openfinance.ge/en/standards

Example claims parameter:​

{
  "userinfo": {
    "verified_claims": {
      "verification": {
        "trust_framework": {
          "value": "ge_aml",
          "essential": true
        }
      },
      "claims": {
        "given_name": null,
        "family_name": null,
        "personal_number": null,
        "birthdate": null
      }
    }
  }
}

Step 3: Requesting the Token​

After successful user authentication, the Identity Provider returns an authorization_code, which must be used at the token_endpoint to obtain a token.

Follow the standard OIDC protocol for this request.

Parameters required for the token_endpoint request:

  • code
  • client_id
  • grant_type=authorization_code
  • redirect_uri
  • code_verifier (if using PKCE)

Step 4: Retrieving User Information​

To retrieve user information, use the userinfo_endpoint. The service will respond with the user's details as defined in the claims parameter, including any verified claims.

To call the userinfo endpoint, you must provide the Authorization header with the Bearer {access_token} received from the token_endpoint.