6.8 Independent Servers: Nintendo Network Accounts

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
  1. Start the application on a system with a registered NNID, connect to the independent server, and then power off the system.

  2. Turn the system on, start the application again, and connect to the independent server.
  3. If you performed steps 1 and 2 using an NNID not yet registered as a test NNID in the Account Developer Portal, register it.
  4. Access the Account Developer Portal and go to the Register Test NNID home screen. On the list of registered NNIDs, select the one registered to the system you used to perform steps 1 and 2, and open the dashboard for that NNID.

  5. Under the Actions dropdown, select Service Token Activity.

  6. Go to Application and select the application you are testing, then display the service token acquisition log.

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:
  • Failed acquisition of service token
  • Expired service token
Test Method
  1. Start up the application and connect to the independent server, then test every possible operation while connected to the server.
  2. Access the Account Developer Portal and go to the Register Test NNID home screen. On the list of registered NNIDs, select the one you have been using to play the application you are testing, and open the dashboard for that NNID.

  3. Under the Actions dropdown, select Service Token Activity.

  4. Go to Application and select the application you are testing, then display the service token acquisition log.
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.

Table 6-2 ID Types
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.

Note:

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.

 


CONFIDENTIAL