Identity Providers #

Pragma Engine enables cross-play, cross-progression, and cross-platform experiences by supporting multiple identity providers with account linking. This allows players to start on one platform and link their account when switching to another platform.

Identity providers are linked to a Pragma Account and used for authentication and platform-specific social integration. These accounts are isolated from player and social data to enable seamless cross-platform experiences.

Test provider #

The Pragma Engine test provider uses the name Unsafe Provider to indicate that it’s only for internal and testing use cases and should not be enabled in production. It can also be used in load testing to allow the creation of millions of test accounts.

When run in development mode, the platform will populate the Test Provider with default accounts (test01 - test20). Below is an example of how to enable the Unsafe Identity Provider:

social:
  serviceConfigs:
    UnsafeIdentityDaoConfig:
      databaseConfig:
        username: "username"
        password: "password"
        hostPortSchema: "host-port-schema"
  pluginConfigs:
    AccountService.identityProviderPlugins:
      plugins:
        Unsafe:
          class: "pragma.account.UnsafeIdentityProviderPlugin"

Configure identity providers #

Pragma Engine is highly configurable. You can enable additional plugins and custom services via the config files located in the 5-ext/config directory. Add the relevant configuration code blocks to local-dev.yml (for testing) or common.yml (for production) under the social section.

For identity providers not listed, studios can implement a custom Identity Provider Plugin. See the Custom Identity Provider concepts page for more information.
Steam configuration
valuedescription
appIdSteam numerical value used to identify a game on Steam
steamWebAPIKeyauthorization key used to connect with the Steam Web API
restrictByAppOwnershipoptional

boolean determining whether to reject users if they don’t own the app or are on a timed trial
restrictByAccountBanoptional

boolean determining whether to reject users who have been developer banned or VAC banned
playerLoginEnabledoptional

boolean determining whether to establish a player session with this identity provider
operatorLoginEnabledoptional

boolean determining whether to establish an operator session with this identity provider
accountLinkingEnabledoptional

boolean determining whether you can link accounts with this identity provider
showPortalLoginButtonoptional

boolean determining whether this login method is available on the portal login page
visibleToOtherPlayersoptional

boolean determining whether Steam account information is visible to other players
social:
  pluginConfigs:
    AccountService.identityProviderPlugins:
      plugins:
        Steam:
          class: "pragma.account.SteamIdentityProviderPlugin"
          config:
            appId: "${steamAppId}"
            steamWebAPIKey: "${steamWebApiKey}"
            restrictByAppOwnership: false
            restrictByAccountBan: false
            playerLoginEnabled: true
            operatorLoginEnabled: false
            accountLinkingEnabled: true
            showPortalLoginButton: false
            visibleToOtherPlayers: true
Epic configuration
valuedescription
clientIdEpic ID that identifies developer’s Epic app while making authorization requests
clientSecretencrypted OAuth secret for the Epic app referenced by the clientId property
redirectUrioptional

backend authorization endpoint that Epic uses to validate OAuth handshakes
restrictByCatalogItemOwnershipoptional

boolean determining whether to reject users if they do not own the catalog item specified

If set to true, the following configs must be configured: sandboxId and catalogItemId.
sandboxIdID of the sandbox environment you’d like to validate against
catalogItemIdID of the catalog item you’d like to validate against. Typically this will be the Game Item ID of your game.
deploymentIdoptional

This field is only required if OAuth login is enabled (portal login).

ID of the deployment you’d like to validate against. For more information, refer to Epic’s documentation on Requesting an Access Token.
playerLoginEnabledboolean determining whether to establish a player session with this identity provider
operatorLoginEnabledoptional

boolean determining whether to establish an operator session with this identity provider
accountLinkingEnabledoptional

boolean determining whether you can link accounts with this identity provider
showPortalLoginButtonoptional

boolean determining whether this login method is available on the portal login page
visibleToOtherPlayersoptional

boolean determining whether Epic account information is visible to other players
social:
  pluginConfigs:
    AccountService.identityProviderPlugins:
      plugins:
        Epic:
          class: "pragma.account.EpicIdentityProviderPlugin"
          config:
            clientId: "epic-client-id"
            clientSecret: "encrypted-epic-client-secret"
            redirectUri: "http://localhost:11200/v1/account/oauth-redirect/EPIC"
            restrictByCatalogItemOwnership: true
            deploymentId: "epic-deployment-id"
            sandboxId: "epic-sandbox-id"
            catalogItemId: "epic-catalog-item-id"
            playerLoginEnabled: true
            operatorLoginEnabled: false
            accountLinkingEnabled: true
            showPortalLoginButton: false
            visibleToOtherPlayers: true
