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]Team ID of Apple Developer",
        "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 values returned from OpenID Connect"
        ]
      }
    }
  ]
}
Type Condition Required Default Value Limits Description
version string
✓
 2024-07-30 Format version of master data
takeOverTypeModels List<TakeOverTypeModel> ~ 1000 items TakeOver Type Model
This model defines TakeOver Information.

TakeOver Information is used when changing devices or moving/sharing an account across platforms.
It consists of a unique string that identifies an individual and a password; by entering the correct combination, an Account (GS2 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 moving/sharing an account across platforms. It consists of a unique string that identifies an individual and a password; by entering the correct combination, an Account (GS2 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 Apple Sign In 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 Team ID of Apple Developer
The team ID from the Apple Developer account. Required for Apple Sign In 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 Apple Sign In 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, it will transition to /authorization/done.
id_token is attached to the Query String.
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 values returned from OpenID Connect
Additional claim names from the ID token or UserInfo response to include in the return values. 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.