Single Sign-On
On this page
With single sign-on, people sign in through an OpenID Connect provider, and Alloy Navigator matches the user the provider asserts to an account.
Setting it up takes two things in Alloy Navigator: a provider record, and an entry that enables that provider on each application people sign in to. Creating a provider record does not enable it anywhere. A provider that no application enables has no effect.
You create provider records in the Settings App or in the Admin Center; both write the same record. You enable providers for the Web App, the API, and the Self Service Portal in the Admin Center. For how the two administration applications relate, see Admin Center and Settings App. For the other sign-in methods, see Authentication Methods.
Before you begin
- To work with SSO providers in the Admin Center, you need basic administrative access, Active Directory integration, or security management rights. The Admin Center returns the list of SSO providers only to these administrators. See Permissions Reference.
- Single sign-on to the Web App needs HTTPS. When the Sign in page is not opened over HTTPS, its provider buttons are disabled.
Supported providers
Single sign-on supports OpenID Connect only; SAML is not supported. Every provider record has one of four types:
| Type | Extra setting | Authority |
|---|---|---|
| Microsoft (Microsoft Entra ID) | The tenant type, multi-tenant or single-tenant, plus the tenant ID for a single tenant | https://login.microsoftonline.com/<tenant ID or common>/v2.0 |
| ADFS | The ADFS domain | https://<domain>/adfs |
| Okta | The Okta domain | https://<domain> |
| Custom | None | The authority URL you type |
A Custom provider is an OpenID Connect provider whose authority URL you type instead of having it composed from the domain or tenant. It is not a way to use another protocol.
Google has no provider type of its own. A Custom provider can have Google's
OpenID Connect endpoint, https://accounts.google.com, as its authority. Other
Google settings in Alloy Navigator belong to e-mail: the outgoing mail system
and the Mail Connector can connect to Google with Google OAuth. They have
nothing to do with signing in.
The Microsoft tenant ID and client ID that the Web App uses for calendar synchronization are also separate from single sign-on. Configuring them does nothing for sign-in, and a provider record does nothing for calendar synchronization.
In a new 2026.1 database created with the Default Workflow (see Default Workflow Configuration), the Microsoft Azure AD Integration scheduled task imports users from Microsoft Entra ID. Its tenant ID, client ID, and secret are settings of its own and do not set up single sign-on; see Microsoft Entra ID Import.
The provider record
A provider record holds:
- A display name.
- The provider type and its extra setting, as listed in Supported providers.
- The authority URL.
- The client ID and the client secret of the application you registered at the provider.
- The two claims to read from the provider's token: the username claim and the full-name claim.
For every type except Custom, the authority is composed from the domain or tenant and is recomputed whenever you change the domain or tenant. The authority can be typed only for a Custom provider.
Each type starts with its own default claims:
| Type | Default username claim | Default full-name claim |
|---|---|---|
| Microsoft | preferred_username |
name |
| ADFS | upn |
name |
| Okta | preferred_username |
name |
| Custom | emailaddress |
name |
The client secret is stored encrypted. Lists of providers are ordered by type, with Custom last. The provider check boxes on the Authentication tabs of the Web App and the API are the exception: they are sorted by name.
Set up single sign-on
- On the provider's own site, register the application people will sign in
to. The redirect address is that application's base URL followed by
signin-oidc. For the mobile apps, the redirect address ishttp://localhost:4000. For the steps at each provider, see Prepare the identity provider. - Create the provider record, in the Settings App or in the Admin Center.
- In the Admin Center, enable the provider on each application where people sign in with it: the Web App, the API, and the Self Service Portal.
- Optionally, for the Self Service Portal only, mark the provider for accountless sign-in in the portal's application settings.
An account signs in with a provider only when its login is the value the provider sends; see How a sign-in is matched to an account.
Prepare the identity provider
Before you create the provider record, register Alloy Navigator at the identity provider. Every provider needs the same things from the registration:
- Sign-in method. OpenID Connect.
- Redirect addresses for the web applications. For every Web App and Self
Service Portal instance where people sign in with the provider, that
instance's base URL followed by
signin-oidc. The address uses HTTPS. Add one redirect address per instance. - Redirect address for the mobile apps.
http://localhost:4000. - Scopes. The Web App asks for
openid,profile, andemail. The Alloy Inventory Scanner app also asks foroffline_accesswhen the provider offers it. - Values for the provider record. The client ID and the client secret of the registered application, plus the tenant ID, the domain, or the authority URL, depending on the provider type.
Note each value when the provider shows it. Some providers show a client secret only once.
Microsoft Entra ID
One app registration serves the Web App, the Self Service Portal, and the mobile apps. For the vendor's own steps, see Microsoft's Register an application, Add a redirect URI, and Add and manage app credentials.
- In the Microsoft Entra admin center, go to Entra ID > App registrations and select New registration.
- Enter a name. Under Supported account types, choose Single tenant only when the people who sign in belong to your tenant, or Multiple Entra ID tenants when they belong to more than one tenant. In the provider record, choose the matching tenant type: single-tenant or multi-tenant.
- Select Register. On the Overview page, copy the Application (client) ID. It is the provider record's client ID.
- Under Manage, select Authentication, then Add Redirect URI. Select the Web platform and enter the redirect address of a Web App or Self Service Portal instance. Add the redirect address of every other instance to the same platform.
- For the mobile apps, add the Mobile and desktop applications platform
to the same registration, with the custom redirect URI
http://localhost:4000. - Select Certificates & secrets > Client secrets > New client secret, choose an expiration, and select Add. Copy the secret's Value. It is the provider record's client secret, and it is not shown again after you leave the page.
- For a single-tenant provider, find the tenant ID: go to Entra ID > Overview > Properties and copy the Tenant ID. See How to find your tenant ID.
A client secret expires at the end of the period you chose. Before it expires, create a new one and enter it in the provider record.
Okta
The web applications and the mobile apps need two separate app integrations. For the vendor's own steps, see Okta's Create OIDC app integrations.
- In the Okta Admin Console, go to Applications > Applications, click Create App Integration, and select Classic experience.
- Select OIDC - OpenID Connect as the sign-in method and Web Application as the application type.
- Under the grant types, select Authorization code.
- In Sign-in redirect URIs, enter the redirect address of every Web App and Self Service Portal instance.
- Under Assignments, choose who may sign in: everyone in your Okta organization, or, under Controlled access, Limit access to selected groups.
- Save the integration. Copy its Client ID and its client secret. They are the provider record's client ID and client secret.
- For the mobile apps, create a second app integration: select
OIDC - OpenID Connect and Native Application, select the
Authorization Code and Refresh Token grant types, and enter
http://localhost:4000in Sign-in redirect URIs.
In the provider record, the Okta domain is the host name of your Okta
organization, for example companyname.okta.com.
AD FS
In AD FS, Alloy Navigator is an application group. For the vendor's own steps, see Microsoft's AD FS web app calling web APIs.
- In AD FS Management, right-click Application Groups and select Add Application Group.
- Enter a name and, under Client-Server applications, select the Server application accessing a Web API template.
- Copy the Client Identifier. It is the provider record's client ID. In Redirect URI, enter the redirect address of every Web App and Self Service Portal instance, clicking Add after each.
- On the Configure Application Credentials page, select Generate a shared secret and copy the secret. It is the provider record's client secret.
- On the Configure Web API page, enter an identifier for the web API and click Add.
- On the Apply Access Control Policy page, choose a policy that admits the people who sign in.
- On the Configure Application Permissions page, make sure openid is
selected. The Web App also asks for the
profileandemailscopes. - Finish the wizard.
- For the mobile apps, add a Native application with the redirect URI
http://localhost:4000.
In the provider record, the ADFS domain is the host name of your AD FS
service, for example adfs.companyname.com.
A Google sign-in uses a Custom provider whose authority is
https://accounts.google.com. For the vendor's own steps, see Google's
Configure the OAuth consent screen
and OpenID Connect.
- In the Google Cloud console, create or select the project for Alloy Navigator sign-in.
- Go to Google Auth platform > Branding. If the platform is not configured yet, click Get Started. Enter the App name and the User support email.
- Under Audience, choose the user type: Internal for users in your organization only, or External. An External app must be published before users other than its test users can sign in.
- Under Contact Information, enter an e-mail address, and finish the setup.
- On the Data Access page, add the
openid,.../auth/userinfo.email, and.../auth/userinfo.profilescopes. - On the Clients page, select Create client and choose Web application as the application type.
- Under Authorized redirect URIs, add the redirect address of every Web
App and Self Service Portal instance and, for the mobile apps,
http://localhost:4000. Google requires an exact match, including the scheme and any trailing slash. - Create the client. Copy its client ID and client secret. They are the Custom provider record's client ID and client secret.
In the Settings App
Create a provider
- Go to Users & Security > SSO Providers.
- Open the New drop-down and choose the provider type: Microsoft, ADFS, Okta, or Custom. The provider editor opens on a new record of that type. The editor carries a standing warning that configuration is needed both on the provider's site and in Alloy Navigator.
- Enter the settings described in The provider record.
- Click OK. The record is saved, and the list is refreshed.
After a separator, the New drop-down also lists Domain. The SSO Providers list shows providers and directory domains together.
Convert a standard account to single sign-on
An account signs in with single sign-on when its login is the value the provider sends. Converting a password account to single sign-on is therefore an edit of the account. For accounts in general, see Accounts.
- In the account editor, choose Standard or Single Sign-On. The other authentication choice is Windows.
- Enter the login the provider sends. The field's hint reads "Username for password authentication or email address for SSO".
- Decide whether the account keeps a password. Select Allow password authentication to keep one. Clear it to remove the stored password when you save the account.
- Save the account.
If the login is not an e-mail address and Allow password authentication is cleared, the editor warns that the login cannot be used for Single Sign-On authentication and asks whether to allow password authentication and set a password now. You must answer before the account is saved:
- Yes selects Allow password authentication and returns you to the password field.
- No saves the account without a password.
- Cancel keeps you in the editor.
Turning an account without a password into a password account is a deliberate step. On an account that has no password and whose login is an e-mail address, Set Password first asks whether you want the user to also be able to sign in with a password.
In the Admin Center
Create and manage providers
The Admin Center's SSO Providers screen creates and edits the same provider records as the Settings App. For the settings of a record, see The provider record.
- New offers Microsoft, ADFS, Okta, and Custom, then, after a divider, Domain. Domain adds a directory domain; see Active Directory Synchronization.
- The list shows providers and domains in two groups, providers first. A group appears only when it has rows, and both groups start expanded.
- The toolbar has no Edit command. To edit a provider, click its name or double-click its row.
- To delete, select one or more rows and click Delete. The selection can mix providers and domains. One confirmation shows the number of selected items; confirming deletes all of them and returns you to the list.
- A single item also has a delete confirmation of its own, separate from the toolbar's. It reads "Are you sure you want to delete the selected item?" with Yes and No. Yes deletes the item. Either answer returns you to the SSO Providers list.
Enable providers for the Web App
IMPORTANT: Saving restarts the Web App instance. The restart closes all active connections and can cause loss of unsaved data.
On the Web App instance's Authentication tab:
- Under SSO Authentication, Available Single Sign-On services: lists one check box per provider, sorted by name. Select the providers people may sign in with. When no provider exists, the tab shows No services configured. and Add SSO providers instead.
- Click Save and Restart. The button is disabled unless Allow password authentication or at least one provider is selected.
Enable providers for the API
An API instance that uses Windows authentication has no Authentication tab. On the Authentication tab of any other API instance, the Password Authentication part notes that password authentication must also be enabled in the user accounts. The tab shows nothing until the list of providers has loaded, and the Admin Center returns that list only to the administrators named in Before you begin. To enable providers:
- Under SSO Authentication, Available Single Sign-On services: lists one check box per provider, sorted by name. Select the providers. When no provider exists, the tab shows No services configured. and Add SSO providers instead.
- Click Save and Restart. The button appears once you change the form, under a warning that saving restarts the API instance. It is disabled unless Allow password authentication or at least one provider is selected.
After a successful save, the API instance restarts. A provider that was enabled for the API but no longer appears in the list is removed from the API's settings when you save.
Enable providers for the Self Service Portal
On the portal's Authentication tab, select the providers people may sign in to the portal with. For a portal that does not use Windows authentication, Save is disabled unless Allow password authentication or at least one enabled SSO provider is selected. You must also choose the workflow action that creates a portal account for a person who signs in with single sign-on.
A provider enabled for the portal can also be marked for accountless sign-in; see In the Self Service Portal.
Convert a standard account to single sign-on
Change the account's login with Modify Login. For Standard or Single Sign-On, a login that contains a backslash is rejected. If password authentication is off for the account and the login is not an e-mail address, a Yes/No warning offers to enable password authentication or to continue without it.
What happens at sign-in
How a sign-in is matched to an account
The provider's token is matched to an account by the login, and by nothing else. Alloy Navigator reads the username claim configured on the provider record from the token and compares it, ignoring case, with the logins of the accounts. There is no mapping table and no matching by e-mail address, and an account does not record which provider it uses.
The account's login must therefore be exactly the value the provider sends.
When a Microsoft or Okta provider keeps its starting username claim,
preferred_username, that value is the user principal name.
When no account matches, the sign-in is refused. The one exception is a provider marked for accountless sign-in to the Self Service Portal; see In the Self Service Portal. Sign-in to the API with a provider's token is refused the same way.
In the Web App
The Web App's Sign in page shows a Sign in with button, followed by the provider's name, for every provider enabled for the Web App. When password authentication is on, the page also shows the password form: User Name, Password, Keep me signed in, and Sign in. A separator appears only when both the form and at least one provider button are shown. For how technicians sign in, see Sign in to the Web App.
- HTTPS. The provider buttons are disabled under the hint Secure connection required (HTTPS) when the page is not opened over HTTPS.
- Redirect address. The redirect address the Web App gives the provider
always uses
https. Its host is the host and port of the request, or, when the Web App's proxy host setting names a header that the request carries, that header's value. The Web App uses the same base address for its redirect after sign-in and for other links, so a wrong proxy host setting affects more than single sign-on. - Scopes. The Web App asks the provider for the
openid,profile, andemailscopes. - Staying signed in. After a successful single sign-on, the Web App keeps the user and the provider for ten days and, on the next visit, signs the user in again without going to the provider. If that fails, the Web App shows the error.
- Missing claim. When the token does not contain the username claim, the Web App reports this as its own error, naming the claim it expected. This is the first thing to check when a provider works elsewhere but not in the Web App.
- Password sign-in. An account that keeps a password can also sign in through the password form with its login.
An account that matches but does not pass the checks for technician sign-in (see Accounts) is refused with the message: "Your account '<login>' is not an active Alloy Navigator account. Please contact your Alloy Navigator administrator."
The Web App reads its providers when it starts:
- A new provider appears in the Web App after the Web App restarts.
- A change to a provider's client secret or username claim takes effect immediately.
- A change to a provider's client ID, authority, or name takes effect after the Web App restarts.
In the Self Service Portal
When a provider is marked for accountless sign-in in the portal's settings, a person whose identity matches no account is not refused. The portal matches the e-mail address the provider asserts against existing person records, creates a person from the asserted full name and e-mail address when none matches, and runs the session for that person. Accountless sign-in is the one way of signing in that creates a record. A directory can be marked for accountless sign-in in the same way; see Authentication Methods. For signing in to the portal, see Sign In to the Portal.
In the API
The API validates a provider's token against that provider's OpenID Connect metadata, and matches it to an account as described in How a sign-in is matched to an account.
In the Mobile App
The mobile apps run the provider's sign-in page in a browser view inside the
app. When the provider redirects to http://localhost:4000, the app takes the
response and closes the browser view.
The Alloy Inventory Scanner app asks for the openid, profile, email, and
offline_access scopes, reduced to those the provider lists.