Arianee Protocol Documentation

Arianee Access Token

Suggest Edits

Before you begin

What is the Arianee Access Token?

An Arianee Access Token is an Ethereum Web Token or JSON Web Token using the Ethereum algorithm signature. It is very similar to an Arianee Proof, but it does not require a blockchain transaction, it is made off-chain.

The Arianee Access Token allows to prove that a user owns a wallet without sharing its private key.

header.playload.signature

eyJ0eXAiOiJKV1QiLCJhbGciOiJFVEgifQ==.eyJpc3MiOiIweDQ5NjdmOTZBOTUyMDk2Q2IxODAyRDM3NWNCNzAzMTRmODcyOUE5NzciLCJzY29wZSI6ImFsbCIsImV4cCI6MTU5NTkxMzMyNDk1OSwiaWF0IjoxNTk1OTEzMDI0OTYwLCJjaGFpbiI6InRlc3RuZXQiLCJzdWIiOiJjZXJ0aWZpY2F0ZSIsInN1YklkIjozNzAzNDU0fQ==.0x1a13a3f9f47b31212bfca68b67e17053c9a95d68d356bb540c7f7af77682699316a34fdb44c07a744e8584a41a5beea5b86ba92d97a4ab03ec5598f50a3f81f21c

HEADER
{
  "typ": "JWT",
  "alg": "ETH"
}
BODY
{
  "iss": "0x4967f96A952096Cb1802D375cB70314f8729A977",
  "scope": "all",
  "exp": 1595913324959,
  "iat": 1595913024960,
  "chain": "testnet",
  "sub": "certificate",
  "subId": 3703454
}

What for?

Arianee Access Token is similar to a JSON Web Token but signed by a wallet. They are widely used as a secure way of transmitting information between stakeholders in a web application environment. Find below some other advantages:

  • Off-chain: it does not require any blockchain transaction: so it is free to sign a JSON Web Token (no transaction cost) and it is instant.
  • Compact & efficient: lightweight and can be sent via HTTP headers, which makes them efficient for use in API authentication and authorization.
  • Stateless: does not require a database lookup to validate their authenticity. All the information required to validate the token is contained within the token itself, making it easy to use in a stateless architecture.
  • Cross-domain compatibility: can be easily passed between different domains, which is useful in a micro-services architecture where different services are running in different domains.
  • Secure: signed using a secret or a public/private key pair, which makes them tamper-proof.
  • Flexible: can carry a large amount of information in a compact format, making them flexible and useful for many use cases, including user authentication and authorization, as well as session management.

Let's start πŸš€

Generate a valid Arianee Access Token

{
  "iss": "0xWalletAddress",
  "exp": number,
  "scope": "read:products write:products"
}

Verify that the iss property in the payload matches the public key that was used to sign the JSON Web Token. If they do not match, the JSON Web Token is not valid.

An app considers this Arianee Access Token valid if:

  • iss public key to verify if the wallet that signs equals the issuer in the payload.
  • Arianee Access Token complies to the RFC7519. For example exp or nbf property.

The scope defines the permissions that the Arianee Access Token holder has, in the example above, the right to read and write products. This information can be used by the system to define whether a user is authorized to perform certain actions on the blockchain, actions based on the scope defined in the Arianee Access Token.

By design, an Arianee Access Token does not give any rights to perform a blockchain transaction.

Check if Arianee Access Token is valid

As you would do with a JSON Web Token:

  1. Split the JWT into three parts: header, payload, and signature. The three parts are separated by a period.
  2. Decode the base64-encoded header and payload. The result will be a JSON object containing the header and payload data.
  3. Verify that the iss property in the payload matches the expected issuer. For Arianee Access Token, the expected issuer is usually the Arianee platform or a specific smart contract address.
  4. Verify the signature of the JWT by recovering the Ethereum address that signed the JWT and comparing it to the address in the JWT's payload (iss property).

To help you out, Arianee developed its API that checks all these steps:

Use the api/isArianeeAccessTokenValid with your Arianee Access Token in the body.

[
  "eyJ0eXAiOiJKV1QiLCJhbGciOiJFVEgifQ==.eyJpc3MiOiIweG[...]
]

Result: Boolean returns, true if valid, otherwise false.

true

Code example:

import jwt
from web3 import Web3

jwt_token = "your.jwt.token.here"
expected_issuer = "0x...expected.issuer.address.here"

# Split the JWT into its three parts
header_b64, payload_b64, signature_b64 = jwt_token.split(".")

# Decode the header and payload
header = jwt.decode(header_b64, verify=False)
payload = jwt.decode(payload_b64, verify=False)

# Verify that the "iss" property in the payload matches the expected issuer
if payload["iss"] != expected_issuer:
    print("Invalid JWT - issuer does not match expected value")
    exit()

# Retrieve the public key associated with the Ethereum address that signed the JWT
w3 = Web3()
address = payload["sub"]
public_key = w3.eth.get_transaction_receipt(jwt.decode(jwt_token, verify=False)["jti"])["from"]

# Verify the signature using the public key
header_payload_bytes = (header_b64 + "." + payload_b64).encode("utf-8")
signature_bytes = jwt.decode(signature_b64, verify=False)["signature"]
w3.eth.account.recover_message(header_payload_bytes, signature=signature_bytes) == public_key

print("Valid JWT")

Updated 6 months ago