This documentation section will dive deep into implementing the Sign-in with Tezos(SIWT). For more details about the concept Sign in With X (SIWx), CAIP-122.
Sign-In with Tezos describes how Tezos accounts authenticate with off-chain services by signing a message parameterized by scope, nonce, etc. It is an alternative to centralized identity providers. It is based on the self-custody of your identity. It leverages the on-chain authentication model to off-chain services.
The reason behind implementing the concept Sign-In with Tezos is that it is a critical step in the Login with NFTs concept. Before granting access to some services based on the ownership of some NFTs, we need to check two main aspects:
You own an account via Sign with Tezos.
Verify that the account has an NFT in a specified collection.
An account in Tezos is linked to the ownership of a private key which is then mapped to his public key. The hash of the public key outputs an address. Depending on the chosen Digital Signature Algorithm's elliptic curve (see ECDSA), the latter starts with "tz1" (Ed25519 curve), "tz2" (Secp256k1 curve), or "tz3" (P256 curve).
The IDP Kit implements SIWT based on seven main steps:
Nonce generation.
Redirection to the IDK Kit wallet user interface.
Connect to your Temple wallet.
A popup appears for signing the message. It is based on multiple factors like the nonce generated by the IDP Kit, account address, etc.
Click the “Sign” button.
Redirection to the IDK Kit verification service.
The IDP Kit verifies the message signature based on the account address.
The message will be in the form of:
{domain} wants you to sign in with your Tezos account: {address}. Public Key: {publicKey}.Date: {ISO8601formatedTimestamp}. {description} URI: {origin}. Version: {versionNumber}. Nonce: {nonce}
domain: is the RFC 3986 authority that is requesting the signing.
Permissions.address: account address.
Public Key : account public key.
Date: is the ISO 8601 datetime string of the current time.
Nonce:security parameter generated by the IDP Kit.
The IDP Kit supports retrieval and verification of NFTs from Tezos ledger.
This section will explain the principles of how OIDC authentication requests are translated into NFT requests and the options available to craft such requests.
The IDP Kit transforms the ownership of NFT on the Tezos ledger into an identity access management solution. The implementation is based on three main aspects: OIDC, SIWT, NFT, and their metadata.
Any client application can use the IDP Kit to grant access to a service via the ownership of an NFT on the Tezos ledger. The IDK Kit extends the verification of the NFT ownership by applying policies to the NFT metadata via an open policy agent(OPA).
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.
The whole verification process has seven main steps:
The client application redirects the user to the IDP Kit. It is a verification request based on the OIDC standard.
The IDP Kit processes the verification request. If it is an NFT Tezos verification, the IDP Kit redirects the user to his user interface.
Then, the user must connect to his wallet. He shares his address with the IDP Kit and signs a message based on the SIWT process.
The SIWT process continues within the IDP Kit by verifying the user address and the message signature.
After that, the IDP Kit will verify that the user has an NFT in a specified collection within the Tezos ledger. The NFT collection information is defined in the IDP Kit configuration file.
If the NFT metadata policy verification is activated, The IDP Kit will load the NFT metadata and run an OPA policy with the NFT metadata. The OPA policy is specified in the configuration file.
In the last step, the IDP Kit redirects the user to the client application with a response of the whole verification with extra information like the account address. This is based on the OIDC standard.
The authorization flow visualized
OpenID Connect(OIDC) is used as the protocol between any client application and the IDP Kit. It is used by the client application to make an NFT ownership verification request. The IDP Kit will well interpret the request. It is also used within the verification response by the IDP Kit to the client application.
SIWT is used to verify that the user controls and owns the private key of a Tezos account.
We can apply policies to the NFT metadata based on the Open policy agent(OPA).
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.
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:
nft_token claim, specified by the client application as a custom claim object in the authorization request
Derived from nft_mappings defined in the IDP Kit claim configuration, based on the scopes and claims requested in the authorization request
NFT token claim, configured in thedefault_nft_token_claim in the IDP Kit claim configuration
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:
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.
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.
