ShipStream Knowledge Base
Developer Center Learn More
System

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). Existing username/password and Login via Badge flows remain available alongside Social Login.

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, it can effectively operate as Single Sign-On by requiring internal 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.

Configuring Providers

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

Google

  1. In Google Cloud Console, open APIs & Services -> OAuth consent screen and confirm the app is configured for your organization.
  2. Open APIs & Services -> Credentials and click Create Credentials -> OAuth client ID.
  3. Choose Web application as the application type.
  4. 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.
  5. Add your Google callback URL as an Authorized redirect URI: https://your-shipstream-host/admin/social/googleCallback/.
  6. Copy the generated Client ID.

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

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

Microsoft Entra ID

  1. In Microsoft Entra admin center, open Identity -> Applications -> App registrations and click New registration.
  2. Enter a name such as ShipStream Admin Login.
  3. 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.
  4. Set the redirect URI platform to Single-page application (SPA) and add your Microsoft callback URL: https://your-shipstream-host/admin/social/microsoftCallback/.

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.
  1. After creating the app registration, copy the Application (client) ID.

  1. If prompted under Authentication, make sure ID tokens are enabled for the application.
  2. In ShipStream, set Enable Microsoft Login to Yes.
  3. Paste the Application (client) ID into the Microsoft Client ID field.
  4. 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.
  5. 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.
  6. Click Save Config.

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

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.

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 can ONLY sign in via Social Login — password login is disabled for those accounts. Super-admins are exempt so that a misconfigured identity provider can still be recovered.

Before enabling Force SSO for Domains, confirm that every internal-domain user has at least one linked social identity (or is a super-admin). A user who matches a required domain but has no linked identity will be locked out until an admin links one.

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.

Social Identities on User Pages

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.

When Force SSO for Domains is enabled, an internal-domain user cannot unlink their last remaining social identity from My Account — doing so would lock the user out of their own account. Administrators editing the user from System -> Users can still unlink any identity.

A new social identity is linked automatically the first time a user signs in via Social Login, provided the provider's email matches an existing ShipStream 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.

Login via Badge

Protected Customer Data