For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

Last updated