GS2-Account Master Data Reference

Reference for the master data format and the models to be imported

Master Data Format

{
  "version": "2024-07-30",
  "takeOverTypeModels": [
    {
      "type": "[int]Slot Number",
      "metadata": "[string?]Metadata",
      "takeOverMethod": "[string (enum)]Takeover Method",
      "openIdConnectSetting": {
        "configurationPath": "[string]OpenID Connect Configuration URL",
        "clientId": "[string]Client ID",
        "clientSecret": "[string]Client Secret",
        "appleTeamId": "[string]Apple Developer Team ID",
        "appleKeyId": "[string]Key ID registered with Apple",
        "applePrivateKeyPem": "[string]Private Key received from Apple",
        "doneEndpointUrl": "[string?]Redirect URL after authentication is completed",
        "additionalScopeValues": [
          {
            "key": "[string]Name",
            "value": "[string?]Value"
          }
        ],
        "additionalReturnValues": [
          "[string]Additional claim name returned from OpenID Connect"
        ]
      },
      "issuedCodeSetting": {
        "expiresDays": "[int]Validity Period (days)",
        "maxFailedAttempts": "[int?]Maximum Number of Failed Attempts",
        "deleteOnUse": "[bool]Expire the code when it is used"
      }
    }
  ]
}
TypeConditionRequiredDefaultValue LimitsDescription
versionstring
✓
2024-07-30Master data format version
takeOverTypeModelsList<TakeOverTypeModel>~ 1000 itemsTakeover Type Model
This model defines Takeover Information.

Takeover Information is used when changing devices or transferring an account across platforms.
It consists of a unique string that identifies an individual and a password; by entering the correct combination, a GS2 Account (anonymous account) can be retrieved.

Multiple sets of Takeover Information can be configured for a single Account.
To configure multiple sets, you must assign each one to a different slot.
Slots can be specified from 0 to 1024, allowing for up to 1,025 types of Takeover Information to be set.

A typical example would be to store the account information for “Sign in with Apple” in slot 0 and the information for a Google account in slot 1.
It should be noted that this Takeover Information serves only as a container for data; the authentication mechanism for social accounts must be prepared separately.

Models

TakeOverTypeModel

Takeover Type Model

This model defines Takeover Information.

Takeover Information is used when changing devices or transferring an account across platforms. It consists of a unique string that identifies an individual and a password; by entering the correct combination, a GS2 Account (anonymous account) can be retrieved.

Multiple sets of Takeover Information can be configured for a single Account. To configure multiple sets, you must assign each one to a different slot. Slots can be specified from 0 to 1024, allowing for up to 1,025 types of Takeover Information to be set.

A typical example would be to store the account information for “Sign in with Apple” in slot 0 and the information for a Google account in slot 1. It should be noted that this Takeover Information serves only as a container for data; the authentication mechanism for social accounts must be prepared separately.

TypeConditionRequiredDefaultValue LimitsDescription
takeOverTypeModelIdstring
*
~ 1024 charsTakeover Type Model GRN
* Set automatically by the server
typeint
✓
0 ~ 1024Slot Number
Specified in the range of 0 to 1024 to distinguish different types of Takeover Information.
metadatastring~ 2048 charsMetadata
Arbitrary values can be set in the metadata.
Since they do not affect GS2’s behavior, they can be used to store information used in the game.
takeOverMethodstring (enum)
enum {
  “openIdConnect”,
  “issuedCode”
}
“openIdConnect”Takeover Method
How the takeover information of this slot is registered and verified.
openIdConnect takes over with an ID token issued by an OpenID Connect-compliant Identity Provider (IdP).
issuedCode takes over with a user ID and password issued by GS2 (IssueTakeOverCode).
DefinitionDescription
openIdConnectOpenID Connect
issuedCodeIssued code
openIdConnectSettingOpenIdConnectSetting{takeOverMethod} == “openIdConnect”
✓*
OpenID Connect Configuration
Configuration for integrating with an OpenID Connect-compliant Identity Provider (IdP). Includes the discovery URL, client credentials, and platform-specific settings such as Sign in with Apple parameters.
* Required if takeOverMethod is “openIdConnect”
issuedCodeSettingIssuedCodeSetting{takeOverMethod} == “issuedCode”
✓*
Issued Takeover Code Configuration
Configuration of the code issued by IssueTakeOverCode: the validity period, the number of failed attempts before it expires, and whether it expires when used.
* Required if takeOverMethod is “issuedCode”

