Add-ons

1. Overview

Add-ons are used to support 3rd party systems like game platforms, text moderation, etc. You can install or uninstall the add-on on the portal. Only installed add-ons work for your title region. You can also modify the parameters of the installed add-ons anytime. You should be careful to check the parameters before you save them since it will work soon after saving.

2. Add-on Category

There are several categories of add-ons:

Auth add-on
Auth add-on is used to integrate 3rd-party authentication services for games like Steam, Epic, Xbox, Apple ID, etc. We also support account solution that encapsulates 3rd-party authentication, such as Tencent in-house INTL SDK. You may need to know how to implement the login flow on your client side. Here is the detailed manual for it.
tip
NOTE: Once you configured the auth add-on correctly, PGOS can verify the auth openID and token on the backend side. But before it works, you need to integrate the client SDK/API on the client side by yourself in advance.
Moderation add-on
Moderation add-on is used to integrate 3rd-party content moderation services. Once you configured it correctly, it will work soon on the backend side. This add-on works for all UGC content filtering like chat messages, player names, etc.
Middleware add-on
Middleware add-on is used to integrate 3rd-party middleware like IDIP/IDIP.
Payment add-on
Payment add-on is used to integrate payment systems like Tencent Midas, Xsolla, etc.

3. Auth Add-on

3.1 Intl Auth (Player Network Authentication)

Field Description:

Intl Game ID: The target Intl game id of current title region.
Intl Backend Domain: The target Intl backend domain, for example: test.intlgame.com.
Verify Login API Path: The target Intl verify login API path, for example: /v2/auth/verify_login.
Intl SDK Key: The target Intl sdk key of current title region.
Intl Server Key: The target Intl server key of current title region.

Further Reading:

3.2 WeGame Auth

Field Description:

Game ID: The target wegame game id of current title region.
Client ID: The target wegame client id of current title region.
Client Secret Key: The target wegame client secret key of current title region.

Further Reading:

3.3 PlayFab Auth

Field Description:

PlayFab Title ID : The target title id on PlayFab.
PlayFab Secret Key: The secret key on PlayFab.
How to get the PlayFab Secret Key:
1. Log in to the PlayFab dashboard of your game: https://developer.playfab.com/en-US/my-games
2. Enter Settings >Title settings:
3. Click the Secret Keys tab to view the secret key:

Further Reading:

3.4 Epic Auth

There is no field for Epic Auth.

Further Reading:

3.5 Steam Auth

Field Description:

Game ID: The target game ID on Steam.
Web API Key: The server key on Steam. Click here to get more information.
How to get steam Web API Key:
1. Log in to https://partner.steamgames.com/.
2. Enter User & Permissions > Manage Groups.
3. Click the group of your application.
4. The Web API Key is on the right.
Use In-Game Purchase Sandbox: For the in-game purchase sandbox, optional.

Further Reading:

3.6 XboxLive Auth

Field Description:

XboxLive Title ID : The target decimal title id on XboxLive .

Further Reading:

3.7 PlayStationNetwork Auth

Field Description:

PlayStationNetwork Client ID : The target client id on PlayStationNetwork.
PlayStationNetwork Client Secret : The target client secret on PlayStationNetwork.
PlayStationNetwork Environment : The target environment on PlayStationNetwork.

Further Reading:

tip

Since PGOS uses the PlayStation Auth Web API to conduct PlayStation authentication operations, and PlayStation requires that servers need to be added to the IP whitelist. If you want to use the Playstation add-on, please contact PGOS to obtain the IP information and then add it to the PlayStation IP whitelist.

3.8 Nintendo Auth

Field Description:

Nintendo Application ID : The target application id on Nintendo.

Further Reading:

3.9 JWT Auth

JWT (JSON Web Token) is an open standard (RFC 7519) that allows you to use your own identity provider to authenticate players. To login PGOS with JWT, you must install the JWT addon on the portal console first and configure the JWT verification settings, then you can start your coding work.

What is JWT?

JWT (JSON Web Token) is a compact, URL-safe token format for securely transmitting information between parties. For a comprehensive introduction, visit https://jwt.io/introduction.

Basic Structure: A JWT consists of three parts separated by dots (.):

header.payload.signature

