Single Sign-On

External Authentication

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:

• Google: Leverages the Google OAuth2 identity services. Any Google account that uses the Google sign-in page is compatible, including personal, school, or business accounts with custom domains.
• Microsoft: Leverages the Microsoft OpenID identity services. Compatible accounts include Microsoft accounts such as Live, Passport, Outlook.com, Office 365, and Azure Active Directory accounts.
• SAML2 (Enterprise Edition Only): An older technology, but still in widespread use across many organizations. Popular implementations include Microsoft’s Active Directory Federation Services (AD FS), Okta SAML2 idP, and OneLogin SAML2 idP. Agility Blue allows for service provider or idP-initiated login methods for this authentication type.

The benefit to using an external identity provider is that you do not have to provide any usernames or passwords to Agility Blue, thus making the login process much more secure and seamless.

Manually Linking an External Account

Click on the “Linked Accounts” 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 desired identity provider. Future configuration options may differ depending on the identity provider. For Google and Microsoft, the configuration options are similar.

To link to either Google or Microsoft 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 association 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 Google, if a user is already logged into Gmail, the browser will already know that the user logged in and will not ask the user to provide their Google 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 should 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.

Example: Login Using a Google Account

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

If the user is already logged into Google somewhere else, they will be automatically authenticated within Agility Blue and brought to the Workspaces page. If the user is logged into Google but has multiple accounts, they will be asked by Google which account they would like to use. If the user is not logged in, they will be asked by Google to enter their Google account credentials.

Example: Login Using a Microsoft Account

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

If the user is already logged into Microsoft somewhere else, they will be automatically authenticated within Agility Blue and brought to the Workspaces page. If the user is logged into Microsoft but has multiple accounts, they will be asked by Microsoft which account they would like to use. If the user is not logged in, they will be asked by Microsoft to enter their Microsoft account credentials.

Configure a SAML2 Identity Provider (Enterprise Edition Only)

SAML2 identity providers like ADFS, Okta, and OneLogin are popular methods deployed by organizations to help facilitate users that typically use their Windows Active Directory login information 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.

