Configuring SAML JIT with Cisco Account

Any information provided in this document regarding future functionalities is for informational purposes only and is subject to change including ceasing any further development of such functionality. Many of these future functionalities remain in varying stages of development and will be offered on a when-and-if available basis, and Cisco makes no commitment as to the final delivery of any of such future functionalities. Cisco will have no liability for Cisco's failure to deliver any or all future functionalities and any such failure would not in any way imply the right to return any previously purchased Cisco products.

Security Assertion Markup Language (SAML) just-in-time (JIT) provisioning uses SAML authentication to verify a user's identity when they log in. If the user does not already exist in ThousandEyes, the system automatically creates the user account during the login process. This process is called just-in-time provisioning because users do not need advance provisioning.

Each time a user logs in, SAML JIT provisioning creates or updates the user's profile using the attributes provided by the identity provider (IdP). If your organization previously provisioned users with SCIM or another method, SAML JIT provisioning overwrites the existing profile information with the latest values from the IdP. This behavior helps keep user records up to date.

SAML JIT provisioning with Cisco Identity supports service provider (SP)-initiated login only. IdP-initiated login is not supported, including launches from your IdP application catalog. Users can log in from the ThousandEyes login screen or an SP-initiated link such as https://app.thousandeyes.com/v2/login?fwd=/account/switch/<AID>, where <AID> is your account group ID.

Use Cases

Organizations of any size can use SAML JIT provisioning. It is especially useful for organizations with large numbers of users, multiple roles or account groups, and a need to assign different permissions based on those roles and groups. This approach is well suited for organizations with frequently changing workforces, such as those that employ seasonal workers or operate large customer support centers.

Prerequisites

• An account or subscription with your chosen IdP.

• You must enable SSO. For more information on SSO configuration, see Configure SSO with Cisco Account.

• Your IdP must send role information alongside identity attributes. The attribute name must match the SAML Role Name Attribute you configure under User Provisioning > SAML Just-In-Time Settings in ThousandEyes.

• Do not use SAML JIT provisioning and SCIM provisioning together. SAML JIT overwrites user records on every login.

• Keep SSO enabled while you use SAML JIT provisioning. You cannot fully disable SSO while JIT is in use.

• A ThousandEyes account assigned a role with the following permissions:

  • Edit security & authentication settings

  • Edit users in all account groups

  • View security & authentication settings

  • View all account groups settings or View agents in account group or View all users

  • View roles or View all users

  For more information on permissions, see Role-Based Access, Explained.

About This Task

When you log in through SSO with SAML JIT enabled, the JIT update flow replaces your ThousandEyes roles with the values from your IdP assertion. In organizations with Cisco Identity enabled, the built-in Organization Admin role controls access to the tenant admin portal under Manage > Account Settings > Organization Settings (Single Sign-On (SSO) > Go to admin portal). Legacy SAML JIT provisioning did not have this requirement because no tenant admin portal existed.

If your IdP does not send a group or role named Organization Admin that matches the ThousandEyes role name exactly, you keep your other ThousandEyes admin permissions but lose access to the tenant admin portal after that login.

Role Name Matching

SAML JIT provisioning maps IdP role or group values to ThousandEyes roles. IdP and ThousandEyes role names must match exactly, including case, spacing, and special characters. For example, a role named IT in your IdP does not map to Organization Admin in ThousandEyes. If the IdP sends a role that has no matching ThousandEyes mapping, user creation or login can fail. Cisco Identity might create the user, but ThousandEyes provisioning fails when role mappings do not match.

Every organization should maintain at least one Organization Admin mapping. This built-in role includes the management permissions needed to manage users and SAML JIT settings. Do not remove the Organization Admin mapping if any admin needs access to the Cisco Identity tenant admin portal. A custom role with the same management permissions does not provide tenant admin portal access.

• Before you test SSO: Create a matching Organization Admin group or role in your IdP, and assign it to every ThousandEyes admin who needs access to the Cisco Identity tenant admin portal.

• If you lose tenant admin portal access: Reassign the built-in Organization Admin role in Manage > Account Settings > Users and Roles. Another admin can do this for you, or you can reassign the role to yourself if you still have user-management permissions. After the role is reassigned, access propagates to Cisco Identity shortly.

• Permanent fix: Create an Organization Admin group or role in your IdP, save your ThousandEyes role mappings, and log in again through SSO. On the next login, JIT provisioning assigns the Organization Admin role back to your account.

