Custom mapping
Custom mapping allows you to dynamically assign users to your Snyk Groups and Organizations based on data provided by your Identity Provider (IdP), in order to implement a scaled user provisioning and access model.
Work with your Snyk account team to implement this option.
To understand more about roles and permissions within Snyk, see Pre-defined roles. See also user role management.
Requirements for custom mapping
Complete the SSO information worksheet for the appropriate IdP (identity provider) found in Resources for SSO setup.
Properly configure the custom attributes in your IdP to populate the
roles
array mapping. See Example: roles array mapping.
Custom Mapping options
Snyk offers an updated custom mapping option explained on this page, with increased flexibility, including the ability to grant users Group-level custom roles as well as pre-defined roles.
The Snyk Legacy custom mapping option is still supported.
Roles array mapping with Snyk
In the IdP, you must first pass a custom mapping called roles
as a string array. Examples of how to set this up for different IdPs are provided.
Refer to your identity provider documentation for further information on how to configure custom mappings.
Custom mapping assertions
This section documents the role assertions that Snyk expects in order to map correctly to Snyk roles within Snyk Groups and Organizations.
Role assertion format
Role assertions should be provided to Snyk in the following format:
snyk:{scope}:{target}:{role}
Where:
snyk
is a fixed prefix for role mapping. Required.
scope
can be one of org
or group.
Required; if a role mapping does not contain a valid scope, it will be ignored.
target
must be a slug of either org
or group
where the role will be granted, or a wildcard.
See the Slugs section for details on how to find this information.
Optional; may be an asterisk
*
or empty string::
to apply as a wildcard for all resources within the definedscope
that are associated with the SSO connection.
role
is the normalized name of the required role. See Role normalized name to find this information.
Required; if no role is present, the role mapping is ignored.
If the role is a custom role, that is, a role created in the Group Member Roles admin panel that can be of either
Org
orGroup
type, then it must have acustom:
prefix. See the example role assertions.Built-in roles do not have the
custom:
prefix, so values likeorg_admin
,org_collaborator
,group_viewer
will refer to the Snyk pre-defined roles, which are shown with a padlock symbol in the Member Roles page.
Users must only have one role mapped per Organization or Group. Mapping multiple roles except when using wildcards is not supported and can lead to unexpected behavior.
Any user that is granted a role in an Organization within the SSO without an explicit Group-level role in the role assertion, will also be implicitly assigned the Group Member Group-level role for that Group. This is the pre-defined Group-level role with the fewest permissions and ensures that the user becomes a member of the Group.
Example role assertions
snyk:group:*:group_admin
Assign the user the pre-defined Group Admin role for all groups associated with the SSO connection.snyk:group::custom:sys_admin
Assign the user the custom Group-level roleSys Admin
for all groups associated with the SSO connection.Note that
::
here indicates an empty string for the target, and so is treated as a wildcard in the preceding example.Note that this Group-level custom role must be created manually before it can be assigned.
snyk:org:my-default-org:org_admin
Assign the user the pre-defined Organization Admin Organization-level role for the Organizationmy-default-org
.snyk:org:my-default-org:custom:code_editor
Assign the user the custom Org-level roleCode Editor
for the Organizationmy-default-org
.
Example role assertions array
An example of a set of role assertions for a user follows:
The system also supports comma-separated lists of roles instead of an array.
These assertions will assign the user:
The pre-defined Group-level role Group Viewer for all groups in the SSO. See pre-defined roles for the permission this grants
The pre-defined Organization-level role Organization Admin for the Organization with the name Development.
The custom Organization-level role Developer ReadOnly for the Organization with the name Test Org, which has the slug
test-org-N58YhztauHcaMiNfvi5fbL
.
Wildcards
Custom mapping introduces wildcards, which allow one assertion to assign a user the same role in all Organizations or Groups.
Assertions using wildcards take a lower priority than assertions with a specific target. This means that it is possible, for example, to assign a user a default role for all Organizations, and specific roles in others:
These role assertions will:
Grant the user the pre-defined Organization-level role Organization Admin in the Development Organization.
Grant the user the custom Organization-level role Developer ReadOnly on all other organizations within the SSO connection.
Grant the user the pre-defined Group-level role Group Member on all groups in the SSO connection. For more details, see the note that follows.
Any user that is granted a role in an Organization within the SSO without an explicit Group-level role in the role assertion, will also be implicitly assigned the Group Member Group-level role for that Group. This is the pre-defined Group-level role with the fewest permissions and ensures that the user becomes a member of the Group.
Slugs
For a valid role assertion, the Organization or Group slug may be required, where a wildcard is not used. The slug is the canonical name for the Organization or Group within Snyk.
To find an Organization slug, navigate to the Settings page for the Organization, and under General settings, the Organization slug value is visible. This can then be copied and used in role assertions in custom mapping.
To find the slug of a Group, navigate to the Group Settings, and find the Group slug under General Settings, which you can copy.
Role normalized name
To find the normalized name of a role for use in custom mapping, first confirm that the role exists for the Snyk Group by navigating to it in the Group settings: Group Settings > Member Roles > {Role}.
This will open the role details page that shows which permissions are enabled for the role and also shows the normalized name. Copy this normalized name and use it in custom mapping.
For more details on roles, and specifically, custom roles, see user role management.
Pre-defined role slugs
Snyk has a set of pre-defined roles. Their corresponding normalized names are listed below.
Role Type | Role Name | Role Slug |
---|---|---|
Organization | Org Admin |
|
Organization | Org Collaborator |
|
Group | Group Admin |
|
Group | Group Viewer |
|
Group | Group Member |
|
Last updated