Discord configuration
valuedescription
clientIdDiscord OAuth ID that identifies developer’s Discord app while making authorization requests
clientSecretencrypted OAuth secret for the Discord app referenced by the clientId property
redirectUrioptional

backend authorization endpoint that Discord uses to validate OAuth handshakes
botTokenoptional

unique ID for Discord server bots
guildIdoptional

Discord-defined guild identifier
allowedRoleIdsoptional

map of user roles that are allowed to authenticate
playerLoginEnabledoptional

boolean determining whether to establish a player session with this identity provider
operatorLoginEnabledoptional

boolean determining whether to establish an operator session with this identity provider
accountLinkingEnabledoptional

boolean determining whether you can link accounts with this identity provider
showPortalLoginButtonoptional

boolean determining whether this login method is available on the portal login page
visibleToOtherPlayersoptional

boolean determining whether Discord account information is visible to other players
social:
  pluginConfigs:
    AccountService.identityProviderPlugins:
      plugins:
        Discord:
          class: "pragma.account.DiscordIdentityProviderPlugin"
          config:
            clientId: "${discordClientId}"
            clientSecret: "${discordClientSecret}"
            redirectUri: "http://localhost:11000/v1/account/discord-redirect"
            botToken: "${discordBotToken}"
            guildId: "${guildId}"
            allowedRoleIds: 
              1: "${RoleId1}"
              2: "${RoleId2}"
            playerLoginEnabled: true
            operatorLoginEnabled: false
            accountLinkingEnabled: true
            showPortalLoginButton: false
            visibleToOtherPlayers: false
Check out the Unreal and Unity Setup Guides for Discord implementation details.
Google configuration
valuedescription
clientIdGoogle OAuth ID that identifies developer’s Google app while making authorization requests
clientSecretencrypted OAuth secret for the Google app referenced by the clientId property
redirectUrioptional

backend authorization endpoint that Google uses to validate OAuth handshakes
allowedDomainsoptional

map of specific domains that are authorized for access–if this value is defined, all other domains are rejected
playerLoginEnabledoptional

boolean determining whether to establish a player session with this identity provider
operatorLoginEnabledoptional

boolean determining whether to establish an operator session with this identity provider
accountLinkingEnabledoptional

boolean determining whether you can link accounts with this identity provider
showPortalLoginButtonoptional

boolean determining whether this login method is available on the portal login page
visibleToOtherPlayersoptional

boolean determining whether Google account information is visible to other players
social:
  pluginConfigs:
    AccountService.identityProviderPlugins:
      plugins:
        Google:
          class: "pragma.account.GoogleIdentityProviderPlugin"
          config:
            allowedDomains:
              1: "${allowedDomain1}"
              2: "${allowedDomain2}"
            clientId: "${googleClientId}"
            clientSecret: "${googleClientSecret}"
            redirectUri: "http://localhost:11000/v1/account/google-redirect"
            playerLoginEnabled: true
            operatorLoginEnabled: false
            accountLinkingEnabled: true
            showPortalLoginButton: false
            visibleToOtherPlayers: false
Check out the Google developer documentation for creating access credentials.
Google Workspace configuration

Google Workspace has been added as an identity provider to support the difference between a public google authentication and an internal one.

valuedescription
clientIdGoogle Workspace OAuth ID that identifies developer’s Google Workspace app while making authorization requests
clientSecretencrypted OAuth secret for the Google Workspace app referenced by the clientId property
redirectUrioptional

backend authorization endpoint that Google Workspace uses to validate OAuth handshakes
allowedDomainsoptional

map of specific domains that are authorized for access–if this value is defined, all other domains are rejected
playerLoginEnabledoptional

boolean determining whether to establish a player session with this identity provider
operatorLoginEnabledoptional

boolean determining whether to establish an operator session with this identity provider
accountLinkingEnabledoptional

boolean determining whether you can link accounts with this identity provider
showPortalLoginButtonoptional

boolean determining whether this login method is available on the portal login page
visibleToOtherPlayersoptional

boolean determining whether Google Workspace account information is visible to other players
social:
  pluginConfigs:
    AccountService.identityProviderPlugins:
      plugins:
        GoogleWorkspace:
          class: "pragma.account.GoogleWorkspaceIdentityProviderPlugin"
          config:
            allowedDomains:
              1: "${allowedDomain1}"
              2: "${allowedDomain2}"
            clientId: "${googleClientId}"
            clientSecret: "${googleClientSecret}"
            redirectUri: "http://localhost:11000/v1/account/google-redirect"
            playerLoginEnabled: false
            operatorLoginEnabled: true
            accountLinkingEnabled: false
            showPortalLoginButton: true
            visibleToOtherPlayers: false