Display Name Attributes

When SAML JIT provisioning creates or updates a user, ThousandEyes determines the display name from IdP attributes as follows:

• If only displayName is provided, ThousandEyes uses it. Leading and trailing spaces are trimmed.

• If both displayName and http://schemas.microsoft.com/identity/claims/displayname are provided, the first attribute listed is used.

• If displayName, firstName, and lastName are all provided, displayName takes precedence.

• If displayName is not provided, ThousandEyes combines firstName and lastName. If only one is present, that value is used. If neither is provided, the default name JIT Created User is assigned.

To avoid the default name JIT Created User, configure your IdP and map Profile Attributes in the Cisco Identity portal to send at least one of the following: displayName, firstName, or lastName.

Steps

Step 1: Configuring SAML JIT in the Cisco Identity Portal

1. In ThousandEyes, go to Manage > Account Settings > Organization Settings.

2. In the Single Sign-On (SSO) section, click Go to admin portal.

3. In the Cisco Identity portal, go to Settings > Manage IdPs.

   If you're setting up a new SAML IdP, skip Edit IdP. Follow Configure SAML IdP with Cisco Account to add your IdP, then return to this guide and configure the SAML mapping attribute.

4. For the SAML IdP you want to edit, click ....

5. Select Edit IdP.

6. If needed, edit the SAML configuration and click Next.

7. Configure the SAML mapping attribute.

   Cisco Identity uses the SAML mapping attribute to match the authenticated user to the provisioned user record. Use the SAML attribute name your IdP sends. The following example maps uid to the user's email, UPN, or eduPersonPrincipalName.

   SAML attribute name	Cisco Identity attribute name	Attribute description
   uid	Username/Primary email address	Maps the UID attribute to the provisioned user's email, UPN, or eduPersonPrincipalName.

8. Click the Configure custom claims, JIT settings, and linking attributes dropdown.

9. Add Custom Claims.

   Custom claims pass additional IdP attributes, such as role or group values, to Cisco Identity. ThousandEyes uses these claims with SAML JIT role mappings to assign access when users are created or updated. Include the attribute your IdP uses for roles (for example, Group). The name must match the SAML Role Name Attribute you configure under User Provisioning > SAML Just-In-Time Settings in ThousandEyes.

   1. Click + Add custom claim.

   2. Enter your custom claim.

      You can add a maximum of 25 custom claims.

10. Select Just-In-Time (JIT) settings.

    Select the following options as needed:

    • Create or activate users (required): Select this option. If Cisco Identity does not find an active user, it creates the user and updates the attributes after the user logs in to the IdP.

    • Update user with SAML attributes (optional): If Cisco Identity finds a user with the specified email address, it updates the user with the attributes mapped in the SAML assertion.

    If you enable Update user with SAML attributes, see Role Name Matching for how role updates affect access to the tenant admin portal.

11. Configure the Linking Attribute.

    The linking attribute uniquely identifies a user so Cisco Identity can update the user's profile. If you enabled Update user with SAML attributes and use a linking attribute other than email or uid, users can update their email address through JIT provisioning.

    1. Click the Select an attribute dropdown and select externalId as the Cisco Identity attribute name.

    2. For the SAML attribute name, enter an attribute name.

       For example:

       SAML Attribute Name	Cisco Identity Attribute Name	Attribute Description
       Example: user.objectid	externalId	A unique attribute for identifying a user and updating their profile and information, including their email address.

12. Configure Profile Attributes.

    Profile attributes map user profile details from your IdP to Cisco Identity attributes. Cisco Identity can use these mappings to create or update the user's profile during JIT provisioning. See Display Name Attributes for how ThousandEyes resolves display names from IdP attributes.

    SAML Attribute Name	Cisco Identity Attribute Name	Attribute Description
    Example: user.preferredlanguage	preferredLanguage	The user's preferred language.
    Example: user.locale	locale	The user's locale.
    Example: user.timezone	timezone	The user's primary time zone.
    Example: user.displayname	displayName	The user's display name.
    Example: user.givenname	name.givenName	The user's first name.
    Example: user.surname	name.familyName	The user's last name.
    Example: user.streetaddress	addresses.streetAddress	The street address of their primary work location.
    Example: user.locality	addresses.locality	The city or locality of the user's primary work location.
    Example: user.region	addresses.region	The state or region of the user's primary work location.
    Example: user.country	addresses.country	The country of their primary work location.
    Example: user.postalcode	addresses.postalCode	The postal code of the user's primary work location.
    Example: work phonenumber	phoneNumbers.work	The work phone number of their primary work location. Use the international E.164 format only (15 digits maximum).
    Example: mobile phonenumber	phoneNumbers.mobile	The user's mobile phone number. Use the international E.164 format only (15 digits maximum).
    Example: extension phonenumber	phoneNumbers.extension	The work extension of their primary work location. Use the international E.164 format only (15 digits maximum).
    Example: user.jobtitle	title	The user's job title.
    Example: user.department	department	The user's job department or team.
    Example: work emails	emails.work	The user's work email.
    Example: user.organization	organization	The user's organization ID.

