Sign in with Google or Microsoft

In plain words

Instead of typing a password, people click Continue with Google or Continue with Microsoft. If they are already signed in to that account in their browser, it takes one click. You still decide who gets in: only people you have added can sign in. This page is for the person who sets up the results server and is comfortable with a terminal.

You need the sign-in server running over HTTPS, and an account with Google, Microsoft, or both.

How it works

1. A person opens your results address and clicks Continue with Google (or Microsoft).
2. Google or Microsoft confirms who they are and sends them back to your server.
3. Your server looks for an account with that email. If there is one, they are in. If not, they see a message and nothing is shown.

Having a Google or Microsoft account is never enough on its own. You add each person first. This is on purpose, so strangers cannot walk in.

1. Add the people who may sign in

People who will only use Google or Microsoft do not need a password:

node bin/manage.js user add sam@example.com --projects shop=viewer --no-password

Anyone who already has an account with a password can use Google or Microsoft too. The first time they sign in, StepTrails links their account to their Google or Microsoft identity, using their verified email. After that it recognises them by a number that never changes, even if their email changes.

2. Register StepTrails with Google

You do this once, in Google's own tools. The screens may look a little different from these notes.

1. Open the Google Cloud console, create a project (or pick one), then go to APIs & Services, OAuth consent screen. Choose Internal if everyone is in your Google Workspace, or External otherwise. Fill in the app name and your email.
2. Go to Credentials, Create credentials, OAuth client ID. Choose Web application.
3. Under Authorized redirect URIs, add exactly: https://results.example.com/auth/google/callback (use your own address).
4. Click Create. Copy the client ID and the client secret.

If everyone should be in one Workspace, also note your domain, for example example.com.

3. Register StepTrails with Microsoft

1. Open the Microsoft Entra admin center, go to App registrations, New registration.
2. Name it. Under Supported account types choose Accounts in this organizational directory only.
3. Under Redirect URI choose Web and enter: https://results.example.com/auth/microsoft/callback
4. Click Register. Copy the Application (client) ID and the Directory (tenant) ID from the overview page.
5. Go to Certificates & secrets, New client secret. Copy the secret value now. It is shown once.

4. Give StepTrails the settings

Set these where the server runs. Do not put them in a file in your project, and never commit them.

Setting	What to put
STEPTRAILS_SSO_GOOGLE_CLIENT_ID	The Google client ID
STEPTRAILS_SSO_GOOGLE_CLIENT_SECRET	The Google client secret
STEPTRAILS_SSO_GOOGLE_DOMAIN	Optional. Only people in this Workspace domain, such as example.com
STEPTRAILS_SSO_MICROSOFT_CLIENT_ID	The Microsoft application (client) ID
STEPTRAILS_SSO_MICROSOFT_CLIENT_SECRET	The Microsoft client secret value
STEPTRAILS_SSO_MICROSOFT_TENANT	The Microsoft directory (tenant) ID, a code made of letters, digits and dashes

Use one provider or both. If only some of a provider's settings are given, StepTrails stops with a message that says which ones are missing.

5. Start the server

node bin/manage.js serve --host 0.0.0.0 --behind-https-proxy --public-url https://results.example.com

--public-url is the address people use. It must be the same address you registered above, and it must start with https:// (except http://localhost for trying it on your own computer).

The sign-in page now shows a Continue with Google button, and a Continue with Microsoft button if you set that up. The email and password form stays below them.

Only Google or Microsoft

To switch password sign-in off completely, add --require-sso. Keep one way to switch it back on: run the server again without that flag if a provider is ever unavailable.

What keeps it safe

• Only invited people get in. An unknown email, a disabled account, or an email the provider has not verified is refused.
• Microsoft: one directory only. StepTrails refuses words like "common" in the tenant setting, because they would let anyone with a Microsoft account reach the sign-in. A person is recognised by their directory and their object number, not by an email anyone could set.
• Google: verified emails only, and optionally one Workspace domain.
• Every sign-in is checked three times: the provider's secure connection, the token's checks (who, for whom, when, and the one-time number), and the token's signature against the provider's published keys.
• A sign-in that someone else started cannot be finished in your browser, and a sign-in link works once.
• Your client secret is only read from settings. It is never put in a web address, a page or the log.
• Signing out ends your session on this server. It does not sign you out of Google or Microsoft.

If something goes wrong

What you see	What to do
"That account does not have access"	The email is not on the list. Add it with user add, or check which Google or Microsoft account the person used.
"Sign-in did not work"	Check the log with user audit. The most common cause is a redirect address that does not exactly match the one you registered.
The server will not start and mentions --public-url	Give the web address people use, starting with https://.