Configuring SSO in Agile.Now

Activating Single Sign-On (SSO) allows users on the Agile.Now platform to log in using their personal credentials on various platforms such as Google Mail, social networks, and others that expose the OpenID API. This streamlines the login process and enhances security.

The configuration flow consists of two parts: on the OpenID provider side and on the Agile.Now side.

Prerequisites

Ensure you have the Security role with create and update permissions.

Before beginning the integration, ensure you have the following information from your OpenID provider:

Parameter	Description
`Client ID`	A unique identifier for your application on the provider's platform.
`Client Secret`	A secret key used to authenticate your application.
`Discovery URL`	A well-known URL that provides OpenID configuration details.

Configuring on OpenID Provider Side

Many platforms—LinkedIn, Facebook, Google, Okta, and Microsoft Entra ID—provide OpenID APIs that perform user authentication, user consent, and token issuance. To integrate them with Agile.Now SSO, you should register an application on their side and obtain the following information:

OpenID Provider	Discovery URL	Link to Documentation
Google	https://accounts.google.com/.well-known/openid-configuration	OpenID Connect
LinkedIn	https://www.linkedin.com/oauth/.well-known/openid-configuration	How to Get SignIn with LinkedIn to work
Facebook	https://www.facebook.com/.well-known/openid-configuration/	Facebook Login
Okta	https://{yourOktaDomain}/.well-known/openid-configuration	Okta OIDC Integration
Microsoft Entra ID	https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration	Microsoft Entra ID Documentation

Note: For Okta, replace {yourOktaDomain} with your actual Okta domain name.

Remember to regularly check the secret key's expiration date and renew it as needed.

Configuring Social SSO with OpenID on Agile.Now

Once the Client ID, Client Secret, and Discovery URL are provisioned (as described above), you are ready to integrate the OpenID provider with the Agile.Now Platform.

Choose OpenID Provider

On the Settings application, go to Credential.
Click New Credential.
Choose OpenID Provider.
Assign a name to your credential for easy identification. This name will be visible to end-users during the login process.

Discovery URL

Specify the discovery configuration URL in the Discovery endpoint field.
Click the Upload icon to let the system fetch the configuration details.
In case of success, you will see the following confirmation:
Click Next to proceed.

Client ID and Secret

Fill in the Client ID and Client Secret fields with the information obtained from your OpenID provider.

Set Scopes

Ensure that the following scopes are selected, as they are necessary for basic SSO functionality:
- openid
- email
- profile

Callback URL

Specify the Callback URLs that will be used to redirect users after login and logout actions. These URLs should be the same as those specified on the OpenID provider platform.

Claims Mapping

Claim mapping is a critical aspect of configuring Single Sign-On (SSO) and OAuth2 authentication systems. It determines how user attributes from an external identity provider (IdP) like Microsoft Entra ID or Google are translated to user attributes in the Agile.Now system.

Claim Mappings in Agile.Now

When setting up an external authentication provider, it's essential to align the user information (claims) from the provider with the user details expected by Agile.Now. This ensures effective user management and seamless integration.

Attribute	Claim Value (example)	Description
Name	`name`	Represents the full name of the user. This field is typically required and should be correctly mapped to display the user's complete name within Agile.Now.
First Name	`given_name`	Represents the first name of the user. Mapping this correctly personalizes the user's experience within Agile.Now.
Last Name	`family_name`	Represents the last name of the user. Proper mapping ensures that the user's full name is accurately reflected in communications and records.
Email	`email`	This field must be unique and is essential for email communications within Agile.Now.
Phone	`phone_number`	If available, the user's phone number should be mapped for use in SMS communications. It should be unique if provided and visible within Agile.Now's user profile.
Username	`email`	Typically, the email address is used as the username. It should be a unique and required field, ensuring each user's username is distinct.
External ID	`oid`	Often represented as `oid` or another unique identifier in the IdP. This ID should be unique and not visible, allowing each user to be individually recognized within Agile.Now. It allows you to change the user's ID or email address without creating duplicate records in Agile.Now.
Roles	`roles`	Roles can be mapped from the identity provider to assign specific groups to users within Agile.Now, ensuring alignment with user permissions and access control. When mapping roles, the system synchronizes the user with existing groups based on the role value (role = Group.Name). If a corresponding group does not exist, a new group will be automatically created.

Importance of Claim Mappings

User Identification: Ensures Agile.Now can correctly identify and match users from the external IdP to the correct user records.
Data Consistency: Maintains consistent user data across different systems.
Authentication Flow: Supports a smooth authentication flow, allowing Agile.Now to receive and interpret user data from the IdP.

Best Practices for Claim Mappings

Ensure all required fields in Agile.Now have a corresponding claim from the IdP.
Regularly review and update mappings to accommodate changes in the IdP's claim structure.
Use stable claims like an immutable user ID instead of an email, which might change over time.

Specify Default Group

Define a Default Group for users who do not have an external group associated with them, such as those logging in with a social account like Facebook. This ensures they are assigned the minimum rights in Agile.Now, with the option to enhance their permissions through group membership.

Activate SSO

Toggle the Credential status to Active to enable the SSO, making it available on the login screen.
Save the configuration.
Conduct tests to confirm that the SSO integration is functioning as expected.

Additional Steps for User Group Synchronization

After enabling SSO, test user group synchronization by having a user log in through SSO and verifying that their group memberships are accurately reflected within the Agile.Now platform.

Conclusion

Properly mapped claims are essential for setting up SSO and OAuth2 authentication in Agile.Now. They require careful planning and alignment between the external IdP's user attributes and Agile.Now's user attribute requirements. Accurate claim mappings ensure that user data is reflected correctly within Agile.Now, enabling effective user management and a seamless authentication experience.