Header: Contains the token type (typ) and signing algorithm (alg), e.g., {"alg": "RS256", "typ": "JWT"}
Payload: Contains the claims (user data), e.g., {"sub": "user123", "exp": 1735000000, "iss": "my-auth-server"}
Signature: Created by signing the encoded header and payload with a secret key, used to verify the token hasn't been tampered with

Each part is Base64URL-encoded, resulting in a token like: eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1c2VyMTIzIn0.signature...

bb518aaf-6da1-419f-a8ef-5d144aed786f

Allowed Algorithms

Definition: A whitelist of JWT signing algorithms accepted by the server
Purpose: Prevents algorithm downgrade attacks by restricting clients to use only secure algorithms
Example: ["HS256", "HS384", "HS512", "RS256", "ES256"]
Security: It's recommended to enable only necessary algorithms to avoid increasing the attack surface by supporting too many algorithms

Expected Issuer

Definition: The expected value of the iss field in JWT Token
Purpose: Verifies the trustworthiness of the Token source, ensuring only Tokens from specified issuers are accepted
Example: "https://auth.example.com" or "game-auth-service"
Validation: If this field is configured, the JWT's iss claim must match exactly

Expected Audiences

Definition: A list of expected values for the aud field in JWT Token
Purpose: Ensures the Token was issued for the current service, preventing Token misuse by other services
Example: ["game-api", "user-service"]
Validation: The JWT's aud claim must contain at least one value from the configuration

Shared Secrets

Used for symmetric encryption verification with HMAC algorithms (HS256/HS384/HS512):

kid (Key ID)
- Definition: Key identifier used to distinguish different keys
- Purpose: The kid field in JWT Header specifies which key to use for verification
- Example: "main-key-2024", "backup-key"
- Usage: Supports key rotation and multi-key management

secret (Key Content)
- Definition: Base64 encoded HMAC key
- Purpose: The actual key material used for JWT signature verification
- Example: "dGVzdC1zZWNyZXQtMTIzNDU2Nzg5MA==" (base64 encoded)
- Security: Must be sufficiently long and random, recommended 64 bytes or more

algorithms (Supported Algorithms)
- Definition: List of HMAC algorithms supported by this key
- Purpose: One key can support multiple algorithms, providing flexibility
- Example: ["HS256", "HS384", "HS512"]
- Advantage: Simplifies key management and supports gradual algorithm upgrades

Public Keys

Used for asymmetric encryption verification with RSA/ECDSA algorithms (RS256/ES256, etc.):

kid (Key ID)
- Definition: Public key identifier, same function as kid in Shared Secrets
- Purpose: The kid in JWT Header specifies which public key to use for verification
- Example: "rsa-key-001", "ecdsa-key-prod"
- Management: Usually managed in pairs with private keys, supports key rotation

pem (PEM Format Public Key)
- Definition: PEM format encoded RSA or ECDSA public key
- Purpose: Public key material used for asymmetric algorithm signature verification, must be in standard PEM format with complete header and footer markers
- Example:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
-----END PUBLIC KEY-----

algorithms (Supported Algorithms)
- Definition: List of asymmetric algorithms supported by this public key
- Purpose: Specifies which signing algorithms the public key can be used for
- Example: ["RS256", "RS384", "RS512"] or ["ES256", "ES384"]
- Limitation: RSA keys are used for RS algorithms, ECDSA keys are used for ES algorithms

JWKS Endpoints

JWKS (JSON Web Key Set) endpoints allow you to dynamically fetch public keys from a remote URL. This is useful when your identity provider rotates keys periodically.

url
- Definition: The HTTPS URL of the JWKS endpoint
- Purpose: PGOS will fetch and cache the public keys from this endpoint
- Example: "https://auth.example.com/.well-known/jwks.json"
- Requirement: Must be a valid HTTPS URL

Supported URL Types

PGOS supports three types of URLs for JWKS endpoints and automatically detects the response format:

#	Name	Specification	URL Pattern	Purpose
1	JWKS (JSON Web Key Set)	RFC 7517	Typically at `/.well-known/jwks.json` or specified by `jwks_uri`	Standard public key set format ✅
2	OpenID Connect Discovery Document	OpenID Connect Discovery 1.0	`.well-known/openid-configuration`	Metadata document containing `jwks_uri` and other provider info
3	X.509 Certificate Chain	Google proprietary format	`/x509/` or `/metadata/x509/`	PEM certificate list (non-standard)

