6.8.1 Service Tokens
This chapter applies to applications that provide services via an independent server only to users with a Nintendo Network account.
If your application uses an independent server to provide a service, you must always get a service token from Nintendo's account server.
Nintendo recommends that your application obtain the token prior to connecting to the independent server because, if you discontinue your service, Nintendo's account server will return an error indicating that your service has been discontinued.
If the principal ID, account ID, or similar IDs are used on the independent server side, you must always decrypt and verify the service token and use the values included in it.
Even if the independent server does not use the principal ID or account ID, to ensure the security of the independent server Nintendo recommends decrypting and verifying the service token to confirm that the connecting client has been successfully authenticated.
If you do not decrypt and verify service tokens, Nintendo strongly recommends ensuring the security of the independent server by some independent means.
In order to minimize server load, only call the nn::act::applet::AcquireIndependentServiceToken or nn::act::applet::AcquireIndependentServiceTokenV2 function (for getting a service token from Nintendo's account server) once per application launch. Note that for security reasons it is prohibited to save service tokens for later use, such as in save data.
To avoid getting tokens too frequently, it is acceptable to cache the service token you have gotten and use the cached token.
Also note that if acquisition of the service token fails, or if the service token has expired, it is only acceptable to retry in response to user operation. Automatic retries are prohibited.
You can configure the service token to expire by comparing the current time against the token issuance time included in the service token, and treating the token as invalid if more than a certain amount of time has passed.
Configure this expiration as appropriate for your application, and get a new token if the current one has expired.
You must take the following measures when sending a service token acquired from Nintendo's account server to an independent server.
- Secure the communication pathway by encrypting the data. If for some reason you cannot secure the communication pathway with encryption, set the token's valid period to be a short amount of time in order to decrease the risk entailed by eavesdropping.
- Implement the process in such a way as to protect against replay attacks.
6.8.1.1 Getting Service Tokens
Guideline Item |
Applications must get a service token from Nintendo's account server. The application must not save the service token for later use. |
---|---|
Software to Be Tested |
Applications that provide an independent-server service restricted to users with Nintendo Network accounts. |
Test Method |
|
Pass/Fail Determination |
Passes if, in step 6, a log is displayed showing acquisition of the correct service tokens corresponding with step 2.
|
6.8.1.2 Restrictions on the Frequency of Getting Service Tokens
Guideline Item |
The application must only call the nn::act::applet::AcquireIndependentServiceToken or nn::act::applet::AcquireIndependentServiceTokenV2 function to obtain a service token once per application launch.
|
---|---|
Software to Be Tested |
Applications that provide an independent-server service restricted to users with Nintendo Network accounts.
|
Exceptions |
Calling the function again, in response to user operation in the following cases:
|
Test Method |
|
Pass/Fail Determination |
Passes if the number of function calls in the service token acquisition log does not exceed the limit.
|
6.8.1.3 Communication Security When Transmitting Service Tokens
Guideline Item |
Applications must take appropriate measures when sending service tokens to an independent server.
|
---|---|
Software to Be Tested |
Applications that send service tokens acquired from the Nintendo account server to independent servers. |
Test Method |
Check the source code. |
Pass/Fail Determination |
Passes if the communication pathway is secured by encryption, or if the valid period for the service token has been set to a short amount of time. The application must also take measures to protect against replay attacks. |
6.8.1.4 Using the Principal ID Included in the Service Token
Guideline Item |
Independent servers must use the principal ID included in the service token.
|
---|---|
Software to Be Tested |
Applications that provide an independent-server service restricted to users with Nintendo Network accounts, and which use principal IDs on the independent server. |
Test Method |
Check the source code. |
Pass/Fail Determination |
Passes if the independent server does not directly acquire the principal ID from the client and then take it on faith that the ID is correct, but instead uses the principal ID included in the service token.
|
6.8.2 Linking Accounts
If your application obtains service tokens from the account server and also uses independent user accounts, Nintendo recommends linking the independent user accounts to the corresponding Nintendo Network accounts.
Note that account IDs may change due to Nintendo's operational circumstances. For that reason, use the principal ID for linking, because it will not change.
ID Name | Overview |
---|---|
Account ID | An ID created by the user at the time of network account creation. Used when signing into the network. |
Principal ID | A 32-bit value automatically assigned to a network account. Once assigned, this does not change. This is different from the principal ID used in identifying friends. |
See the Account System Developer's Guide for details regarding accounts.
No required guideline items.
6.8.3 Supporting Multiple Account Server Environments
It is possible that account IDs or principal IDs can overlap between different account servers. When identifying a Nintendo Network account on an independent server, you must handle the principal ID together in combination with the account server's environment name, and treat that combination as the unique ID. You must not treat the principal ID as a unique ID by itself. See the "Using Independent Licensee Servers" chapter in the Account System Developer's Guide for details.
For example, the following account-server environments exist.
- D1 to D9: Development Environment
- L1 to L9: Production Environment
- S1 to S9: Lotcheck Environment
The environment name always consists of one uppercase letter (A-Z) followed by a single-digit number (1-9), as in "L1". Design your specifications to support any combination used as this value without problems.
6.8.3.1 Identifying Nintendo Network Accounts in Multiple Account Server Environments
Guideline Item |
Applications must use the combination of principal ID and environment name when identifying Nintendo Network accounts.
|
---|---|
Software to Be Tested |
Applications that identify Nintendo Network accounts on independent servers.
|
Test Method |
Check the source code.
|
Pass/Fail Determination |
Passes if the application uses a combination of the principal ID and environment name as the unique ID it evaluates when identifying a Nintendo Network account.
|