System Administration

Social Login

Social Login lets admin users sign in to ShipStream using Google or Microsoft Entra ID (formerly Azure AD) instead of (or in addition to) a username and password. Combined with the Required Domains list, this makes your identity provider the source of truth for ShipStream access — disabling a user in Google Workspace or Entra ID also blocks their ShipStream login, removing a step from your offboarding process.

Each provider is configured independently, so you can roll out Google without enabling Microsoft (or vice versa). Username/password and Login via Badge sign-in remain available alongside Social Login unless you restrict passwords with Password Login or Force SSO for Domains.

Social Login is for Organization Users only. Client Users sign in to the Client UI with a password and cannot sign in with Google or Microsoft.

Social Login is not a complete Single Sign-On solution with two-way user synchronization. However, when you combine Required Domains, Allow External Users, and Force SSO for Domains or Password Login, it can effectively operate as Single Sign-On by requiring users to authenticate through your identity provider. Users blocked from your Google Workspace or Microsoft Entra organization will also be blocked from signing in to ShipStream.

Social Login button with Google enabled Social Login button with Microsoft enabled

Configuring Providers

All Social Login settings live at System -> Configuration -> Advanced -> Social Login.

Social Login configuration settings

Google

In Google Cloud Console, open APIs & Services -> OAuth consent screen and confirm the app is configured for your organization.
Open APIs & Services -> Credentials and click Create Credentials -> OAuth client ID.
Choose Web application as the application type.
Add your ShipStream admin origin as an Authorized JavaScript origin. For example, if you sign in at https://example.shipstream.app/admin, enter https://example.shipstream.app.
Add your Google callback URL as an Authorized redirect URI: https://your-shipstream-host/admin/social/googleCallback/.
Copy the generated Client ID.

Google OAuth Client ID page

In ShipStream, set Enable Google Login to Yes.
Paste the Google Client ID into the Google Client ID field.
Click Save Config.

A Sign in with Google button will appear on the admin login page on the next page load.

Microsoft Entra ID

In Microsoft Entra admin center, open Identity -> Applications -> App registrations and click New registration.
Enter a name such as ShipStream Admin Login.
Choose who can use the application. For most organizations, choose Accounts in this organizational directory only. Choose a broader option only if you want to allow multiple Entra tenants or personal Microsoft accounts.
Set the redirect URI platform to Single-page application (SPA) and add your Microsoft callback URL: https://your-shipstream-host/admin/social/microsoftCallback/. If you plan to use End Social Login Session on Sign Out (see Shared devices), also add the admin login URL: https://your-shipstream-host/admin/index/login/. ShipStream uses the login URL after sign-out so Microsoft can return the browser to the login page. If it is missing, Microsoft still ends the session and shows its own signed-out page.

Microsoft Entra app registration page with Single-page application selected

The Microsoft redirect URI must be configured as a Single-page application (SPA), not as a Web application. If the platform is set to Web, Microsoft sign-in will not complete correctly from the ShipStream login page.

After creating the app registration, copy the Application (client) ID.

Microsoft Entra application client and tenant IDs

If prompted under Authentication, make sure ID tokens are enabled for the application.
If you plan to use End Social Login Session on Sign Out, open Token configuration, click Add optional claim, choose the ID token type and select login_hint. Without this claim, Microsoft asks which account to sign out of instead of ending the session immediately.
In ShipStream, set Enable Microsoft Login to Yes.
Paste the Application (client) ID into the Microsoft Client ID field.
Fill in Microsoft Allowed Tenants with one or more Entra tenant IDs (GUIDs), separated by commas. ID tokens are accepted only when the token's tenant claim matches this allow-list.
Set Allow Personal Microsoft Accounts to Yes if you also want to permit sign-in with personal Microsoft accounts (MSAs). Leave it No if only your organization's Entra accounts should be allowed.
Click Save Config.

A Sign in with Microsoft button will appear on the admin login page on the next page load.

Select Sign in with Microsoft to open Microsoft's sign-in page in the same tab. After you sign in, you return to ShipStream automatically. If sign-in cannot be completed on the return page, select Back to Login to try again.

At least one tenant must be in Microsoft Allowed Tenants, or Allow Personal Microsoft Accounts must be Yes, for Microsoft Login to take effect. Personal accounts are always rejected when Allow Personal Microsoft Accounts is No, even when the user manages to sign in at Microsoft.