Response Format Examples

1. JWKS (JSON Web Key Set) - Standard Format

// URL: https://www.googleapis.com/service_accounts/v1/jwk/securetoken@system.gserviceaccount.com
{
  "keys": [
    {
      "kid": "abc123def456",
      "kty": "RSA",
      "alg": "RS256",
      "use": "sig",
      "n": "0vx7agoebGcQSuuPiLJXZptN9nn...",
      "e": "AQAB"
    }
  ]
}

This is the standard format defined by RFC 7517, containing a keys array with JWK objects.

2. OpenID Connect Discovery Document

// URL: https://securetoken.google.com/{project-id}/.well-known/openid-configuration
{
  "issuer": "https://securetoken.google.com/{project-id}",
  "jwks_uri": "https://www.googleapis.com/service_accounts/v1/jwk/securetoken@system.gserviceaccount.com",
  "response_types_supported": ["id_token"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"]
}

When PGOS detects this format (by the presence of jwks_uri), it automatically follows the jwks_uri to fetch the actual keys.

3. X.509 Certificate Chain - Google Proprietary Format

// URL: https://www.googleapis.com/robot/v1/metadata/x509/securetoken@system.gserviceaccount.com
{
  "kid1": "-----BEGIN CERTIFICATE-----\nMIIDHDCC...\n-----END CERTIFICATE-----\n",
  "kid2": "-----BEGIN CERTIFICATE-----\nMIIDHDCC...\n-----END CERTIFICATE-----\n"
}

This is a Google-specific format where each key is a kid -> PEM Certificate mapping. PGOS extracts the public key from each certificate.

Automatic Format Detection

PGOS automatically detects and parses all three formats based on the response content:

If the response contains a keys array → parsed as JWKS
If the response contains a jwks_uri field → follows the URI to fetch keys
If all values are PEM certificates → parsed as X.509 format

This allows you to configure any of these URL types without additional settings.

Best Practices for JWKS Key Rotation

When using JWKS endpoints, key rotation is an important consideration. Here are the recommended practices:

1. Key Rotation with Overlap (Recommended)

When rotating keys, your identity provider should publish both the old and new keys simultaneously during a transition period. This ensures that tokens signed with either key can be verified without interruption.

Phase 1: { keys: [KeyA] }           // Only old key
Phase 2: { keys: [KeyA, KeyB] }     // Both keys during transition
Phase 3: { keys: [KeyB] }           // Only new key

This is the industry standard practice used by major identity providers (Auth0, Okta, Google, etc.) and is strongly recommended for your implementation.

2. Automatic Refresh on Unknown Kid

PGOS automatically refreshes the JWKS cache when it encounters an unknown kid that is not in the current cache. This allows new keys to be discovered without waiting for the cache to expire. However, this refresh is rate-limited (default: once per 5 minutes per endpoint) to prevent abuse.

Important: If a token arrives with a new kid before the cache is refreshed, the first request will fail with a "key not found" error. Subsequent requests (after the cache refresh) will succeed. This is why Method 1 (Key Rotation with Overlap) is strongly recommended—it avoids this issue entirely.

3. HTTP Cache-Control Support

PGOS respects the Cache-Control: max-age header from JWKS endpoint responses. If your identity provider returns this header, PGOS will use it to determine the cache TTL, ensuring optimal cache freshness based on your provider's recommendations.

JWT Token Requirements

The JWT token should contain the following claims:

Claim	Required	Description
`kid`	Required	Key ID in the JWT header. Used to identify which key to use for verification.
`exp`	Required	Expiration time. The token will be rejected if expired.
`iss`	Conditional	Issuer. Required if `expected_issuer` is configured.
`aud`	Conditional	Audience. Required if `expected_audience` is configured.
`sub`	Optional	Subject identifier. If present, must match the `account_open_id` field in the login request.
`jti`	Optional	JWT ID. If present, used for replay attack prevention.
`iat`	Optional	Issued at time. Used for validation with clock skew tolerance.
`nbf`	Optional	Not before time. The token will be rejected if used before this time.

Key Lookup Strategy and Duplicate Kid Warning

How PGOS Looks Up Keys

When verifying a JWT, PGOS uses both the kid (Key ID) and alg (Algorithm) from the token header to find the matching key. The lookup follows this priority order:

Shared Secrets (for symmetric algorithms like HS256/HS384/HS512)
Public Keys (for asymmetric algorithms like RS256/ES256)
JWKS Endpoints (remote key sets)

PGOS searches for a key that matches both the kid and the alg. If a key with the matching kid is found but doesn't support the requested algorithm, PGOS continues searching in the next key source.

Avoid Duplicate Kid Values

It is strongly recommended to use unique kid values across all your configured keys (Shared Secrets, Public Keys, and JWKS). If multiple keys share the same kid:

Keys are matched by both kid and alg, so different key types (symmetric vs asymmetric) with the same kid may work if they use different algorithms
However, this can lead to confusing configurations and unexpected behavior
If two keys have identical kid and overlapping algorithms, only the first one (by priority order) will be used

Best Practice: Assign a unique, descriptive kid to each key, such as "hmac-prod-2024", "rsa-key-v2", or "ecdsa-signing-key".

Supported Algorithms

Algorithm	Type	Description
HS256	Symmetric	HMAC using SHA-256
HS384	Symmetric	HMAC using SHA-384
HS512	Symmetric	HMAC using SHA-512
RS256	Asymmetric	RSA signature using SHA-256
RS384	Asymmetric	RSA signature using SHA-384
RS512	Asymmetric	RSA signature using SHA-512
ES256	Asymmetric	ECDSA using P-256 curve and SHA-256
ES384	Asymmetric	ECDSA using P-384 curve and SHA-384
ES512	Asymmetric	ECDSA using P-521 curve and SHA-512
PS256	Asymmetric	RSA-PSS using SHA-256
PS384	Asymmetric	RSA-PSS using SHA-384
PS512	Asymmetric	RSA-PSS using SHA-512

Further Reading:

Introduction to JSON Web Tokens

4. Moderation Add-on

4.1 Content Moderation

ACE SDK provides profanity-checking and filtering functionality ( User Input Service). PGOS adapted to the ACE SDK and provides an add-on to enable content moderation for related API.

4.1.1 Content Moderation Integration

You can set the content moderation configuration on the portal.

There are two different filter modes：

Normal Mode: Different API calls behave differently when sensitive words are detected, please refer to the document to see the logic Related API and Profanity Handling.
Strict Mode: When sensitive words are detected, all API calls will return an error.

4.1.2 Field Description

Enabled: switch to enable content moderation.
APP ID: IEGG UIC service APP ID of the game.
APP KEY: IEGG UIC service APP KEY of the game.
UIC Region: the region where content moderation services are used.
Filter Mode: Different modes apply to different countries' policies.

API	Profanity Handling
SendInstantChatMsg SendPersonalTextMsg SendGroupTextMsg	In normal mode, when there are sensitive words, the API will directly filter the sensitive words and return success. The API call will return an error in strict mode if sensitive words are detected.
SetGroupDesc SetGroupAnnouncement	In normal mode, when input content is with sensitive words, the API will filter the sensitive words, return success, and also indicate there are sensitive words. The API calling will return an error in strict mode if sensitive words detected
SetMyName CreateParty CreateLobby EditLobbyInfo SetMyGroupNickName CreateGroup SetGroupName SetGroupMemberRemark	No matter what the filter mode is, when there are sensitive words, the API call will return an error. Please refer to the key error handling in the corresponding service manual for more details.

4.1.4 Reporting of TSS information

TSS needs to submit relevant information every time it detects, The way to report can view the document

4.2 Content Moderation Report

Only used for Tencent games released in China Mainland.

Field Description:

CC ID: The ID of the game registered from the platform.

5. Middleware Add-on

5.1 IDIP

IDIP is a service that allows the interaction between the operation merchandising system and the core data of your game, which is deployed outside PGOS.

IDIP is commonly used in marketing services for the following purposes:

Award player with items
Query players' activities
Ban or unban a player
Send mail to players
......

graph LR CustomerServices --> IDIP IDIP --> HTTPServer HTTPServer --> PlayerData

In general, If you integrate IDIP directly, you need to implement an HTTP server that responds to IDIP requests.

graph LR CustomerServices --> IDIP IDIP --> PGOSAdapter PGOSAdapter --> VirtualServer VirtualServer --> PlayerData

However, If a game uses PGOS, we provide an adapter service to route all IDIP requests to the Virtual Server, so you can write Node.JS code to handle IDIP requests.

To integrate IDIP on PGOS, two things need to be done:

Configure the PGOS Adapter with a secret key and paste the callback URL to the IDIP side.
Write virtual server code to handle IDIP requests.

5.1.1 IDIP Integration Steps

Firstly, you need to register your game at the IDIP web portal.

Then three steps need to be done on the PGOS web portal:

Specify a virtual server function to use as an IDIP request handler.
Input the secret key, and ensure its value is the same as IDIP_sig_key configured on the IDIP Portal.
Copy and paste the Callback URL to the IDIP_server_info section on the IDIP Portal.

The last step is to handle IDIP requests in your virtual server functions according to the agreement of the IDIP Protocol

5.1.2 About Virtual Server

After the PGOS Adapter handles the signature verification logic in the IDIP protocol, developers are still required to implement service code to respond to IDIP requests. This code can be written in any programming language, as long as it can properly handle HTTP requests with the URL path /pgos_idip.

For guidance on implementing the Virtual Server, please refer to the documentation.

When PGOS receives a request from IDIP, it triggers a call to the Virtual Server. After the Virtual Server completes processing, PGOS records a log entry containing both the request and response details of the HTTP transaction. These logs can be viewed under the Add-ons/IDIP/Logs tab.

5.2 Player Credit

Only used for Tencent games released in China Mainland.

Field Description:

Game ID: The ID of the game registered from the credit platform.
Source: The registration source from the credit platform helper.
TP Token: The TP Token is registered from the credit platform helper.
Credit Chatting: The scene ID for chatting.
Credit Friend: The scene ID for a friend.
Credit Group: The scene ID for a group.
Credit Player Info: The scene ID for player information.

5.3 GME

Field Description:

GME App ID: The app ID generated by the GME platform.
Permission Key: The permission key generated by the GME platform.
GME Type: Choose the type for GME usage.

6. Third-party Payment Add-on

6.1 Xbox

You can upload Relying Party and Business Partner Certificate file to install. Please input file password if exist.

6.2 Midas Global

Games published by Tencent can use the payment service provided by Midas to implement the purchase of items or currency in PGOS. Refer to economy document to learn about the configuration and application of Midas Global Addon.

1. Overview​

2. Add-on Category​

3. Auth Add-on​

3.1 Intl Auth (Player Network Authentication)​

3.2 WeGame Auth​

3.3 PlayFab Auth​

3.4 Epic Auth​

3.5 Steam Auth​

3.6 XboxLive Auth​

3.7 PlayStationNetwork Auth​

3.8 Nintendo Auth​

3.9 JWT Auth​

4. Moderation Add-on​

4.1 Content Moderation​

4.1.1 Content Moderation Integration​

4.1.2 Field Description​

4.1.3 Related API and Profanity Handling​

4.1.4 Reporting of TSS information​

4.2 Content Moderation Report​

5. Middleware Add-on​

5.1 IDIP​

5.1.1 IDIP Integration Steps​

5.1.2 About Virtual Server​

5.2 Player Credit​

5.3 GME​

6. Third-party Payment Add-on​

6.1 Xbox​

6.2 Midas Global​

1. Overview

2. Add-on Category

3. Auth Add-on

3.1 Intl Auth (Player Network Authentication)

3.2 WeGame Auth

3.3 PlayFab Auth

3.4 Epic Auth

3.5 Steam Auth

3.6 XboxLive Auth

3.7 PlayStationNetwork Auth

3.8 Nintendo Auth

3.9 JWT Auth

4. Moderation Add-on

4.1 Content Moderation

4.1.1 Content Moderation Integration

4.1.2 Field Description

4.1.3 Related API and Profanity Handling

4.1.4 Reporting of TSS information

4.2 Content Moderation Report

5. Middleware Add-on

5.1 IDIP

5.1.1 IDIP Integration Steps

5.1.2 About Virtual Server

5.2 Player Credit

5.3 GME

6. Third-party Payment Add-on

6.1 Xbox

6.2 Midas Global