Check out the Google developer documentation for creating access credentials.
Twitch configuration
valuedescription
clientIdTwitch OAuth ID that identifies developer’s Twitch app while making authorization requests
clientSecretencrypted OAuth secret for the Twitch app referenced by the clientId property
redirectUrioptional

backend authorization endpoint that Twitch uses to validate OAuth handshakes
playerLoginEnabledoptional

boolean determining whether to establish a player session with this identity provider
operatorLoginEnabledoptional

boolean determining whether to establish an operator session with this identity provider
accountLinkingEnabledoptional

boolean determining whether you can link accounts with this identity provider
showPortalLoginButtonoptional

boolean determining whether this login method is available on the portal login page
visibleToOtherPlayersoptional

boolean determining whether Twitch account information is visible to other players
social:
  pluginConfigs:
    AccountService.identityProviderPlugins:
      plugins:
        Twitch:
          class: "pragma.account.TwitchIdentityProviderPlugin"
          config:
            clientId: "${twitchClientId}"
            clientSecret: "${twitchClientSecret}"
            redirectUri: "http://localhost:11000/v1/account/twitch-redirect"
            playerLoginEnabled: false
            operatorLoginEnabled: false
            accountLinkingEnabled: true
            showPortalLoginButton: false
            visibleToOtherPlayers: false
Okta configuration
valuedescription
clientIdOkta OAuth ID that identifies developer’s Okta app while making authorization requests
clientSecretencrypted OAuth secret for the Okta app referenced by the clientId property
authorizationUriURI the user will be sent to for authenticatication with Okta
tokenUriURI to obtain an access token by sending an auth code
userInfoUriURI to obtain information about the user
redirectUrioptional

backend authorization endpoint that Okta uses to validate OAuth handshakes
requireEmailVerificationboolean determining whether email is required
playerLoginEnabledoptional

boolean determining whether to establish a player session with this identity provider
operatorLoginEnabledoptional

boolean determining whether to establish an operator session with this identity provider
accountLinkingEnabledoptional

boolean determining whether you can link accounts with this identity provider
showPortalLoginButtonoptional

boolean determining whether this login method is available on the portal login page
visibleToOtherPlayersoptional

boolean determining whether Okta account information is visible to other players
social:
  pluginConfigs:
    AccountService.identityProviderPlugins:
      plugins:
        Okta:
          class: "pragma.account.OktaIdentityProviderPlugin"
          config:
            clientId: "${OktaClientId}"
            clientSecret: "${OktaClientSecret}"
            authorizationUri: "https://your-okta-subdomain.okta.com/oauth2/v1/authorize"
            tokenUri: "https://your-okta-subdomain.okta.com/oauth2/v1/token"
            userInfoUri: "https://your-okta-subdomain.okta.com/oauth2/v1/userinfo"
            redirectUri: "http://localhost:11000/v1/account/Okta-redirect"
            requireEmailVerification: true
            playerLoginEnabled: false
            operatorLoginEnabled: true
            accountLinkingEnabled: false
            showPortalLoginButton: true
            visibleToOtherPlayers: false
Auth0 configuration
valuedescription
clientIdauth0 OAuth ID that identifies developer’s auth0 app while making authorization requests
clientSecretencrypted OAuth secret for the auth0 app referenced by the clientId property
authorizationUriURI the user will be sent to for authenticatication with Auth0
tokenUriURI to obtain an access token by sending an auth code
userInfoUriURI to obtain information about the user
redirectUrioptional

backend authorization endpoint that auth0 uses to validate OAuth handshakes
requireEmailVerificationboolean determining whether email is required
playerLoginEnabledoptional

boolean determining whether to establish a player session with this identity provider
operatorLoginEnabledoptional

boolean determining whether to establish an operator session with this identity provider
accountLinkingEnabledoptional

boolean determining whether you can link accounts with this identity provider
showPortalLoginButtonoptional

boolean determining whether this login method is available on the portal login page
visibleToOtherPlayersoptional

