Configuring JIT Provisioning with Cisco Account

Just-in-time (JIT) provisioning creates or updates a ThousandEyes user when the user signs in through Cisco account. It uses identity, profile, and role or group information from your identity provider (IdP).

JIT provisioning runs when a user signs in. It is not a continuous provisioning or deprovisioning service. When JIT processes a login, ThousandEyes determines the user’s roles and account-group access from the configured role mappings.

Cisco account supports JIT provisioning with Security Assertion Markup Language (SAML) and OpenID Connect (OIDC). Both protocols use the same JIT role mappings in ThousandEyes. The protocol-specific difference is how Cisco Identity receives the identity, profile, and role or group values.

JIT provisioning with Cisco account supports service provider (SP)-initiated login only. Start from the ThousandEyes login screen or an SP-initiated link. IdP-initiated launches, including launches from an IdP application catalog, are not supported for this workflow.

How JIT Role Mappings Work

The role-mapping flow is the same for SAML and OIDC:

1. IdP role or group value.

2. SAML assertion attribute or OIDC ID-token claim.

3. Cisco Identity custom claim.

4. ThousandEyes JIT role attribute.

5. ThousandEyes role and account-group mapping.

The claim name must match the configured ThousandEyes JIT role attribute. Each incoming role or group value must exactly match the name of a ThousandEyes role in the mapping, including capitalization, spacing, and special characters. If a matching role does not exist, create a custom role with the same name as the incoming value.

For example, an OIDC ID token might contain:

{"groups":["TE-JIT-Users"],"name":"Jane Doe"}

Configure the example as follows:

• ThousandEyes JIT role attribute: groups

• ThousandEyes role: Create or use a custom role named TE-JIT-Users.

• ThousandEyes JIT role mapping: Select the TE-JIT-Users role and the account groups it can access.

For group-based mappings, send group values as an array when supported by your IdP. Create or use a ThousandEyes role with the same name as each group value that should provide access, then create one mapping for each value.

To access the Cisco Identity admin portal, map incoming admin role or group values to a ThousandEyes role with the Edit security & authentication settings permission. The built-in Organization Admin role is not required. If this permission is missing, admins might lose access after their next login.

Comparing SAML and OIDC JIT Provisioning

Area	SAML	OIDC
User identity	SAML mapping attribute, such as uid	OIDC identity claim, such as email or mail
Role or group values	Attribute or custom claim in the SAML assertion	Custom claim in the OIDC ID token, commonly an array such as groups
Cisco Identity configuration	SAML mapping attribute, custom claims, JIT settings, and profile attributes	OIDC metadata, scopes, discovery or endpoint settings, custom claims, JIT settings, and profile attributes
ThousandEyes role mappings	Same JIT role-mapping settings	Same JIT role-mapping settings

Prerequisites

Before configuring JIT provisioning, make sure that you have:

• A Cisco account configuration with SSO enabled. For more information, see Configure SSO with Cisco Account.

• An account with your chosen IdP.

• An IdP configuration that sends a stable, unique, and verified identifier for each user.

• An IdP configuration that sends role or group values for users who need access to ThousandEyes.

• A test user assigned to a dedicated application group or role. Avoid relying only on broad default groups such as Everyone.

• A break-glass routing rule that allows at least one administrator to sign in with local Cisco account credentials if SSO configuration fails. For more information, see Configure Routing Rules.

• 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

  To verify that the role grants Edit security & authentication settings, go to Manage > Account Settings > Users and Roles > Roles, locate the ThousandEyes role you plan to map to the admin role or group, and confirm that the permission is enabled.

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

Additional OIDC prerequisites

If you use OIDC, make sure that you have:

• An OIDC application registered with your IdP.

• The client ID, client secret, and redirect URI required by your IdP.

• An OIDC discovery URL or the required endpoint information.

• A role or group claim configured in the ID token.

• The required scopes, including openid and email.

• Claims configured on the same authorization server that Cisco account uses for login.

Do not use JIT provisioning and SCIM provisioning together. JIT provisioning can replace user profile and role information when the user signs in.

Keep SSO enabled while JIT provisioning is in use.

Configure JIT Provisioning

