How to sign-in a user with SIWE

Sign in with Ethereum (SIWE)

Unblock implement the Sign-in with Ethereum (SIWE) standard (also known as EIP-4361 or EIP-1271) to identify users and confirm ownership of a blockchain address.

At a high level, the Sign-In With Ethereum standard requires the Merchant to ask the individual to use their private key to sign a plaintext message containing several standardised fields and send that signed message to the server to prove account ownership.

Unblock uses the SIWE standard to create authenticated sessions for the Individual and returns a session_id.

Unblocker App (for development purposes)

To make life easier during the development process, Unblock has built a simple webapp to help SIWE existing Individuals use a private key stored in Metamaks.

The code of Unblocker is public, and Merchants are welcome to use it to base their implementation of SIWE.

The app can also be built locally by the Merchants if needed by just cloning the GitHub repo and then running yarnthenyarn dev`

1. Connecting with Metamask Wallet

The user needs to have been created using the following steps (make sure to set up the user with the target address that is stored in Metamask):

Once done, the Merchant can use Unblock to generate the session_id using SIWE,

The merchant can then go to Unblocker and click on Connect wallet, when connecting the merchant notices this warning:

This warning shows up because Unblocker is creating a signed SIWE message to a domain that is not the same as where it's hosted: getunblocker.getunblock.com and in the example above, the signed message domain is sandbox.getunblock.com - they are not the same domain hence the warning showing on Metamask.

In the Production environment, this error message can be avoided; the Merchant will be asked to provide the domain from which the message will be signed, and Unblock can whitelist it. Once this is done, this warning message should not appear again.

2. Using Unblocker to Login in Unblock

Once the wallet is connected, the Merchant can press the Generate message and signature button, this will display the message to be signed below.

Select the correct environment for the User and the API key to be used in the next step.

Lastly, the Merchant can press Login this will prompt the Merchant API key to be inserted, depending on the environment selected above. Make sure to use the full API key, including the word API-key

If all goes right the Merchant should then get the user uuid of the user that is signed in and the session ID that can be used for all API calls,

🚧

Session_id will expire after 4hrs

The unblock_session_id last for four hours and after this time has passed a new login must be completed to refresh the session - this means a new signed message has to be generated and you'll need to log in again using the API key.

In code (for production)

We recommend Merchants use these examples and library to generate SIWE messages and sign them: SIWE Quick start

This can be done in Front end applications using browser wallets standards like Metamaks, but it can also be achieved in full backend environments using libraries like web3.js and ether.js.

🚧

Make sure to keep API key private

Keep in mind that if you decide to generate the SIWE message in the front end you will need to make sure that the API key provided by Unblock required to verify the message is always kept private.