GS2-Account Master Data Reference

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

Master Data Format

{
  "version": "2024-07-30",
  "takeOverTypeModels": [
    {
      "type": "[int]Slot Number",
      "metadata": "[string?]Metadata",
      "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"
        ]
      }
    }
  ]
}
Type Condition Required Default Value Limits Description
version string
✓
 2024-07-30 Master data format version
takeOverTypeModels List<TakeOverTypeModel> ~ 1000 items 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.

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.

Type Condition Required Default Value Limits Description
takeOverTypeModelId string
*
 ~ 1024 chars Takeover Type Model GRN
* Set automatically by the server
type int
✓
 0 ~ 1024 Slot Number
Specified in the range of 0 to 1024 to distinguish different types of Takeover Information.
metadata string ~ 2048 chars Metadata
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.
openIdConnectSetting OpenIdConnectSetting
✓
 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.

OpenIdConnectSetting

OpenID Connect Configuration

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

Type Condition Required Default Value Limits Description
configurationPath string
✓
 ~ 1024 chars OpenID 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).
clientId string
✓
 ~ 1024 chars Client ID
The client ID of the application registered with the IdP.
clientSecret string {configurationPath} != “https://appleid.apple.com/.well-known/openid-configuration”
✓*
 ~ 1024 chars Client Secret
* clientSecret is required when the configurationPath is not “https://appleid.apple.com/.well-known/openid-configuration”, i.e., for other IdP integrations.
appleTeamId string {configurationPath} == “https://appleid.apple.com/.well-known/openid-configuration”
✓*
 ~ 1024 chars Apple 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”
appleKeyId string {configurationPath} == “https://appleid.apple.com/.well-known/openid-configuration”
✓*
 ~ 1024 chars Key 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”
applePrivateKeyPem string {configurationPath} == “https://appleid.apple.com/.well-known/openid-configuration”
✓*
 ~ 10240 chars Private 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”
doneEndpointUrl string ~ 1024 chars Redirect 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.
additionalScopeValues List<ScopeValue> [] 0 ~ 10 items Additional 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.
additionalReturnValues List<string> [] 0 ~ 10 items Additional 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.

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.

Type Condition Required Default Value Limits Description
key string
✓
 ~ 64 chars Name
The scope name that was requested from the IdP during authentication.
value string ~ 51200 chars Value
The value returned by the IdP for the corresponding scope.