13. Configure Group attributes.

    Group attributes map group identifiers from your IdP to Cisco Identity group attributes. Cisco Identity can use these mappings to associate the user with a group for licensing or service settings.

    SAML Attribute Name	Cisco Identity Attribute Name	Attribute Description
    Example: user.groupid	groupId	Maps the IdP group identifier to the Cisco Identity group ID.
    Example: user.groupexternalid	groupExternalId	Maps the IdP external group identifier to the Cisco Identity external group ID.

    Configure the row that matches the group identifier your IdP sends. If your IdP sends both values, configure both rows.

14. Click Save.

Step 2: Configuring Role Mappings in ThousandEyes

1. Go to Manage > Account Settings > Organization Settings > Security and Authentication.

2. Scroll to User Provisioning > SAML Just-In-Time Settings.

3. Switch the Enable toggle on.

4. Select the SAML Role Name Attribute you want to map.

   • If the role name attribute is not listed in the dropdown, select Custom… to enter a new role name attribute. This value must match the custom claim you add for roles in the Cisco Identity portal.

5. In the Role dropdown, select a role to add.

6. In the Account Groups dropdown, select all the account groups you want this role to access.

7. Click + Add mapping or - to add or remove role and account group mappings as needed. Include a mapping for Organization Admin before you test the SSO login.

8. Click Save.

Testing SAML JIT Login

After you complete the Cisco Identity portal and ThousandEyes configuration, test with an SP-initiated login:

1. In your browser, open https://app.thousandeyes.com/v2/login?fwd=/account/switch/<AID>, where <AID> is your account group ID.

2. Log in to your IdP when prompted.

3. Confirm that ThousandEyes creates or updates the user and assigns the expected roles.

You can also enter your email address on the ThousandEyes login screen. If you are not already logged in to your IdP, ThousandEyes redirects you to your IdP and then back to ThousandEyes to complete provisioning and the login process.

Editing or Disabling SAML JIT Settings

Editing Settings

1. Go to Manage > Account Settings > Organization Settings > Security and Authentication > User Provisioning > SAML Just-In-Time Settings.

2. To change attributes, select or type a new attribute name.

3. To change roles, select a new role from the dropdown. You must first create the role under Manage > Account Settings > Users and Roles > Roles before it appears in the dropdown.

4. To change account group access, select or clear account groups in the Account Groups dropdown.

5. Click Save.

Disabling SAML JIT

To stop using SAML JIT provisioning, switch the Enable toggle off. Your settings remain saved but are inactive.

Troubleshooting

Common SAML JIT issues are caused by configuration errors in ThousandEyes or the Cisco Identity portal:

• SSO or SAML JIT not enabled: Confirm that SSO is enabled and that the Enable toggle is on under User Provisioning > SAML Just-In-Time Settings.

• No SAML Role Name Attribute configured: Set the SAML Role Name Attribute under User Provisioning > SAML Just-In-Time Settings in ThousandEyes. It must match the role custom claim in the Cisco Identity portal.

• Role names do not match: The role values your IdP sends must exactly match ThousandEyes role names and the role and account group mappings under SAML Just-In-Time Settings in ThousandEyes.

• No roles in IdP assertion: Confirm that your IdP sends role or group values in the attribute you configured as a custom claim.

For additional help, see Test Your SSO Setup and Troubleshoot Login Errors.

Learn More

• Identity Provider Setup: Configure IdP-side metadata, certificates, and user assignments before you add SAML in the Cisco Identity portal.

• Configure Routing Rules: Define how authentication requests are routed by domain or group after you add an IdP.

• Edit an IdP Configuration: Edit or delete IdP records in the Cisco Identity portal after initial setup.