Use this procedure to configure JIT provisioning with either SAML or OIDC. Protocol-specific steps are labeled where they apply.

Configure the IdP, Cisco Identity, and ThousandEyes settings in the following order.

1. Open 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.

2. Add or Edit the Identity Provider

1. To add a provider, click + Add an IDP, select SAML or OpenID Connect, and click Next.

2. To edit a provider, click ... next to the provider and select Edit IdP.

3. Configure the Protocol-Specific Settings

1. (SAML only) Configure the SAML metadata and the required SAML mapping attribute.

   Use the SAML attribute that identifies the user in your IdP. For example, map uid to the user’s email address, user principal name (UPN), or eduPersonPrincipalName. For more information, see Configure SAML.

2. (OIDC only) Configure the OIDC metadata, scopes, and discovery URL or endpoint information.

   Register the Cisco Identity redirect URI in your IdP application. For more information, see Configure OpenID Connect.

3. (OIDC only) If your IdP supports more than one authorization server, verify which authorization server Cisco account uses for login.

   Configure the claims, scopes, and access policies on the authorization server identified by the discovery document’s issuer value.

4. (OIDC only) If you use a custom authorization server, define and allow the groups scope in its access policies.

Claims configured on one authorization server do not automatically apply to another. For example, an Okta claim configured on /oauth2/default might not appear if Cisco account uses the Okta organization authorization server.

4. Open the JIT and Custom-Claims Settings

1. (SAML only) Expand Configure custom claims, JIT settings, and linking attributes (optional).

2. (OIDC only) Expand Configure Just-In-Time (JIT) settings and Custom Claims (optional).

5. Configure Custom Claims

1. (SAML only) Under Custom claims, add the role or group attribute from the SAML assertion.

   The claim name must match the ThousandEyes SAML Role Name Attribute setting.

2. (OIDC only) Under Custom claims, add the role or group claim from the OIDC ID token.

   Configure the claim in the IdP so it is included in the ID token. For group-based mappings, send the group values as an array.

3. Use the same claim name in the IdP, Cisco Identity, and ThousandEyes.

   For example, configure groups consistently in all three locations.

4. Configure profile claims such as name, displayName, or mail if you want Cisco Identity to forward them to ThousandEyes.

Cisco Identity supports a maximum of 25 custom claims. Claim names are case-sensitive. For example, groups and Groups are different claim names.

6. Configure JIT Settings

1. Select Create or activate users. This setting is required. It creates a user when no active user is found or activates an existing inactive user.

2. (SAML only) Select Update user with SAML attributes if you want to update existing users with attributes from the SAML assertion.

3. (OIDC only) Select Update user with OIDC claims if you want to update existing users with claims from the OIDC ID token.

7. Configure Linking, Profile, and Group Attributes

The source attribute and claim names below are examples. Replace them with the names sent by your IdP.

Linking Attribute

The linking attribute uniquely identifies a user so Cisco Identity can update the user’s profile, including the email address.

Map an immutable IdP attribute or OIDC claim to externalId when the user’s email address is not a permanent identifier.

Protocol	Source attribute or claim example	Cisco Identity attribute	Description
SAML	user.objectid	externalId	A unique attribute for identifying a user and updating the user’s profile, including the email address.
OIDC	An immutable claim, such as sub or an IdP-specific user ID	externalId	A stable identifier that remains consistent if the user’s email address changes.

Profile Attributes

Configure only the profile attributes that your IdP sends and that you want Cisco Identity to maintain.

