EVM | Identity Provision

The IDP Kit supports retrieval and verification of NFTs from wallets.

This section will explain the principles of how OIDC authentication requests are translated into NFT requests and the options available to craft such requests.

How it works

To understand how identity provision via NFTs can be leveraged in an OIDC authentication flow, you may first want to recap on the basic principles of OIDC authentication.

OIDC via NFTs

When using NFTs as information source, the IDP Kit will derive the required NFT collection from the authentication request and redirect to an application, where the user can connect his wallet and share their address.

After the user has shared their address, the application will send it back to the IDP Kit, where the NFT Manager will make sure that the user is the rightful owner of that shared address, by utilizing the concepts described in EIP-4361: Sign-In with Ethereum, and that the shared address is associated with the required NFT collection sent in the authentication request. Have a look at the NFT Manager configuration page to see how this can be configured and which defaults can be set.

The verified data is then transformed into the response format requested by the application, which by default will include the account address and optionally specified metadata of the NFT.

The authorization flow visualized

Claiming nft_token

In this scenario, the client application requests the raw NFT data, without mapping to standard OIDC claims, by specifying the custom nft_token claim or defining the nft_token scope in the authorization request.

nft_token Scope

By specifying the nft_token scope in the authorization request, the client application requests the validation of the user being a holder of an NFT in the required NFT collection and the user info to be included in the response. The IDP Kit will determine the NFT request, which is sent to the NFT wallet, by the following sources in this order:

1. nft_token claim, specified by the client application as a custom claim object in the authorization request

2. Derived from nft_mappings defined in the IDP Kit claim configuration, based on the scopes and claims requested in the authorization request

3. NFT token claim, configured in thedefault_nft_token_claim in the IDP Kit claim configuration

nft_token Claim

The nft_token claim should be constructed as follows:

Authorization POST request:

When making the authorization post request, the client can specify a claim field in the body, with a value describing the NFT collection. The format will be as follows:

"claim": {
  "nft_token": {
    // blockain identifier
    "chain":"MUMBAI",
    // the smart contract representing the NFT collection
    "smartContractAddress":"0xf277BE034881eE38A9b270E5b6C5c6f333Af2517"
  }
}

Authorization GET request:

When making the authorization get request, the client can specify a claim field, as shown in the example above, in a JSON object. This object will then be sent URL encoded via the query parameters.

IDP Kit receiving the request

The IDP Kit takes the request and opens a wallet connect page, where the user is prompted to connect their wallet to the page and share their address. The shared address will then be sent back to the IDP Kit, which verifies that the user is the rightful owner and holder of an NFT of the required NFT collection. After verification, the IDP Kit sends the information (account address/nft metadata) back to the client application in the nft_token property of the user info.

The application can rely on the received data, as the IDP Kit is verifying the ownership of NFT and address.

Standard OIDC scopes, claims and claim mapping

In this scenario, the client application simply makes a standard OIDC authorization request, like any other OIDC compliant identity provider would expect it. E.g. the application could request the profile scope, to receive name, given name, family name, gender, date of birth, etc. of the user from the IDP Kit.

The IDP Kit maps the required claims to suitable traits in the NFT metadata that contain the requested information, by getting access to the NFT through the shared address of the user. The gathering of the user address will be handled by a separate wallet connect page (web application), without the client taking any notice.

Once the IDP Kit has received the address of the user from the wallet connect page, got the information from the NFTs metadata and verified all of it. The IDP Kit translates the received data into the standard user info claims requested by the application and provides it on the standard user info endpoint.

To use this flow, the client application needs no additional knowledge about the underlying protocol. In most cases, a simple configuration change would suffice to make an application connect to the IDP Kit and accept NFT data for user authentication, given that OIDC is already used as an authentication layer.