boolean determining whether Auth0 account information is visible to other players
social:
  pluginConfigs:
    AccountService.identityProviderPlugins:
      plugins:
        Twitch:
          class: "pragma.account.Auth0IdentityProviderPlugin"
          config:
            clientId: "auth0-client-id"
            clientSecret: "auth0-client-secret"
            authorizationUri: "https://your-auth0-subdomain.us.auth0.com/authorize"
            tokenUri: "https://your-auth0-subdomain.us.auth0.com/oauth/token"
            userInfoUri: "https://your-auth0-subdomain.us.auth0.com/userinfo"
            redirectUri: "https://localhost:11200/v1/oauth-redirect/auth0"
            requireEmailVerification: true
            playerLoginEnabled: false
            operatorLoginEnabled: true
            accountLinkingEnabled: false
            showPortalLoginButton: true
            visibleToOtherPlayers: false
Playstation configuration
Pragma Engine supports PlayStation Network integration. Contact us for details.
Xbox configuration
Pragma Engine supports Xbox integration. Contact us for details.

Add OAuth redirect URIs #

Any identity provider that uses OAuth requires a list of authorized redirect URIs to allow the Pragma Engine platform to generate an access code and authorization token. As an example, below are the URIs you will need to add to Discord’s developer console OAuth2 Redirects.

To enable authentication for the SDK or external clients, you must add:

  • http://localhost:11000/v1/account/discord-redirect

To enable Operator Portal authentication, you must add:

  • http://localhost:11200/redirect/SignInDiscord
  • http://localhost:10200/redirect/SignInDiscord

To enable Player Portal authentication and account linking, you must add:

  • http://localhost:11000/redirect/SignInDiscord
  • http://localhost:11000/redirect/LinkDiscord

When used on a deployed shard environment, replace these links with your own Pragma Engine hostname.

Error types #

error typedescription
AccountService_IdProviderMissingIdentity provider is not configured in Pragma Engine.
AccountService_InvalidIdProviderIdentity provider enum type does not exist in IdProvider or ExtIdProvider enums.
AccountService_IdProviderLinkingDisabledaccountLinkingEnabled config value is set to false for this identity provider.
AccountService_IdProviderAlreadyAssociatedIdentity provider account is already linked to an existing Pragma Account.

Ex: The same Steam account can not be linked to two separate Pragma Accounts.
AccountService_AccountAlreadyBoundToProviderTypeA Pragma Account can not simultaneously be linked to the same identity provider type more than once.

Ex: Two Steam accounts can not be linked to the same Pragma Account at the same time.
AccountService_CannotUnlinkOnlyIdProviderIdentity provider is the last one linked to Pragma Account. Every Pragma Account needs at least one identity provider associated with it to be reachable.
AccountService_IdProviderAuthenticationDisabledplayerLoginEnabled or operatorLoginEnabled config value is set to false for this identity provider.
AccountService_UnauthorizedUser does not meet authorization requirements for identity provider.

Ex: Only users with a specific email domain can log in.
AccountService_UnverifiedUser’s account has not been verified.

Ex: email verification
AccountService_IdProviderUnexpectedResponsePragma Engine received a response from the identity provider’s API that was unexpected.

Ex: Steam service is down.

Manage identity providers in Operator Portal #

Identity providers can be viewed and managed within the Operator Portal.

  1. From the Social Operator Portal, click Services, then click Accounts.
  2. Click on the relevant player name to view individual account information.
  3. View the player’s identity providers.

Unlinking an identity provider #

Removing an identity provider from an account is a permanent action and cannot be undone.

  1. From the Social Operator Portal, click Services, then click Accounts.
  2. Click on the relevant player name to view individual account information.
  3. View the player’s identity providers.
  4. Hover over the identity provider you’d like to remove and click unlink.
  5. Confirm you want to unlink the identity provider.

Alternatively, the following endpoints can be used to unlink an identity provider:

  • AccountRpc.UnlinkIdentityProviderAccountPartnerV1Request
  • AccountRpc.UnlinkIdentityProviderAccountServiceV1Request
  • AccountRpc.UnlinkIdentityProviderAccountOperatorV1Request

Filtering by identity provider #

Accounts can be filtered in Operator Portal by identity provider. This includes identity providers that are no longer used or disabled. For example, even if login is disabled for Steam, accounts will still appear when you filter by Steam in Operator Portal.

Hide a player’s identity providers information #

You can choose which identity providers are visible to other players using the config value visibleToOtherPlayers.

Below is an example of how to hide the Steam identity provider from other players:

Steam:
  class: "pragma.account.SteamIdentityProviderPlugin"
  config:
    appId: "1627080"
    steamWebAPIKey: "3CD023D13769C48A24FDFCCB3398D68A"
    visibleToOtherPlayers: false

Contents #

TopicDescription
Custom Identity ProvidersCreate a custom identity provider.

Cross-Platform Accounts
Custom Identity Providers