Agility Blue supports SAML2 assertions that can be initiated from Agility Blue (SP > idP, AuthN) as a button on the login page or initiated from the SAML2 identity provider (idP > 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.

SAML2 configuration is located on the Organization Details page on the Authentication tab.

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.

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 you will need to consult your identity provider’s documentation on how to provide the correct details. There are two examples below that should cover most use cases.

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.

Example: Active Directory Federation Services (AD FS)

This example uses a typical AD FS 2.0 setup on a Windows 2008 R2 server that does not use any special configuration changes from the standard install. Active Directory is setup as the attribute store.

Agility Blue must be setup as a Relying Trust Party within AD FS using the following steps:

1. Within the AD FS management console, make sure that the “AD FS 2.0” node is highlighted in the left-hand Explorer panel and click on “Add Relying Party Trust…” on the right-hand Actions panel.
2. Click the “Start” button after the Add Relying Party Trust Wizard appears.
3. Agility Blue does publish SAML2 metadata, but it has been our experience that adding a relying party manually works better. Click on the “Enter data about the relying party manually” radio button and click the “Next” button.
4. For the Display Name, enter “Agility Blue”. Click the “Next” button.
5. Choose the “AD FS 2.0 profile” and click the “Next” button.
6. For Configure Certificate, you should not need to specify an optional encryption certificate. Click the “Next” button to continue.
7. For Configure URL, ensure that “Enable support for the SAML 2.0 WebSSO protocol” is the only option checked. For the relying party SAML 2.0 SSO service URL, enter in https://api.agilityblue.com/identity for now. This value will need to be updated after you configure Agility Blue.
8. For the Configure Identifiers, add “https://agilityblue.com” as a Relying party trust identifier. Note that this is case-sensitive.
9. For Choose Issuance Authorization Rules, select “Permit all users to access this relying party” unless your organization wants to set special user access requirements. Click the “Next” button when ready.
10. Click the “Next” button on the Ready to Add Trust page.
11. On the Finish page, ensure that “Open the Edit Claim Rules dialog for this relying party trust when the wizard closes” option is checked.

Claim Rules must be added in order to send Agility Blue the proper information. Agility Blue needs an email claim in order to link the user with their Agility Blue account successfully.

1. While on the Edit Claim Rules for Agility Blue window, under the Issuance Transformation Rules tab, click on the “Add Rule…” button.
2. On Choose Rule Type, select “Send LDAP Attributes as Claims” from the Claim rule template dropdown. Click on the “Next” button.
3. On Choose Rule Type, enter a name for the rule, such as “Map Email”
4. Select Active Directory as the Attribute Store
5. Select “Email-Addresses” for LDAP Attribute map.
6. Select “E-Mail Address” for Outgoing Claim Type.
7. Click the “OK” button.
8. Back on the Edit Claim Rules for Agility Blue window, under the Issuance Transformation Rules tab, click on the “Add Rule…” button.
9. On Choose Rule Type, select “Transform an Incoming Claim” from the Claim rule template dropdown. Click on the “Next” button.
10. On Choose Rule Type, enter a name for the rule, such as “Email to Name ID”
11. Set Incoming claim type to “E-Mail Address”
12. Set Outgoing claim type to “Name ID”
13. Set Outgoing name ID format to “Email”
14. Ensure “Pass through all claim values” is selected and click on the “OK” button.

Agility Blue now needs to be configured with the following steps:

1. Login to Agility Blue as an Organization Admin, click on the Organization tab in the Home area, and click on your Organization’s name to view the Organization details page.
2. Click on the Authentication tab on the left.
3. Under the SAML2 configuration block, click the “Configure” button on the right.
4. Enter a Caption. In addition to naming the SAML2 identity provider, this also serves as the button text presented on the Login page.
5. The Entity ID is provided by AD FS. By default, it is your organization’s trust endpoint. You can find your entity id by viewing the AD FS metadata endpoint.
6. The Metadata URL default for AD FS is [yourADFSserver]/FederationMetadata/2007-06/FederationMetadata.xml
7. You can find the metadata url within the AD FS management console under Service > Endpoints. The metadata endpoint that Agility Blue requires is the Federation Metadata url.
8. For Claim Type, enter “email”
9. If you would like users to initiate logins from AD FS to Agility Blue, make sure that “Allow Idp-Initiated SSO?” is selected.

Agility Blue generates and supplies the SP ACS URL that needs to be supplied to AD FS (this is the value that the relying party SAML 2.0 SSO service URL needs to be updated with from step 7 of configuring Agility Blue as a Relying Trust Party within AD FS above).

1. Switch back to the AD FS server.
2. Navigate to Trust Relationships > Relying Party Trusts within the AD FS management console.
3. Double Click on “Agility Blue” or right click and select Properties.
4. Click on the Endpoints tab
5. Remove the current URL
6. Click on the “Add…” button
7. You will see the Add an Endpoint dialog
8. Select SAML Assertion Consumer as the Endpoint type
9. Select POST as the binding
10. Leave Index at 0
11. Copy the ACS URL from that Agility Blue provided in the configuration details for the URL input box.
12. Click the “OK” button.

At this point, you must contact Sadie Blue support in order to finalize the configuration process. The idP must be added to our authentication pipeline in order to accept it.

Now that the idP is configured for your organization, users can now map the AD FS emails to their Agility Blue emails on their account details page. At this point, AD FS idP-initiated SSO should be working (provided you enabled allow idP-Initiated SSO).

If you would like Agility Blue to display a button that your users can use on the Agility Blue login page, you need to register the IP Address ranges that they would be logging into Agility Blue from.

You can register IP Address ranges under the SAML2 configuration block.

1. Click on the “Register an Ip Address Range for this Identity Provider…” link.
2. The New Saml2 Idp Ip Range Dialog window appears
3. Choose the protocol (generally ipv4).
4. Enter the starting address.
5. Enter the ending address.
6. Click Save.

Agility Blue allows for ranges of IP addresses to simplify entering in ip addresses for organizations with blocks of public IP ranges. If your organization only has one IP address, just enter the same address for both the starting and ending Ip Address inputs.

The login page will now display a third button with your SAML2 caption that users can click on.

If the user is already signed in through ADFS, they will be taken directly to Agility Blue’s Workspaces page (provided their ADFS email is mapped). If they are not signed in, a message box will appear asking for credentials. The user must enter their Active DIrectory credentials to continue.

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 manual and try again. If the user is still experiencing issues, have them contact support@sadiebluesoftware.com for troubleshooting assistance.