Single Sign-On Authentication

External Authentication (SSO)

External authentication can be achieved by linking a supported external identity provider account to an existing Agility Blue account. Three identity providers are currently available:

The benefits to using an external identity provider for Single Sign-On (SSO) is that your organization is in control of your identity and the security surrounding your identity. Furthermore, you do not have to remember a separate set of usernames or passwords to access Agility Blue, making the login process less burdensome.

How Does SSO Work?

When you log in using an external provider (such as Google, Microsoft, or SAML2) from the Agility Blue login page, Agility Blue hands off the login process to the provider. The external provider is responsible for authenticating your identity.

Once authentication is successful, Agility Blue:

1. Receives an ID token from the external identity provider.

2. Exchanges it for an Agility Blue access token, based on the linked Agility Blue account’s permissions.

Authentication vs. Authorization

It’s important to note that logging in with an external provider does not automatically grant access to Agility Blue.

• Authentication

  The external provider verifies who you are.

• Authorization

  Agility Blue determines what you can access based on its roles and permissions system.

All access control is managed within Agility Blue, ensuring that user permissions are enforced independently of the external provider.

Linking an External Account

Heads up!

If the user’s email address in Agility Blue matches the same email address of the identity provider, Agility Blue will automatically link the accounts the first time the user attempts to initiate SSO.

To manually link an external account, click on the Linked Accounts section tab on the user details page to view and configure accounts from the list of available identity providers.

A user can choose to configure any combination of identity providers with a single Agility Blue account, however, only one account from each identity provider is allowed.

If an account is currently linked, the email address of that account will be shown next to the identity provider’s name, otherwise the text Not Linked will be displayed.

Click on the Configure button of the identity provider you wish to link with.

To link to identity providers, the external account email address is all that is required. Enter the account email address and click the Save button to complete the linking process.

Agility Blue will now accept identity authorization tokens from the configured identity provider. When a user clicks on the appropriate external identity provider button on the login page, they will be redirected to the identity provider’s login page (unless they are already logged in to that provider). For instance, in the case of Microsoft, if a user is already logged into their Entra ID account, the browser will already know that the user is logged in and will likely not ask the user to provide their Entra credentials. If the user has more than one account, the identity provider will ask the user which account they would like to use. The user must select the account that uses the same email address that they associated with in Agility Blue.

To unlink a linked account, click on the broken link icon to the left of the Configure button for the desired identity provider.

Heads up!

Users with the Organization Administrator role may configure and manage linked accounts for any user account.

Configure a SAML2 Identity Provider ^{(Enterprise Edition Only)}

SAML2 identity providers like Entra ID, Okta, and OneLogin are popular methods deployed by organizations to help facilitate users that typically use a managed directory service in order to authenticate a variety of applications. These services sit in a DMZ on premises or in the cloud (SaaS) in order to protect the integrity of the company’s domain, but still offer a flexible way for their users to authenticate with modern application login flows.

Agility Blue supports SAML2 assertions that can be initiated from Agility Blue (SP to idP, AuthN) as a button on the login page or initiated from the SAML2 identity provider (idP to SP, Unsolicited). In order to take advantage of this method of authentication, Agility Blue must be setup as a trusted party within your organization’s SAML2 idP. There is configuration information required by your idP that Agility Blue will provide, and there is configuration information required by Agility Blue that your idP will provide.

Notice!

Only user accounts with the Organization Administrator role within Agility Blue can configure a SAML2 identity provider. You must first contact us at support@sadiebluesoftware.com to make the SAML2 configuration options available within your instance.

SAML2 configuration is located within your organization’s details page on the Authentication section tab at the bottom. Click on the Configure button to launch the SAML2 configuration window.

Fill out the form with the information required. Depending on your provider, you may need to put in temporary placeholder information for a couple of fields to save the form and retrieve Agility Blue information that is generated to provide for your identity provider’s configuration first and then update your Agility Blue’s configuration after completing your provider’s setup. Agility Blue asserts accounts that require a claim containing an email address. Identity providers handle this differently based on the provider and a variety of policies, so check with your provider’s documentation or support options for specific details on setting up applications for use with SAML2 for your provider.

In order for users to see a button on the login page to initiate the SP SSO flow, you must register IP Address ranges that users will be accessing Agility Blue from. If your users are outside of these ranges, the button will not be available. If you only want idP-initiated control, you do not need to do this as users will login from your application’s SSO page instead. Click on the Register an Ip Address Range link to register as many address ranges as you need. If you want to show the SAML2 login button from anywhere and not restrict it to a specific IP address range, enter a range of 0.0.0.0 and 255.255.255.255 .

Once configuration for the idP is complete, users or admins will be able to see and link their SAML2 account with their Agility Blue account on their user account page. If a user’s email address is the same as the email claim value coming from the provider, their Agility Blue account will be linked automatically.

Important!

You must alert Agility Blue support at support@sadiebluesoftware.com to finalize any configuration changes to a SAML2 identity provider configuration. Failure to do so will result in rejected responses by Agility Blue for login attempts with your idP. Updating IP address range information does not require support intervention.

Login Using a Google Account

On the login page, click the Google button on the External Authorization login panel.

Notice!

Do not enter your Google credentials in the Username and Password input boxes on the Agility Blue login page — those fields are only to be used for Agility Blue accounts.

If you are already logged into Google somewhere else, you will be automatically authenticated with Agility Blue and brought to the workspaces page. If you are logged into Google but have multiple accounts, you will be asked by Google which account you would like to use. If you are not logged in, you will be asked by Google to provide your Google account credentials.

Login Using a Microsoft Account

On the login page, click the Microsoft button on the External Authorization login panel.

Notice!

Do not enter your Microsoft credentials in the Username and Password input boxes on the Agility Blue login page — those fields are only to be used for Agility Blue accounts.

If you are already logged into Microsoft somewhere else, you will be automatically authenticated with Agility Blue and brought to the workspaces page. If you are logged into Microsoft but have multiple accounts, you will be asked by Microsoft which account you would like to use. If you are not logged in, you will be asked by Microsoft to provide your Microsoft account credentials.

Login Using a SAML2 Account ^{(Enterprise Edition Only)}

On the login page, click the name of your SAML2’s button (the caption of this button is set during SAML2 configuration).

Notice!

Do not enter your SAML2 credentials in the Username and Password input boxes on the Agility Blue login page — those fields are only to be used for Agility Blue accounts.

You will be brought to your SAML2 identity provider’s login system. Follow any prompts there and you will be brought back to Agility Blue upon successfully authenticating with your idP.

External Account Errors

If a user tries to use an external identity provider that is not linked to an Agility Blue identity account, the user may receive an identity services error.

Follow the steps outlined in the Linking an External Account section of this documentation and try again. If the user is still experiencing issues, have them contact us at support@sadiebluesoftware.com for troubleshooting assistance.