Configuring SSO in Agile.Now
- 10 Aug 2024
- 5 Minutes to read
- Print
- DarkLight
Configuring SSO in Agile.Now
- Updated on 10 Aug 2024
- 5 Minutes to read
- Print
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
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
Securityrole 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:
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
Settingsapplication, go toCredential. - 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 endpointfield.Click the
Uploadicon
to let the system fetch the configuration details.
In case of success, you will see the following confirmation:
Click
Nextto proceed.
to let the system fetch the configuration details.
Client ID and Secret
- Fill in the
Client IDandClient Secretfields 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:
openidemailprofile
Callback URL
- Specify the
Callback URLsthat 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 | 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 Groupfor 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 statustoActiveto 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.
Was this article helpful?
