Single Sign On

Single Sign-On

Operators use this page to turn on sign-in with Google for the Player Accounts website and for the control panel.

Single sign-on is optional. With no configuration, the two surfaces use email and password only, and no provider button shows.

Surface	With Google on
Player Accounts website (/v1/players/account/)	A player can sign in, make an account on the first sign-in, and link or unlink Google on the account page.
Control panel (/v1/control-panel)	A user with Google linked can sign in. A person can accept an invite or a sign-up approval with Google. A user can link or unlink Google on the account page.

The two surfaces have separate stores. A Google account that is linked to a player account gives no access to the control panel.

Before you start

Set CONTROL_PANEL_BASE_URL to the public origin of the server, for example https://ggscale.example.com. The server does not start if a provider is on and this variable is empty. In production, the origin must use https://.

1. Make the Google OAuth clients

Make one OAuth client for each surface that you want to turn on.

1. Open the Google Cloud console, then APIs & Services, then Credentials.

2. Select Create credentials, then OAuth client ID.

3. Set the application type to Web application.

4. Add the redirect URL of the surface to Authorized redirect URIs:

   Surface	Redirect URL
   Players	{CONTROL_PANEL_BASE_URL}/v1/players/account/sso/google/callback
   Control panel	{CONTROL_PANEL_BASE_URL}/v1/control-panel/sso/google/callback

5. Record the client ID and the client secret.

The URL must be an exact match. A different scheme, host, or port, or a slash at the end, causes a redirect_uri_mismatch error from Google.

Google has one consent screen for each Cloud project. Two clients in one Cloud project show the same app name to players and to control panel users. To show different names, make the clients in two Cloud projects.

2. Set up the consent screen

GG Scale asks for the scopes openid, email, and profile. These scopes are not sensitive, but Google can ask for verification for other reasons, for example a logo.

1. On the branding page of the consent screen, give the app name, support email, home page, privacy policy, terms of service, and authorized domains.
2. Publish the app. While the app is in testing, only the test users that you add can sign in.

3. Set the variables

Variable	Surface
PLAYER_SSO_GOOGLE_CLIENT_ID	Players
PLAYER_SSO_GOOGLE_CLIENT_SECRET	Players
CONTROL_PANEL_SSO_GOOGLE_CLIENT_ID	Control panel
CONTROL_PANEL_SSO_GOOGLE_CLIENT_SECRET	Control panel

• An empty client ID turns off Google for that surface.
• A client ID with no secret, or a secret with no client ID, stops the server at startup.
• Each secret supports the _FILE form. Set <NAME>_FILE to the path of the file and leave <NAME> empty.

Restart the server after you change the variables.

4. Check the setup

1. Open {CONTROL_PANEL_BASE_URL}/v1/players/account/login. The Google button shows.
2. Sign in with a Google account. The account page opens.
3. Open the control panel login page. The Google button also shows there.

Rules

Rule	Reason
GG Scale rejects a player whose Google email matches an existing account. The player signs in to that account and links Google on the account page.	GG Scale does not merge accounts by email.
The control panel login page does not make users.	A control panel user comes from the first-run setup, an invite, or a sign-up approval.
A person who accepts an invite with Google gets a user with the invite email, not the Google email.	The emailed invite code is the proof of the email.
An existing control panel user can accept an invite with Google only if that Google account is already linked to the user. If not, the user enters the password.	The emailed link alone must not open an existing account.
After Google sign-in, an account with two-factor authentication must enter the code, unless the device is trusted.	The provider is the first factor only.
A person cannot remove the last sign-in method.	The person would lose access to the account.
An account with no password sets one with Forgot password.	The reset link goes to the account email.
A link or unlink asks for the current password. If the account has no password and two-factor authentication is on, it asks for a two-factor code. If the account has neither, no check runs.	A stolen session must not change the sign-in methods.

Audit rows

The rows are in platform_audit_log.

Action	Actor	When
sso.signup	Service player_sso	A player account is made on the first sign-in.
sso.link, sso.unlink	Service player_sso	A player links or unlinks a provider.
sso.link_collision	Service player_sso	A player tries to link a provider account that a different player account has.
control_panel.sso_link, control_panel.sso_unlink	Control panel user	A user links or unlinks a provider, or accepts an invite or a sign-up approval with Google and gets a new user.
control_panel.sso_link_collision	Control panel user	A user tries to link a provider account that a different user has.
control_panel.login with {"method": "google"}	Control panel user	A user signs in with Google and has no two-factor challenge.

For the player rows, target is the ID of the player account. A collision row also has the ID of the account that has the provider account. A control panel collision row has the other user in linked_user_id. No page resolves a collision. Find the two accounts from the row, then resolve the collision by hand.

Problems

Symptom	Cause
The button does not show.	The client ID for that surface is empty, or you did not restart the server.
Google refuses an account that is not a test user.	The app is still in testing. Publish it.
Google shows redirect_uri_mismatch.	The redirect URL on the Google client is not an exact match. Check CONTROL_PANEL_BASE_URL.
"That sign-in attempt expired or is not valid."	The person took more than 10 minutes, used the browser back button, or the browser blocks cookies.
The browser does nothing when the person selects the button, and the console shows a form-action error.	A proxy changes the Content-Security-Policy header. The server adds the Google origin to form-action.
"Could not reach Google." or "Could not reach the sign-in provider."	The token exchange or the profile request failed. Check the client secret, and check that the outbound firewall rules allow oauth2.googleapis.com and openidconnect.googleapis.com.