Identity Assurance სერვისთან ინტეგრაციის ტექნიკური დოკუმენტაცია

შესავალი

ეს დოკუმენტაცია აღწერს, თუ როგორ უნდა მოხდეს თქვენი აპლიკაციის ინტეგრაცია ღია ფინანსების Identity Assurance სერვისთან. სერვისი საშუალებას აძლევს ერთ ფინანსურ ინსტიტუტს (შემდგომში „დაყრდნობილი მხარე“) მიიღოს მომხმარებლის ვინაობის შესახებ დადასტურებული ინფორმაცია სხვა ფინანსური ინსტიტუტისგან (შემდგომში „იდენტობის პროვაიდერი“).

პროცესი ეფუძნება OpenID Connect for Identity Assurance 1.0 სტანდარტს და სრულად თავსებადია Financial-grade API (FAPI) უსაფრთხოების პროფილთან.

---

ძირითადი კონცეფციები

დაყრდნობილი მხარე (Relying Party): თქვენი აპლიკაცია ან სერვისი, რომელსაც სურს მომხმარებლის ვინაობის გადამოწმება.

იდენტობის პროვაიდერი (Identity Provider): ორგანიზაცია (მაგ. ბანკი), რომელიც ადასტურებს მომხმარებლის ვინაობას და აწვდის ამის შესახებ ინფორმაციას.

შემოწმებული მტკიცებები (Verified Claims): მომხმარებლის შესახებ ინფორმაცია (სახელი, გვარი, პირადი ნომერი და ა.შ.), რომლის სისწორეც დადასტურებულია იდენტობის პროვაიდერის მიერ.

მტკიცებულება (Evidence): ინფორმაცია იმის შესახებ, თუ რა დოკუმენტს ან მეთოდს დაეყრდნო იდენტობის პროვაიდერი მომხმარებლის ვინაობის გადამოწმებისას (მაგ., პირადობის მოწმობა, პასპორტი).

ნდობის ჩარჩო (Trust Framework): წესების ერთობლიობა, რომლის მიხედვითაც მოხდა ვინაობის გადამოწმება. საქართველოსთვის სავალდებულოა ge_aml ჩარჩოს გამოყენება, რაც გულისხმობს უკანონო შემოსავლების ლეგალიზაციის წინააღმდეგ მიმართული კანონმდებლობის დაცვას.

---

ინტეგრაციის პროცესი:

ინტეგრაციის პროცესი სტანდარტული OpenID Connect (OIDC) პროცესის შესაბამისია, თუმცა მოიცავს სპეციფიკურ პარამეტრებს შემოწმებული მტკიცებების გამოსათხოვად.

ეტაპი 1: წინაპირობები

1. სამართლებრივი შეთანხმება: დაყრდნობილი მხარე უნდა იყოს „მესამე პირის/შუამავლის საშუალებით მომხმარებლის იდენტიფიკაციისა და ვერიფიკაციისას მონაცემთა გაცვლის“ შეთანხმების მონაწილე.
2. კლიენტის რეგისტრაცია: დაყრდნობილმა მხარემ უნდა მიიღოს უნიკალური client_id და ავთენტიფიკაციისთვის საჭირო მონაცემები იდენტობის პროვაიდერისგან.
3. Identity Assurance სერვისების გამოყენება: კლიენტის (დაყრდნობილი მხარის) ავთენტიფიკაცია ხორციელდება დაცული საკომუნიკაციო არხით, რომელიც მოითხოვს ორივე მხარის მიერ X.509 ფორმატის სერტიფიკატების წარდგენას (mTLS), ღია ბანკინგისთვის განსაზღვრული სტანდარტების შესაბამისად.

ეტაპი 2: ავთენტიფიკაციის მოთხოვნის ფორმირება

დაყრდნობილმა მხარემ მომხმარებელი უნდა გადაამისამართოს იდენტობის პროვაიდერის authorization_endpoint-ზე შემდეგი პარამეტრებით:

• response_type=code
• client_id
• scope=openid (და სხვა საჭირო scope-ები, მაგ. https://openfinance.ge/ns/scope/kyc)
• redirect_uri
• state
• code_challenge (თუ გამოიყენება PKCE)
• code_challenge_method (თუ გამოიყენება PKCE)
• nonce
• claims (ყველაზე მნიშვნელოვანი პარამეტრი): JSON ობიექტი, რომელიც აღწერს, თუ რა შემოწმებული ინფორმაცია გჭირდებათ.

claims პარამეტრი უნდა იყოს შესაბამისობაში OpenID Connect for Identity Assurance 1.0 და საქართველოს ღია ბანკინგის ასოციაციის მიერ შემუშავებულ სტანდარტთან User Identification and Authentication Service Standard 0.3.RC3:

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

claims პარამეტრის მაგალითი:

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

ეტაპი 3: ტოკენის მოთხოვნა

მომხმარებლის წარმატებული ავთენტიფიკაციის შემდეგ, იდენტობის პროვაიდერი დააბრუნებს authorization_code, რომელიც უნდა გამოიყენოთ token_endpoint-ზე ტოკენის მისაღებად. შეგიძლიათ იხელმძღვანელოთ OIDC პროტოკოლის სტანდარტით.

token_endpoint ბოლოწერტილზე მოთხოვნისთვის საჭიროა შემდეგი პარამეტრები:

• code
• client_id
• grant_type=authorization_code
• redirect_uri
• code_verifier (თუ გამოიყენება PKCE)

ეტაპი 4: მომხმარებლის ინფორმაციის მიღება

მომხმარებლის ინფორმაციის მისაღებად, გამოიყენეთ userinfo_endpoint. სერვისი დააბრუნებს მომხმარებლის შესახებ claims პარამეტრით მოთხოვნილ ინფორმაციას, მათ შორის შემოწმებულ მტკიცებებს.

userinfo ბოლოწერტილზე მოთხოვნისთვის საჭიროა ჰედერში Authorization გადაეცეს Bearer {access_token}, რომელიც მიიღეთ token_endpoint-დან.