# 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:

```json
{
  "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`.