Generate a login access token
How to form a login token on a game server.
阅读时间3 分钟最后更新于 8 个月前
The next step in the login process is to correctly form a login token on a game server. This step is important to understand as it contributes to a significant number of Vivox integration mistakes. Here are some key facts to understand Login Tokens in general:
-
Login tokens can only be used once.
-
Expiration timers are important; leave room for unforeseen circumstances such as slow internet connections or inactive instances.
- Current best practice for expiration time is Time.Now + 90 seconds.
-
Your game will provide its own account names and login tokens.
-
There are three key sections to the login tokens:
- Header
- Payload
- Signature
Login token - Header
In the case of Vivox, the header is empty to satisfy the JSON Web Token (JWT) standards. The header can be formed either as code or as a constant.
Code | Constant |
|---|---|
| base64URLencode(“{}”) | An empty header should always resolve to “e30” when encoded, this can be stored as a constant in your code if it fits your needs. |
Login token - Payload
Crafting a payload consists of a defined set of claims you make to the Vivox server. Your code can craft an object to store these claims. The claims apply to tokens other than login tokens, so they can be serialized and encoded when you submit your request to Vivox.
Explanation | Example claims object |
|---|---|
| N/A | public class Claims { |
| Issuer | public string iss {get;set;} |
| Expiration time in “epoch seconds” | public int exp {get;set;} |
| Vivox Action | public string vxa {get;set;} |
| VXI is a claim that guarantees uniqueness, a simple incremented integer can be used. | public int vxi {get;set;} |
| Full details on who the token is “from” | public string f {get;set;} |
| Not used for login tokens. | public string t {get;set;} |
| N/A | public string sub {get;set;} } |
Example login token
Claims loginClaim = new Claims{iss=issuer-ba63,vxi = 93000,vxa:login,exp=1600349400,f=sip:.issuer-ba63.030104_16.@tla.vivox.com };
Some best practices for token payloads
- All information should be base64URLEncoded, this is different from base64encode.
- Current best practice for expiration time is Time.Now + 90 seconds.
- VXI is a claim that guarantees uniqueness, a simple incremented integer can be used.
Login token - Signature
The signature combines the header and payload into a signed hash-based message authentication code (HMAC) which is then encoded. This is where the key provided by Vivox is used to protect your service and authenticate your communication.
To form this HMAC:
- Join your encoded header and encoded payload together with a period.
- Process the result through an HMACSHA256 process.
- Use the “secret” provided in your Vivox Developer Portal credentials as the signing key in the HMAC process/method.
A pseudo-code example of this can be found on the Access token signature page.
Your final result should resemble this example:
| e30.eyJpc3MiOiJibGluZG1lbG9uLUFwcE5hbWUtZGV2IiwidnhhIjoibG9naW4iLCJ2eGkiOjkzMzAwMCwiZXhwIjoxNjAwMzQ5NDAwLCJmIjoic2lwOi5ibGluZG1lbG9uLUFwcE5hbWUtZGV2Lmplcmt5LkB0bGEudml2b3guY29tIn0.5FKsAQz7bRQGGlSZw-KIcCmft7Ic6nT3Ih-TbdYPWwI |
Color guide:
| Header | Payload | Signature |
The next step is to submit your login request using the login token.