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

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 defined scope 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 or Group type, then it must have a custom: prefix. See the example role assertions.

  • Built-in roles do not have the custom: prefix, so values like org_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 role Sys 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 Organization my-default-org.

  • snyk:org:my-default-org:custom:code_editor Assign the user the custom Org-level role Code Editor for the Organization my-default-org .

Example role assertions array

An example of a set of role assertions for a user follows:

{
    "roles": [
        "snyk:group:*:group_viewer",
        "snyk:org:development:org_admin",
        "snyk:org:test-org-N58YhztauHcaMiNfvi5fbL:custom:developer_readonly",
    ]
}

The system also supports comma-separated lists of roles instead of an array.

{
  "roles": "snyk:group:*:group_viewer, snyk:org:development:org_admin, 
snyk:org:test-org-N58YhztauHcaMiNfvi5fbL:custom:developer_readonly"
}

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:

roles: [
        "snyk:org:*:custom:developer_readonly",
        "snyk:org:development:org_admin",
    ]

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 TypeRole NameRole Slug

Organization

Org Admin

org_admin

Organization

Org Collaborator

org_collaborator

Group

Group Admin

group_admin

Group

Group Viewer

group_viewer

Group

Group Member

group_member

Last updated

More information

Snyk privacy policy

© 2024 Snyk Limited | All product and company names and logos are trademarks of their respective owners.