IdP Role Mapping
You can set up Instana to automatically provision users to the Instana role (and optionally to team) based on the attributes they have within your Identity Provider (IdP).
This setup reduces your user management workload significantly. In Instana, you can use manual user and role management capabilities, even if you have a working IdP mapping configuration. However, you can migrate to role assignments based on IdP mapping rules to centralize your user and group management within your IdP.
For more information about enabling IdP mapping rules with traditional role-based access control, see Implementation details.
Prerequisites
To make role mapping work, complete the following prerequisites:
- Configure Instana to delegate authentication to your identity provider: SAML, OIDC, or LDAP. If you delegate authentication to your IdP, you must know your users' assertion claim, such as SAML. Successful role mapping depends on entering the correct assertion keys and values. Use either built-in browser tools or browser extensions to view an assertion.
- Create the Instana role that you want to map. For more information about creating Instana roles, see Create role.
Mapping rules
A mapping rule defines which assertion attribute (key and value) gets mapped to which Instana role. You can use the same assertion attribute for multiple Instana roles. For role mapping, identify the correct assertion attributes that you want to map to existing Instana roles.
Some of the OIDC and SAML IdPs can be configured to provide a list of values as attributes in the user profiles. If the key is a list in the user profile, the rule will match if one of the list items is identical to the value. If the rule matches, the user is added to the configured role.
- If the “Deny access when no mapping found” checkbox is selected, the user must be part of a role to sign in to Instana.
- If the “Deny access when no mapping found” checkbox is not selected, the user will be added to the default role and provisioned.
A mapping rule consists of a key, a value, and an Instana role. The key and value refer to the assertion attribute and its value that you map from. The key and value must be in the context of the results of any of the following user data:
- OIDC profile
- SAML profile
- LDAP user query
For example:
-
SAML: You want to map every user that has the value "SRE" in the "Department" attribute in your SAML identity provider to the Instana "Owner" role.
Key Value Role Department SRE Owner - SAML with ADFS: You want to map every user that has the value "instana-admins" in the "Group" attribute sent by Active Directory Federation Services (ADFS) to the Instana "Administrators" Group.
Key Value Role Group instana-admins Administrators For detailed instructions on configuring ADFS to send group membership as SAML claims, see Create a Rule to Send Group Membership as a Claim (step-by-step guide for sending AD group membership as SAML claims) and Create a Rule to Send LDAP Attributes as Claims (alternative approach for scenarios with complex attribute-mapping requirements).
-
LDAP: You want to map every user from the role with "memberOf: CN=administrators,CN=Groups,CN=SVT,OU=APMDir,DC=ibm,DC=com" in your LDAP identity provider to the Instana "adminsDK" role.
Key Value Role memberOf CN=administrators,CN=Groups,CN=SVT,OU=APMDir,DC=ibm,DC=com adminsDK
dn: cn=myteam,c=de,ou=myorgunit,o=mycoor.org then for mapping, the key is dn and the value is cn=myteam,c=de,ou=myorgunit,o=mycoor.org.Deny access
If you select the checkbox in the Role Mapping pane, then your Instana instance is locked to prevent unmapped access. Access is allowed only for users who have at least one working mapping rule that is applied to them when they log in.
Configure mapping rules for your administrators, and successfully validate that they can log in, before you select the checkbox.
Implementation details
Roles that are assigned by your configured mapping rules are treated slightly different from the usual role assignment. The core difference is that users lose the role assignments that do not apply any more during future logins. Having both IdP mapping rules and traditional Instana role-based access control enabled, works under certain rules that then apply:
-
If the checkbox to deny access is not selected, users with no mapping rules are put into the Instana role "Default". If those same users are already in the "Default" role, the assignment is changed to an IdP role assignment. IdP role assignment means that the user can lose the Instana "Default" role assignment during future logins if the mapping is edited or does not apply anymore.
-
After you select the checkbox to deny access, users with no applicable mapping rules are not be able to log in. Even users with existing Instana role-based role assignments are locked out. Configure mapping rules for your administrators, and successfully validate that they can log in, before you select the checkbox.