Shared devices

Google and Microsoft keep their own sessions in the browser, separate from ShipStream. On a shared device, that leftover session can sign the next person in as the previous user. Both sign-in buttons therefore always ask which account to use instead of signing in silently.

For Microsoft, ShipStream can go further and end the Microsoft session itself. Edit the User Role used on the shared device and set End Social Login Session on Sign Out to Yes. When a user signs in with Microsoft and then selects Sign Out in ShipStream, ShipStream also ends the Microsoft session in that browser. This happens when any role assigned to the user has the option set, and only on an explicit sign-out — not when a session expires or when another user signs in with a badge on the same device.

Microsoft also keeps a list of every account that has signed in on a browser and offers it as a picker on the next sign-in. ShipStream cannot remove accounts from that list, so it avoids it instead: once a user with any role that has End Social Login Session on Sign Out signs in on a browser, ShipStream marks that browser as a shared device and later Microsoft sign-ins there go straight to the credentials form. The mark survives sign-out and is removed the next time a user without the option signs in on that browser, so a personal computer reverts to the account picker on its own.

Microsoft's Stay signed in? prompt is controlled by Entra, not by ShipStream. To remove it on shared devices, create a Conditional Access policy in Entra that targets the ShipStream app registration (and, if you like, only the shared-device users or location) with Session -> Persistent browser session -> Never persistent. Setting Show option to remain signed in to No under Company branding removes the prompt for the whole tenant instead.

Google offers no way for ShipStream to end its session, so this option has no effect on Google sign-in.

Ending the Microsoft session on sign-out also signs that browser out of other Microsoft apps (Outlook, Teams, and so on) until someone signs in again. Leave the option No on every role held by users who sign in from a personal computer.

Required Domains

The Required Domains field is a comma-separated list of email domains that ShipStream considers "internal" — for example, acme.com,acme.co.uk. Required Domains drive three related controls. Leave the field empty to allow Social Login from any domain (in which case a matching ShipStream User must already exist).

Allow External Users

When Required Domains is set, the Allow External Users option controls whether users whose email does NOT match any required domain can log in via Social Login.

Yes — users from outside the required domains may sign in, but only if an admin has already created a matching ShipStream User account for them.
No — only users whose email matches a required domain can sign in via Social Login.

Force SSO for Domains

When Force SSO for Domains is Yes, users whose email matches one of the Required Domains cannot sign in with a password — they sign in with Google, Microsoft or a badge. Super-admins are exempt so that a misconfigured identity provider can still be recovered, and Client Users are exempt because they cannot use Social Login.

A blocked user who enters a password sees the usual invalid-login error, whether or not the password is correct, so the login page reveals neither which accounts are internal nor whether a password is right. Tell your team to use the Google or Microsoft button before you turn this on. The rule applies together with Password Login: a user blocked by either one cannot sign in with a password.

An internal-domain user does not need a linked identity before you enable Force SSO for Domains — their first Google or Microsoft sign-in links one automatically. That only works when the email on their ShipStream User matches the email they use at the provider, so check those emails first. A user whose emails differ cannot sign in with either method until you correct the email on their ShipStream User.

Auto Create Accounts

When Auto Create Accounts is Yes, ShipStream automatically creates an admin User the first time a user with an internal-domain email signs in via Social Login. The new account is assigned to the Primary User Group and to the role you choose in Auto Created Accounts Role.

The username is derived from the email's local part (with a numeric suffix if the username is taken).
The full name is taken from the identity provider when available.
Auto-creation only fires for emails matching the Required Domains. External users still need an admin-created account.

Auto Created Accounts Role is required when auto-create is enabled. Pick a role with the minimum permissions appropriate for new internal users; existing administrators can adjust roles afterward on the User edit page.

Auto-created accounts have no password. They sign in with Google, Microsoft or a badge unless someone later sets a password for them.

The Password Login setting decides whether Organization Users may still sign in with a username and password once Social Login is in place. Unlike Force SSO for Domains, it does not depend on the Required Domains list.

Enabled — the default. Users can sign in with a password, subject to Force SSO for Domains.
Disabled for Linked Accounts — a user with a linked Google or Microsoft identity must sign in with it. A user with no linked identity keeps using their password until their first Google or Microsoft sign-in links one, which makes this option a good way to move a team over gradually.
Disabled — no user can sign in with a password. Users sign in with Google or Microsoft (whichever is enabled) or, when it is enabled, a badge.