Attribute type	SAML attribute name	SAML Cisco Identity attribute name	OIDC claim name	OIDC Cisco Identity attribute name	Description
Primary identifier	uid	Username/Primary email address	mail or email	uid	The user’s email address, UPN, or other supported primary identifier.
Profile	user.preferredlanguage	preferredLanguage	preferredLanguage	preferredLanguage	The user’s preferred language.
Profile	user.locale	locale	locale	locale	The user’s locale.
Profile	user.timezone	timezone	timezone	timezone	The user’s primary time zone.
Profile	user.displayname	displayName	displayName	displayName	The user’s display name.
Profile	user.givenname	name.givenName	given_name	name.givenName	The user’s first name.
Profile	user.surname	name.familyName	family_name	name.familyName	The user’s last name.
Profile	user.streetaddress	addresses.streetAddress	street_address	addresses.streetAddress;work	The street address of the user’s primary work location.
Profile	user.locality	addresses.locality	locality	addresses.locality;work	The city or locality of the user’s primary work location.
Profile	user.region	addresses.region	region	addresses.region;work	The state or region of the user’s primary work location.
Profile	user.country	addresses.country	country	addresses.country;work	The country of the user’s primary work location.
Profile	user.postalcode	addresses.postalCode	postal_code	addresses.postalCode;work	The postal code of the user’s primary work location.
Profile	work phonenumber	phoneNumbers.work	phone_number	phoneNumbers;work;primary	The user’s work phone number. Use international E.164 format only, with a maximum of 15 digits.
Profile	mobile phonenumber	phoneNumbers.mobile	mobile_phone	phoneNumbers;mobile;primary	The user’s mobile phone number. Use international E.164 format only, with a maximum of 15 digits.
Profile	extension phonenumber	phoneNumbers.extension	phone_extension	phoneNumbers;work_extension;primary	The work extension of the user’s primary work location. Use international E.164 format only, with a maximum of 15 digits.
Profile	user.jobtitle	title	title	title	The user’s job title.
Profile	user.department	department	department	department	The user’s department or team.
Profile	work emails	emails.work	email	emails;work	The user’s work email address.
Profile	user.organization	organization	organization	organization	The user’s organization ID.

If displayName is provided, ThousandEyes uses it. Otherwise, ThousandEyes combines firstName and lastName. If neither is available, it assigns JIT Created User.

Group Attributes

Group attributes are optional. Configure them only when you need to map IdP groups to Cisco Identity groups for licensing or service settings.

These attributes are different from the role or group claim used for ThousandEyes JIT role mappings.

Protocol	Source attribute or claim example	Cisco Identity attribute	Description
SAML	user.groupid	groupId	Maps an IdP group identifier to a Cisco Identity group ID.
SAML	user.groupexternalid	groupExternalId	Maps an IdP external group identifier to a Cisco Identity external group ID.
OIDC	groupId	groupId	Maps an OIDC group identifier to a Cisco Identity group ID.
OIDC	group_external_id	groupExternalId	Maps an OIDC external group identifier to a Cisco Identity external group ID.

8. Save the Identity Provider

1. For a new provider, click Add IdP.

2. For an existing provider, click Save.

9. Configure JIT Role Mappings in ThousandEyes

ThousandEyes uses the screen labeled SAML Just-In-Time Settings for both SAML and OIDC. There is no separate OIDC role-mapping screen.

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 that contains the role or group values.

   For OIDC, select the custom claim name that Cisco Identity sends to ThousandEyes. If the claim name is not listed, select Custom… and enter it manually.

5. In the Role dropdown, select a ThousandEyes role whose name exactly matches the incoming role or group value. If a matching role does not exist, create a custom role with that name under Manage > Account Settings > Users and Roles > Roles before continuing.

6. In the Account Groups dropdown, select the account groups that the role can access.

7. Click + Add mapping to add mappings or click the minus icon to remove them.

8. Include a mapping for a ThousandEyes role with the Edit security & authentication settings permission if admins need access to the Cisco Identity admin portal.

9. Click Save.

10. Test and Activate the Identity Provider

If you added a new IdP or changed the SSO configuration:

1. In Cisco Identity, go to Settings > Manage IdPs.

2. Open the actions menu for the IdP and select Test SSO Setup.

3. Complete the test login.

4. If the test succeeds, select Successful test.

5. Click Activate SSO and IdP.

6. Click Save.

For more information, see Test Your SSO Setup.

11. Test JIT Provisioning

Test with a user assigned to the dedicated IdP group or role.

1. Open the following SP-initiated link in your browser:

   https://app.thousandeyes.com/v2/login?fwd=/account/switch/<AID>

   Replace <AID> with the account group ID.

2. If possible, use a private browser window to avoid cached authentication information.

3. Log in to your IdP when prompted.

4. Confirm that ThousandEyes creates or activates the user.

5. Confirm that the user receives the expected ThousandEyes roles and account-group access.

