Clearnode Authentication Flow Intricacies

[nksazonov]

Clearnode Authentication

This is a discussion that serves as a reference for developers working with Clearnode’s authentication flow and contains answers to some of the most common questions.

Please note that this discussion message will evolve as answers to some commonly-asked questions will be added, while some moved to the documentation.

❓ How does the authentication flow work in Clearnode?

Clearnode uses a three-step challenge-response authentication mechanism:

1. Authentication Request (auth_request): Client sends their address along with other parameters like session key, allowances, scope, and application address
2. Challenge Response (auth_challenge): Server responds with a unique UUID challenge string that the client must sign
3. Verification (auth_verify): Client signs the challenge with their private key and sends it back for verification

Upon successful authentication, the server issues a JWT token containing policy information, permissions, and asset allowances. This token has a default validity of 24 hours and uses ES256 signatures for security.

❓ Are there any restrictions on the address-session_key relationship in authentication parameters?

Yes, there are strict restrictions enforced by Clearnode to prevent security vulnerabilities and address conflicts. First, it's important to understand that session keys (also called participant keys) are delegated signing keys that allow high-frequency state signing without exposing the main wallet's private key - they act as temporary representatives of the wallet for User Experience purposes.

The restrictions are:

1. No Circular Dependencies: An address used as a wallet cannot also be a session key
2. Exclusive Wallet Usage: An address used as a session key cannot also be a wallet
3. Unique Session Keys: A session key can only belong to one wallet
4. One-to-One Mapping: No circular or overlapping relationships between addresses

The easier rule of thumb is:

Each address can only serve one role: either as a wallet OR as a session key for exactly one wallet - no address can wear multiple hats.

These restrictions ensure that:

• There's no ambiguity about which wallet a session key represents
• Addresses maintain distinct roles as either wallets or session keys
• The delegation system remains secure and predictable
• High-frequency operations can be performed safely without compromising the main wallet

If you attempt to violate these restrictions, you'll receive errors like "signer is already in use for another wallet", "cannot use a wallet as a signer", or "wallet is already in use as a signer".

❓ Do clients need to authenticate before every request?

No, clients don't need to authenticate before every request. After the initial authentication flow, clients receive a JWT token that can be used for session persistence. This token allows clients to make authenticated requests without repeating the full challenge-response process until the token expires (default: 24 hours).

However, there are two types of endpoints:

• Public endpoints (like ping, get_config, get_assets) - No authentication required, can be called without the JWT
• Private endpoints (like transfer, create_app_session, close_app_session) - Require authentication, please provide the JWT

❓ How should private endpoints be accessed?

Private endpoints must be called with a valid JWT token. After completing the authentication flow successfully, clients receive a JWT token in the auth_verify response. This token should be included in subsequent requests to private endpoints. The JWT contains policy information including wallet address, participant details, permission scopes, asset allowances, and expiration time.

❓ How can a client verify if their JWT token is still valid?

There is no dedicated endpoint specifically for JWT validation. Clients can verify token validity by:

1. Using any private endpoint - If the token is expired or invalid, the request will be rejected
2. Calling the auth_verify endpoint with the JWT token - This can serve as a validation check
3. Checking the token's expiry claim - JWT tokens include an expiration time claim (exp) that clients can inspect locally before making requests

If a token is expired, clients must complete the full authentication flow again to receive a new JWT token.