Token Usage Guide

1. Introduction to Token

JWT (JSON Web Token) is an open standard used for authentication and authorization. It is based on the JSON (JavaScript Object Notation) format and is designed for securely transmitting claim information between network applications.

JWT consists of three parts: the header, payload, and signature. The header contains the type of JWT and the signature algorithm used, the payload contains the information to be transmitted, and the signature is used to verify the integrity and authenticity of the JWT.

In TuGraph, JWT is used to implement a stateless authentication and authorization mechanism. After a user logs in successfully, the server generates a JWT and returns it to the client. The client passes this JWT as an identity credential in subsequent requests to the server. Upon receiving the JWT, the server verifies the signature and parses the information in the payload to determine the user’s identity and permissions, and decides whether to allow the execution of the request.

2. Token Expiration

2.1. Browser Token Interaction Logic

1. The user opens the browser, enters the username and password, and clicks login.

2. The frontend calls the login interface and inputs the account and password to the backend.

3. After receiving the account and password, the backend verifies them and returns a Token.

4. The frontend stores the Token in the browser cache, and all subsequent requests must carry this Token.

5. If the frontend actively clicks logout or closes the page, it should actively call the logout interface and pass the Token to the backend.

6. After receiving the Token, the backend invalidates it, returns a status code 200, and “logout successful”. After receiving the message, the frontend clears the Token in the browser memory, and returns to the login page.

7. The Token expires (initially set to 24 hours), and the user needs to log in again.

2.3. Token Expiration Refresh Mechanism

Token expiration has a refresh mechanism that is turned off by default. If turned on, the security of the Token will be higher, and there will be two timestamps.

The first timestamp refresh_time is used to determine whether the Token has expired (default 24 hours): after expiration, the refresh interface can be called to obtain a new Token, which can be set to a shorter time, such as 1 hour.

The second timestamp expire_time is the forced expiration timestamp (default 24 hours): after expiration, the user must log in again.

2.4. Token Expiration Modification

To facilitate developers to develop on their own, TuGraph provides two ways to modify the expiration time, both of which require admin privileges.

• Set through the interface call. The interfaces involved in modifying the expiration time are update_token_time and get_token_time for querying the expiration time. For details, please refer to the REST interface document.

• Set through startup parameters. When the server-side is started, adding the parameter -unlimited_token 1 can set the Token to be unlimited. Please refer to the service running document for details.

3. Introduction to Token-Related Requests Sent by Clients

The client handles two types of protocol-related requests: REST and RPC.

3.1. REST

If the client uses the REST protocol (including the browser), because it is a short connection, Token needs to be carried in every request, and a new Token needs to be obtained after it expires.

For self-developed clients, if the REST protocol is used, Token logic needs to be considered.

3.2. RPC

If the client uses the RPC protocol (including the official C++/Java/Python), it uses a long connection to maintain, and no Token operation is involved after login.

4. Token upper limit

The upper limit of Token refers to the maximum number of Tokens that a user can own at the same time. To prevent unlimited logins, the upper limit of Token is 10000 by default. Since the token generation logic is strongly related to time, a token will be generated for storage every time you log in. The validity period of the token is 24 hours by default. Therefore, it is recommended to log out the unused token in time after login.