Authentication flow

Step by step authentication flow

1 - Connect Wallet

A user connect its wallet, probably using WalletConnect, Privy, etc (other methods of connecting a wallet could be later explored). Once the wallet is connected at the frontend / mobile level a sign-in flow with Cedalio can be started.

2 - Request JWT

Any interaction with Cedalio's gateway must be done using a JWT as authentication mechanism. Therefore a JWT should be request with the Auth system. To do so, the application should send a request to the Auth service via its application authentication endpoint URL https://$COMPANY_ID.gtw.cedalio.io/auth.

PROJECT_ID can be obtained from the project overview inside the Studio.

cURL

curl -X POST "https://$COMPANY_ID.gtw.cedalio.io/auth"

Response

{
	"nonce": "SOME_NONCE_TOKEN_TO_BE_SIGNED"
}

3 - Message Signature Challenge

When receive the auth request to generate a JWT, the auth service should generate a message that must include a random nonce and an expiration time (to avoid replay attacks). This message should be sent to the application to be signed by the user that connected their wallet.

Remember to remove the “0x” from the public address. You have only two minutes to do this step. More info here.

cURL

curl -X POST <https://$COMPANY_ID.gateway.cedalio.io/auth/verify> -d@PATH_FILE_PAYLOAD.json

JSON File

{
	"message": "THE MESSAGE SIGNED BY THE USER WITHOUT INCLUDING THE NONCE",
	"nonce": "NONCE AS IS I RETURNED IT TO THE PREVIOUS REQUEST",
	"signature": "SIGNATURE OF THE MESSAGE",
	"account": "PUBLIC ADDRESS OF THE USER WHO SIGNED THE MESSAGE"
}

Response

{
	"token": "JWT ready to use"
}

We verify the signature by doing message + nonce. For this reason, if the message has 2 enters (new line) before displaying the NONCE_THAT_THE_SERVER_SENT, the value of the message field must include those 2 enters /n/n.

4 - Signed message response

The signed message is returned to the auth service for it to validate that the response was sent within the sign time window and then verifies the signature. More info here. Basically given a message and a signature use recover to obtain the public address which should match the public address initially provided by step 2.

5 - JWT

If the signature is successfully verified, the auth service emits a JWT that expires in 30 minutes that is a small window, long enough to avoid having to perform the sign process constantly. The JWT must include the public address obtained in step 4 and any other relevant "session" information.

💡If you want to test the signing flow without having to build the frontend first you can use https://app.mycrypto.com/sign-message to sign the nonce of the first request.