Online Help | Desktop App

Configuring SSO authentication with AD FS

Introduced in 2021.1

This article explains how to integrate Alloy Navigator Express with Microsoft's Active Directory Federation Service (AD FS) for single sign-on, so your users can sign in to Alloy Navigator Express with their AD domain credentials.

PREVIOUS STEP: Before you begin, see Managing single sign-on (SSO) providers for basic information and prerequisites.

Register Alloy Navigator Express in AD FS

First, you need to create an integration for your Alloy Navigator Express apps in AD FS so it can provide authentication and authorization services for Alloy Navigator Express users. See your AD FS documentation on how to integrate OpenID Connect (OIDC) applications. For example, see Scenario: Web App (Server App) calling Web API.

You will need this information for creating OIDC app integration. Other parameters are set by default, you can change them as required.

Parameter Value

Sign-in redirect URIs

The sign-in redirect URI is the location where your AD FS IdP sends the authentication response and ID token for sign-in requests.

Alloy Navigator Express web apps (the Web App and Self Service Portal):

  • [Web App URL]/signin-oidc

  • [SSP URL]/signin-oidc

    The Web App URL and SSP URL must use HTTPS, not HTTP.

Alloy Navigator Express mobile apps (Alloy Navigator and Alloy Inventory Scanner):

  • http://localhost:4000
Application Credentials

Generate a shared secret

Copy and save the secret! It will not be available after you complete the registration.

Note that a single "Server application" group serves all your Alloy Navigator Express web apps, as shown in the screenshot below. Add a redirect URI for every Alloy Navigator Express web app instance you want to use SSO.

Configuring SSO for Alloy Navigator Express mobile apps requires creating a separate "Native application" group, as the screenshot below shows.

You will also need to add a "Web API" group, as shown below.

Note the Client Identifier and Secret values. You will use them later in the Alloy Navigator Express Settings App.

Create an SSO Provider record for AD FS in Alloy Navigator Express

To store AD FS metadata in Alloy Navigator Express, create an SSO Provider record using the Settings App. Here is what you will need. All these data are available in your AD FS.

  • Authority - the OpenID Connect endpoint URL (HTTPS protocol must be used);

  • Client ID - the OpenID Connect client ID provided by AD FS;

  • Client Secret - the client secret for the Alloy Navigator Express app provided by AD FS;

  • Full Name Claim - the claim where AD FS stores user full names. Alloy Navigator Express needs that claim for creating Person records for self-registering Self Service Portal customers. The default value is name.

  • User Name Claim - the claim where AD FS stores usernames (email addresses); those usernames must match usernames (email addresses) in Alloy Navigator Express accounts. The default value is unp, for "User Principal Name.".

To add an SSO Provider record for AD FS:

  1. In Alloy Navigator Express Settings, go to Accounts and Roles > SSO Providers and select New > ADFS from the Module menu. The AD FS dialog box opens.

  2. In the Name field, keep the default name or specify a different one. Alloy Navigator Express users will see that name in their sign-in dialog as Sign in with [Name].

  3. In the ADFS Domain field, enter the AD FS domain name for your org. It can look like adfs.companyname.com.

  4. In the Authority field, review the service endpoint URL path. Note that it must start with https://, because secured protocol is requited.

  5. Provide the credentials of your Alloy web apps from AD FS:

    • Client ID - the unique identifier that Alloy apps will use when requesting an access token from AD FS. This is the "Client Identifier" value that the AD FS configuration provides.

    • Client Secret - the secret string that the Alloy apps will use to prove its identity when requesting an access token from AD FS. This is the "shared secret" that you copied and saved before.

  6. When users sign in, their user information from AD FS becomes available to Alloy Navigator Express. By default, the claims that carry information about the user include the user's email address, name, and preferred username.

    Typically, you can keep the default values in the Full Name Claim and the User Name Claim fields.

  7. Click OK to save your record.

NEXT STEP:Step 3: Configure the Alloy Navigator Express apps to use SSO.