OpenIdConnectSetting

OpenID Connect Configuration

By registering the settings of an OpenID Connect-compliant IdP, IdP integration can be configured and used as Takeover Information.

TypeConditionRequiredDefaultValue LimitsDescription
configurationPathstring
✓
~ 1024 charsOpenID Connect Configuration URL
The discovery endpoint URL of the OpenID Connect provider. Must follow the well-known format (e.g., https://example.com/.well-known/openid-configuration).
clientIdstring
✓
~ 1024 charsClient ID
The client ID of the application registered with the IdP.
clientSecretstring{configurationPath} != “https://appleid.apple.com/.well-known/openid-configuration”
✓*
~ 1024 charsClient Secret
* clientSecret is required when the configurationPath is not “https://appleid.apple.com/.well-known/openid-configuration”, i.e., for other IdP integrations.
appleTeamIdstring{configurationPath} == “https://appleid.apple.com/.well-known/openid-configuration”
✓*
~ 1024 charsApple Developer Team ID
The team ID from the Apple Developer account. Required for Sign in with Apple authentication.
* Required if configurationPath is “https://appleid.apple.com/.well-known/openid-configuration”
appleKeyIdstring{configurationPath} == “https://appleid.apple.com/.well-known/openid-configuration”
✓*
~ 1024 charsKey ID registered with Apple
The key ID registered in the Apple Developer account for Sign in with Apple.
* Required if configurationPath is “https://appleid.apple.com/.well-known/openid-configuration”
applePrivateKeyPemstring{configurationPath} == “https://appleid.apple.com/.well-known/openid-configuration”
✓*
~ 10240 charsPrivate Key received from Apple
The private key in PEM format downloaded from the Apple Developer portal. Required for Sign in with Apple authentication.
* Required if configurationPath is “https://appleid.apple.com/.well-known/openid-configuration”
doneEndpointUrlstring~ 1024 charsRedirect URL after authentication is completed
If not specified, the user will be redirected to /authorization/done.
The id_token is included as a query parameter.
additionalScopeValuesList<ScopeValue>[]0 ~ 10 itemsAdditional scopes obtained with OpenID Connect
Additional OAuth scopes to request from the IdP beyond the default OpenID Connect scopes. Allows retrieving extra user information during authentication.
additionalReturnValuesList<string>[]0 ~ 10 itemsAdditional claim name returned from OpenID Connect
Additional claim names extracted from the ID token or UserInfo response and included in the authentication result. Specified claims are extracted and returned alongside the standard authentication result.

IssuedCodeSetting

Issued Takeover Code Configuration

Configuration for takeover information whose user ID and password are issued by GS2 instead of being chosen by the player. The issued code expires after the specified number of days, and can also be made to expire when it is used or when the password is entered incorrectly too many times.

TypeConditionRequiredDefaultValue LimitsDescription
expiresDaysint
✓
1 ~ 365Validity Period (days)
The number of days from issuance until the issued code expires.
An expired code can no longer be used for takeover.
maxFailedAttemptsint1 ~ 100Maximum Number of Failed Attempts
The issued code expires when the password is entered incorrectly this many times.
The count is reset when a takeover with the code succeeds.
If omitted, the code does not expire no matter how many times the password is entered incorrectly.
deleteOnUsebooltrueExpire the code when it is used
When enabled, the issued code expires once a takeover with it succeeds.
When disabled, the code can be used any number of times until it expires.

ScopeValue

Scope Value

A key-value pair representing an additional OAuth scope value obtained during OpenID Connect authentication. Used to store extra data retrieved from the IdP beyond the standard OpenID Connect claims.

TypeConditionRequiredDefaultValue LimitsDescription
keystring
✓
~ 64 charsName
The scope name that was requested from the IdP during authentication.
valuestring~ 51200 charsValue
The value returned by the IdP for the corresponding scope.