6. If profile updates are enabled, confirm that the expected profile attributes are updated.

7. If testing an administrator, confirm that the user can access the Cisco Identity admin portal.

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 the IdP and then returns you to ThousandEyes to complete provisioning and login.

Editing or Disabling JIT Settings

Edit JIT Settings

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

2. To change the role attribute, select or enter the new claim or attribute name.

3. If you change the claim name, update the custom claim name in Cisco Identity and the claim name configured in your IdP.

4. To change a role mapping, select a different role from the Role dropdown.

   Create the role under Manage > Account Settings > Users and Roles > Roles before it appears in the dropdown.

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

6. Click Save.

7. Test the change with an SP-initiated login.

Edit the Identity Provider Configuration

1. In Cisco Identity, go to Settings > Manage IdPs.

2. Click ... next to the IdP.

3. Select Edit IdP.

4. Update the protocol settings, custom claims, JIT settings, linking attributes, or profile attributes.

5. Click Save.

6. Test the change with an SP-initiated login.

Disable JIT

To stop using JIT provisioning, switch the Enable toggle off.

Your JIT settings remain saved but inactive. Disabling JIT does not delete existing users or role mappings. Review existing users separately if you want to remove access.

Troubleshooting JIT Provisioning

Protocol	Symptom	Likely cause	What to do
SAML or OIDC	JIT is not active	SSO or JIT is disabled	Confirm that SSO is enabled and that User Provisioning > SAML Just-In-Time Settings > Enable is on.
SAML or OIDC	An IdP application-catalog launch fails	IdP-initiated login is not supported for this workflow	Start from the ThousandEyes login screen or an SP-initiated link.
SAML or OIDC	The user is created without the expected access	No matching role mapping or the mapped role does not allow login	Map the exact role or group value to a ThousandEyes role with login access and the required account groups.
SAML	No roles are found	The IdP did not send the configured SAML attribute or custom claim	Confirm that the SAML assertion contains the configured role attribute and that the attribute name and values match exactly.
OIDC	Custom claims contain name but not the group claim	The group claim is access-token-only or configured on a different authorization server	Configure the group claim in the ID token and configure it on the authorization server identified by the discovery document’s issuer value.
OIDC	The token preview contains claims, but live login does not	The preview uses a different authorization server from the one Cisco account uses	Compare the live token’s iss value with the discovery document’s issuer value. Configure claims, scopes, and policies on that same server.
OIDC	A custom authorization server fails when requesting the groups scope	The scope is not defined or is not allowed by the access policy	Add the groups scope to the authorization server and allow it in the access policy.
SAML or OIDC	The logs show group values, but no role mappings are found	The claim name or capitalization does not match	Use the same claim name and capitalization in the IdP, Cisco Identity, and ThousandEyes. For example, use groups consistently instead of Groups.
SAML or OIDC	A duplicate user is created or the email address is not updated	The linking attribute is missing, unstable, or not mapped to externalId	Map a stable, immutable IdP attribute or OIDC claim to externalId. Confirm that the profile-update option is enabled when profile updates are required.
OIDC	Authentication fails before claims are received	Incorrect issuer, redirect URI, client ID, client secret, or endpoint configuration	Verify the OIDC discovery URL, issuer, redirect URI, client ID, client secret, and endpoint values.
SAML or OIDC	An admin loses Cisco Identity admin portal access	The admin does not receive a mapped ThousandEyes role with the Edit security & authentication settings permission	Have another admin verify that the assigned role has the Edit security & authentication settings permission, update the role mapping if needed, and sign in again through SSO.

If logs show No role mappings found, inspect the custom claims data first. The message often means that no role or group values were received, not that the ThousandEyes mappings are necessarily missing.

For additional help, see Troubleshoot Login Errors.

Learn More

• Configure SSO with Cisco Account — Configure SAML or OIDC authentication in Cisco Identity.

• Test Your SSO Setup — Test the SSO configuration before activating it.

• Configure Routing Rules — Route users to the correct IdP and maintain a break-glass rule.

• Verify Your Domain — Verify domains before creating domain-based routing rules.

• Role-Based Access, Explained — Learn how roles and permissions control access.