OpenID Connect sign-in

Logship supports OpenID Connect (OIDC) authorization code sign-in with PKCE. The identity provider authenticates the person; Logship controls which accounts and permissions that person has. Configure providers in Administration → System → Identity providers as a global administrator.

Set up the provider

1. In Sign-in URLs and callback, enter the public backend URL and frontend URL that users can reach in their browser. Save them. Use HTTPS outside local development.
2. Copy the displayed callback URL, normally https://api.example.com/auth/identity/callback. Register that exact URL as a web application redirect URI with your OIDC provider. The URL must use the public backend host, not the frontend host.
3. In the provider's console, enable the authorization code flow and create a client ID and client secret. Grant the openid, profile, and email scopes. Ensure the provider returns an ID token with a stable sub claim. For automatic matching to an existing Logship user, it must also return the user's email and email_verified=true.
4. Select Add provider. Choose a Google, Microsoft, or Keycloak preset, or use Custom OpenID Connect. Enter the provider's issuer URL, client ID, and secret. The issuer must expose OIDC discovery metadata at /.well-known/openid-configuration and match the ID token issuer.
5. Leave Enable sign-in and Automatically create users accepted by this provider checked if new people should be able to sign in. To restrict who can sign in, configure the provider's own access policy and the Logship provider restrictions. For the Microsoft common issuer, explicitly allow enterprise tenant IDs or personal accounts.
6. Optionally choose a Default account by name and select Initial account permissions. These permissions apply only when Logship creates a new user through this provider. Existing users keep their account memberships and permissions.
7. Save the provider. Saving an enabled provider checks its configuration and OIDC discovery. Then use Test sign-in to complete the provider redirect and callback without creating or linking a Logship user. The provider appears on the login page when enabled.

To correct an existing provider, select Edit, change Issuer URL, and select Save changes. Saving an enabled provider validates discovery before applying the change. Leave the client secret blank to retain the stored secret. Start a fresh sign-in after saving; pending sign-ins use the previous provider version and must restart.

Provider ID and client ID cannot be edited after creation. Add a new provider for a different client registration. Logship stores client secrets encrypted and does not display them again. Changing the configured issuer does not rewrite existing identity links: links use the issuer and subject from the validated ID token. Switching Microsoft authorities can preserve those links when the returned identity is unchanged; switching to a different identity service may require users to link that identity explicitly.

Microsoft account setup

In Microsoft Entra admin center → App registrations, create or select the application. Its Supported account types must match the authority configured in Logship. Add the callback displayed by Logship under Authentication → Web → Redirect URIs, and enter the application's client ID and client secret in the Logship Microsoft provider.

Microsoft app's supported account types	Logship Issuer URL	Logship restrictions
Personal Microsoft accounts only	https://login.microsoftonline.com/consumers/v2.0	Enable Allow personal Microsoft accounts.
Accounts in any organizational directory and personal Microsoft accounts	https://login.microsoftonline.com/common/v2.0	Enable personal accounts as needed and list each allowed enterprise tenant GUID.
Accounts in any organizational directory (work/school accounts)	https://login.microsoftonline.com/organizations/v2.0	List allowed enterprise tenant GUIDs; leave personal accounts disabled.
Accounts in this organizational directory only	https://login.microsoftonline.com/<tenant-guid>/v2.0	Replace <tenant-guid> with the directory's tenant ID. The issuer restricts sign-in to that tenant.

The Microsoft preset starts with /common/v2.0 and personal accounts enabled. For a personal-account-only app, change Issuer URL to /consumers/v2.0 before saving. The personal-account checkbox controls which validated Microsoft identities Logship accepts; it does not change the Microsoft app registration or select a different authorization endpoint.

If Microsoft reports invalid_request with userAudience, Consumer, and /common/, the app is configured for personal accounts only but the request uses the common authority. Edit the existing provider's issuer to https://login.microsoftonline.com/consumers/v2.0, save, and start sign-in again. Alternatively, configure the Microsoft app to support both personal and work/school accounts and retain /common/v2.0.

See Microsoft's OIDC endpoint and authority reference and supported account types. Provider discovery validation checks the issuer and endpoints; Test sign-in also exercises Microsoft app-registration and account-type restrictions.

Give people account access

An account administrator can use Account → Settings → Users → Add Users and enter the person's email address, then select the account permissions. This works whether the person signs in with a Logship password or OIDC. If an existing user has that email, Logship adds that user to the account. Otherwise it creates a pending user and sends an account invitation. An OIDC user's internal ID or provider subject is never needed in this flow.

On first OIDC sign-in, Logship uses the provider issuer and sub claim to find a linked user. If none exists, a verified provider email can attach the sign-in to one existing Logship user with the same email. If no user matches and automatic creation is enabled, Logship creates a user. If more than one user has the email, an administrator must resolve the duplicates before sign-in can attach it safely. Unverified email cannot automatically claim an existing user.

Users can link another provider in User → Security Settings after signing in to their Logship account. A global administrator can also choose a user by name or email in System → Identity providers → Link a Logship user to a provider and generate a single-use invitation link. That link expires after 30 minutes. This is useful when a provider does not supply a verified email or an existing account needs an explicit link.

Require SSO

The Require SSO for all users except recovery administrators policy disables Logship password sign-in for everyone except the designated recovery administrators. Before enabling it, configure and test an enabled provider. Each recovery administrator must be enabled, have global administrator permission, and have a local password. Sign in again before changing this policy.

Troubleshooting

On a provider rejection, Logship's sign-in page displays the provider name, error code, and available explanation as plain text. Microsoft audience errors include the issuer correction above. Return to login and start again after fixing the configuration; callbacks and completion codes are single use. An HTTP 302 from the backend callback is expected: it returns the browser to the frontend sign-in result page on success or failure. Inspect that page's error message to identify the failure.

Symptom	Check
Redirect or callback fails	The public URLs and the provider's registered redirect URI must exactly match the callback shown in Logship. Check HTTPS and reverse proxy routing.
Discovery or provider save fails	Check the issuer URL, its discovery document, and whether Logship can reach it.
Microsoft rejects userAudience / Consumer / /common/	Use /consumers/v2.0 for a personal-account-only Microsoft app, or change the Microsoft app's supported account types to match /common/v2.0. Save and restart sign-in.
Provider returns access_denied	The user declined consent or the provider's access policy rejected sign-in. Read the provider explanation, if supplied.
Provider changed; try again	The provider was edited during sign-in. Start a new sign-in using the saved configuration.
Provider sign-in succeeds but account access is missing	Add the person's email to the account and assign permissions. A provider default account applies only to newly created users.
A second user is created	Check whether the provider returns the same email as the existing user and email_verified=true. Resolve pre-existing duplicate email users before linking.
Existing user cannot be linked by email	Sign in to that user and link the provider under Security Settings, or create a provider invitation. Check that the email is verified and that the user is not already linked to a different identity.
Login says the identity is not provisioned	Enable automatic user creation, link the provider to an existing user, or use a provider invitation.