This documentation section will dive deep into implementing the Sign-in with Polkadot(SIWP). For more details about the concept Sign in With X (SIWx), CAIP-122.
Sign-In with Polkadot Blockchain describes how polkadot 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 Polkadot 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 Polkadot.
Verify that the account has an NFT in a specified collection.
An account in Polkadot 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.
The IDP Kit implements SIWP based on seven main steps:
Nonce generation.
Redirection to the IDK Kit wallet user interface.
Connect to your polkadot 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 Polkadot 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.
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 Polkadot into an identity access management solution. The implementation is based on three main aspects: OIDC, SIWP, 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 Polkadot Blockchain. 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 Polkadot 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 SIWP process.
The SIWP 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 Polkadot Blockchain. 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.
SIWP is used to verify that the user controls and owns the private key of a Polkadot 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.