Onboarding

The onboarding of all users require a minimal KYC requirements no matter what role they undertake.

The key identifier for any users in the system is their credential in Keycloak, the subject sub identifier is used across all microservices.

Components involved in the onboarding process are:

• Keycloak v24 instants (Platform-D Realm): Supported by Postgres integration
• [User Management] : Rust based, holds Keycloack Admin Client Connections, used for user registration
• Gayadeed KYX : Golang based, interacts with SPID, Sefin, Jumio and ComplyAdvantage, used for KYC and blacklist check
• Gayadeed VC-API: Golang based, interacts with Paradym, used for issuance and storage of batch verifiable credential
• [Account]: Rust based, interacts with D-Chain, used for creating onchain wallet and updating user wallet address

Apart from the Keycloak Admin Client connection, all services communicate via gRPC.

Sequence of onboarding and logging in

sequenceDiagram
    autonumber
    actor User
    participant Keycloak
    participant User Mgmt
    participant Gaya-kyx-&-vc

    participant D-Account
    participant D-Chain

    Keycloak --> User Mgmt: Holds Admin Client <br> controls user attributes

    User ->> Keycloak: Create Webauthn Credential
    User ->> Keycloak: Login with token
    User ->> D-Account: check `AccountKycStatus`

    alt AccountKycStatus == `init`
        D-Account->> Gaya-kyx-&-vc: `GayaKyxCreateTransactionService` <br> with `response_endpoint` to User Mgmt
        Gaya-kyx-&-vc ->> D-Account: `CreateTransactionResponse` with `challenge_url`
        Note over D-Account, Gaya-kyx-&-vc: The `response_endpoint` is in the transaction request <br> but challenge_url is returned to D-Account for the User

        D-Account ->> User: re-route to `challenge_url`
        User ->> User: Jumio web client re-route to <br> `platformd.io/kyx-pending`

        Note over Gaya-kyx-&-vc: Jumio calls `/kyx/callback` on update
        Gaya-kyx-&-vc ->> User Mgmt: `GayaKyxCallbackService` <br> with status and decide if it should issue credential
        User Mgmt ->> Gaya-kyx-&-vc: `CallbackResponse` <br> with info regarding if Gaya-vc should be called

        opt On `CallbackResponse` create physical person cred == true
            Gaya-kyx-&-vc ->> Gaya-kyx-&-vc: Request batch issuance of credential for physical person
        end

        User Mgmt ->> Keycloak: Update user attributes accordingly


    else AccountKycStatus == `pending`
        D-Account ->> User: wait

    else AccountKycStatus == `success`
        Note over D-Account: Check `token.dChainAddr`

        alt token.dChainAddr == empty
            D-Account ->> D-Chain: create onchain wallet
            D-Account ->> User Mgmt: update token.dChainAddr field
        else token.dChainAddr == not empty (support only 1 in this case)
            D-Account ->> D-Chain: query data (also from indexer)
            D-Chain ->> D-Account: return account data
        end
        D-Account ->> User: Return account data

    end

User registration

Impl: Keycloak Platform-D Realm

This step users interact with keycloak Platform-D realm to register their Webauthn credentials. The public key created and stored in keycloak will be used to create they Onchain wallet later on.

The tokens must present following attributes on top of the standard OIDC claims:

{
    "kycStatus": "init",
    "roles": ["<roles>"]
    "dChainAddr": ["<address>"]
}

• kycStatus includes both identity proofing and blacklist check status. Please see KYC Status for more details. This attribute is updated by the gaya/kyx calling to the UserManagement API.

• roles are the roles that the user has in the system. Currently roles are supplier, investor and admin. This attribute is updated by the platform-D onboarding API for the user on the UserManagement API.

• address are the onchain addresses created for the user by the platform-D onboarding API after KYC_SUCCESS status. This attribute is updated by the platform-D onboarding API for the user on the UserManagement API.

Please see webauthn background on credential_id

KYC and Blacklist check

Impl gaya/gaya-kyx

After a value token is created, the user will be navigated to the KYC process. The KYC process depends on the nationality of the user. For Italian users, Gayadeed provides SPID identity proofing and Blacklist test, for other nationalities, Jumio is used for identity proofing and ComplyAdvantage.

The state of the KYC is stored in the Keycloak user attributes.

Please see details of iframe communication for the process of KYC by jumio here

KYC Status

The KYC states are tied to the sub.

stateDiagram-v2
    [*] --> KYC_INIT
    KYC_INIT --> KYC_PENDING
    KYC_PENDING --> KYC_FAILED
    KYC_PENDING --> KYC_SUCCESS

Verifiable Credentials Management

Impl gayadeed-vc-api

This service interacts with Paradym.id API services to create credential templates (see credential services for more template details), and stores the issued credentials on behalf for the users.

This service stores the credential for the users.