Super-admins and Client Users can always sign in with a password, whichever option you choose, so a super-admin can still get in if your identity provider fails. Badge login is never affected.

For a user who is not allowed to sign in with a password:

Entering a password on the login page shows the usual invalid-login error, even when the password is correct, so the page never confirms that a password is right.
Forgot your password? sends no email, and the page shows the same confirmation it shows for any other address. A reset link sent before the restriction no longer works.
The password fields and the Send Reset Link button are hidden on the User edit page and on My Account.

Saving the setting

Test Social Login before you restrict passwords. Open a private browser window, sign in with Google or Microsoft as an ordinary user, and confirm you reach ShipStream. ShipStream checks that a provider is configured, not that it works: a mistyped client ID or tenant passes the check and still blocks every social sign-in. After a save that restricts passwords, ShipStream reminds you to run this test before you sign out; if it fails, set Password Login back to Enabled.

Either Disabled option can only be saved while Google Login or Microsoft Login is enabled and fully configured: a Google Client ID, or a Microsoft Client ID plus at least one Microsoft Allowed Tenant or Allow Personal Microsoft Accounts set to Yes. The same check runs whenever you save the Social Login settings, so to turn off your last provider, set Password Login back to Enabled first.

To switch to Disabled, you must be a super-admin or be signed in with Google or Microsoft at the time, through an identity whose email the Required Domains and Allow External Users values you are saving still accept. For Microsoft, the tenant you signed in from must also stay allowed. This proves the new sign-in path works for you before passwords stop working, so you cannot lock yourself out. While Disabled is in force, every later save of the Social Login settings runs the same check, so a change to a provider, tenant or domain that would stop your own social sign-in is refused.

When a provider is turned off

Under Disabled for Linked Accounts, only identities for providers that are currently enabled count. If you turn off Google while Microsoft stays on, users who linked only Google can sign in with their password again, rather than being locked out of both.

Removing a tenant from Microsoft Allowed Tenants, or setting Allow Personal Microsoft Accounts to No, does not re-enable password login for users linked through it, because ShipStream does not record which tenant an identity belongs to. To restore password login for such a user, unlink their Microsoft identity on their User edit page.

If a user's provider email changes to one that Required Domains and Allow External Users refuse, their social sign-in is refused, and ShipStream records the new email on the identity. Under Disabled for Linked Accounts that identity then no longer counts, so the user can sign in with their password.

Disabled stays in force even if no provider is available. Super-admins can still sign in with a password to repair the configuration.

When Password Login is Disabled, the login page shows only the buttons for the enabled providers, and the username and password form (including Forgot your password?) is not shown. Badge scanning works as before. ShipStream super-admins can still sign in with a password; their sign-in page states that password login is disabled and only super-admins can use it. Under the other two options the login page does not change, because ShipStream does not know who is signing in until they submit the form.

Start with Disabled for Linked Accounts. Once the Social Identities on your User pages show that everyone has signed in with Google or Microsoft, switch to Disabled.

Each linked Google or Microsoft account is recorded as a Social Identity on the corresponding ShipStream User. Users see their own linked identities at the bottom of System -> My Account, and administrators see any user's identities at the bottom of the User Information tab on the User edit page.

Each identity row shows the Provider, the Provider Email (the email returned by the identity provider, which may differ from the ShipStream account email), and the date the identity was first linked. Click Unlink on a row to remove that identity.

A new social identity is linked automatically the first time a user signs in via Social Login, provided the provider's email matches the email of an existing Organization User (or auto-create is enabled). After the first sign-in, ShipStream identifies the user by the provider's stable identifier rather than the email, so changing the email at the provider does not break the link. For the same reason, unlinking an identity does not stop the user from signing in with that provider: their next sign-in links it again if the emails still match. To block a user, disable them at the provider or deactivate their ShipStream User.

On My Account, the Unlink button is hidden where unlinking would lock the user out or lift a password restriction: a non-super-admin's last identity for a currently enabled provider when Password Login is Disabled for Linked Accounts or Disabled, or when Force SSO for Domains is enabled and their email matches a Required Domain. The same rule applies to an administrator's own identities on their User page. Administrators editing another user from System -> Users can still unlink any identity; the confirmation then explains how the change affects the user's sign-in.

Time Tracking for Administrators