Add guide for migrating from legacy to v2 custom mapping. - #1612
Open
brookecastleberry wants to merge 2 commits into
Open
Add guide for migrating from legacy to v2 custom mapping.#1612brookecastleberry wants to merge 2 commits into
brookecastleberry wants to merge 2 commits into
Conversation
Documents the IdP migration process and syntax translation reference for SSO custom role mapping. Co-authored-by: Cursor <cursoragent@cursor.com>
✅ Snyk checks have passed. No issues have been found so far.
💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse. |
Avoids raw hint syntax rendering issues in the published docs. Co-authored-by: Cursor <cursoragent@cursor.com>
VeronicaSnyk
left a comment
VeronicaSnyk
left a comment
Collaborator
There was a problem hiding this comment.
Reviewed against the Snyk docs writing rules. Useful page and the syntax translation tables are the strongest part — they will save administrators a lot of guesswork. The comments below are mostly a consistent set of four style patterns rather than one-off errors:
- Modals — "may", "should", "might" appear seven times. Replace with definite statements, "must", or "can". The one in the access-loss warning matters most: if users without a valid mapping lose access, say so definitively.
- Future tense and agentless passives — "will validate", "will be updated", "roles are automatically assigned". Name Snyk or the user as the actor and use present tense.
- Bold scaffolding labels —
**Note:**,**Warning:**,**Best practice:**, and bolded list lead-ins. Bold is reserved for UI elements and status values; the parent README already uses{% hint %}for these asides, so this page should match. - Sentence case — the title, the
SUMMARY.mdentry, and the README link text all use title case.
Two things worth resolving before the line edits, since they affect the shape of the page:
- Naming. The page cycles through "v2 custom mapping", "the new format", "updated custom mapping", and "New custom mapping format" as a column header. More importantly, "v2" does not appear anywhere on the canonical README, which calls it the "updated custom mapping option". Pick one term and make the README agree.
- Step structure. Seven manual
### Step N:headings split across two H2s ("Migration IdP configuration process" / "Implementation and rollout") for what is one sequence. Use{% stepper %}/{% step %}under a single H2, and lead with an anchor-linked roadmap of the phases per the implementation-guide template.
Three content questions for the SSO team, flagged inline: Step 1 and Step 5 disagree on whether all mappings or only a few are configured before activation; **Best practice:** in Step 6 labels a statement of fact, so something may have been dropped there; and please confirm Group-level custom roles genuinely had no legacy equivalent.
One process note: if this is not already covered by a /ship-it request from Slack, please create one so the change is tracked through the usual review and release flow.
| nav_context: classic | ||
| --- | ||
|
|
||
| # Migrating from Legacy to v2 Custom Mapping |
Collaborator
There was a problem hiding this comment.
Sentence case. Headings and titles use sentence-style capitalization — only the first word, proper nouns, and Snyk product/feature names are capitalized.
Suggested change
| # Migrating from Legacy to v2 Custom Mapping | |
| # Migrating from legacy to v2 custom mapping |
Same change needed in the SUMMARY.md entry and the README link text so all three match.
Comment on lines
+8
to
+10
| Snyk's Single Sign-On (SSO) custom mapping empowers administrators to dynamically provision users into Snyk Groups and Organizations based on attributes passed from their Identity Provider (IdP). | ||
|
|
||
| If your organization is still using the legacy format, migrating to the updated custom mapping provides a standardized syntax, wildcard support, and streamlined assignments for custom roles. |
Collaborator
There was a problem hiding this comment.
Three style rules in the opening two sentences:
- Brand possessive — avoid the possessive of the company name ("Snyk's").
- "empowers administrators to…" — this is the banned "enables users to" construction. Rewrite as a direct statement of what Snyk does, or as "you can…".
- Generic "organization" — Organization is a Snyk-defined noun, so use "company" for the generic sense to avoid ambiguity.
Suggested change
| Snyk's Single Sign-On (SSO) custom mapping empowers administrators to dynamically provision users into Snyk Groups and Organizations based on attributes passed from their Identity Provider (IdP). | |
| If your organization is still using the legacy format, migrating to the updated custom mapping provides a standardized syntax, wildcard support, and streamlined assignments for custom roles. | |
| Single Sign-On (SSO) custom mapping dynamically provisions users into Snyk Groups and Organizations based on attributes passed from your Identity Provider (IdP). | |
| If your company still uses the legacy format, the updated custom mapping gives you a standardized syntax, wildcard support, and streamlined assignments for custom roles. |
|
|
||
| If your organization is still using the legacy format, migrating to the updated custom mapping provides a standardized syntax, wildcard support, and streamlined assignments for custom roles. | ||
|
|
||
| For details on the legacy and v2 formats, see [Legacy custom mapping](legacy-custom-mapping.md) and [Custom mapping](README.md). |
Collaborator
There was a problem hiding this comment.
"Visit," not "see" when pointing the reader at another page — it reads better with screen readers.
Suggested change
| For details on the legacy and v2 formats, see [Legacy custom mapping](legacy-custom-mapping.md) and [Custom mapping](README.md). | |
| For details on the legacy and v2 formats, visit [Legacy custom mapping](legacy-custom-mapping.md) and [Custom mapping](README.md). |
Applies to the other instances on this page too (lines 46, 73). Flagging that the surrounding SSO pages all use "see", so you may prefer to make this a repo-wide sweep rather than fixing it only here.
Comment on lines
+14
to
+24
| ## Why migrate? | ||
|
|
||
| The new format uses a highly extensible, colon-delimited string syntax: | ||
|
|
||
| `snyk:{scope}:{target}:{role}` | ||
|
|
||
| ### Key benefits | ||
|
|
||
| * Support for multiple Groups | ||
| * Claims-based provisioning and deprovisioning access | ||
| * Support for Tenant-level roles |
Collaborator
There was a problem hiding this comment.
Two things in this block:
Question heading. Question-style headings are the implementation-guide decision device and belong immediately before a set of branching options. There is no decision here, so use a keyword heading — and fold the H3 into it rather than nesting a heading that only holds a three-item list.
Grammar on line 23: "deprovisioning access" is missing a preposition.
Suggested change
| ## Why migrate? | |
| The new format uses a highly extensible, colon-delimited string syntax: | |
| `snyk:{scope}:{target}:{role}` | |
| ### Key benefits | |
| * Support for multiple Groups | |
| * Claims-based provisioning and deprovisioning access | |
| * Support for Tenant-level roles | |
| ## Benefits of v2 custom mapping | |
| The v2 format uses an extensible, colon-delimited string syntax: | |
| `snyk:{scope}:{target}:{role}` | |
| This gives you: | |
| * Support for multiple Groups | |
| * Claims-based provisioning and deprovisioning of access | |
| * Support for Tenant-level roles |
Also dropped "highly" from "highly extensible" — subjective intensifier.
Comment on lines
+26
to
+28
| ## Migration IdP configuration process | ||
|
|
||
| ### Step 1: Plan and audit |
Collaborator
There was a problem hiding this comment.
Structure — worth addressing before the line edits. Two issues:
- "Migration IdP configuration process" is hard to parse (three nouns stacked). And the split between this H2 (Steps 1–4) and "Implementation and rollout" (Steps 5–7) is arbitrary — it is one sequence, and the second H2 heading does not tell a scanning reader anything the steps do not.
- Manual
### Step N:headings duplicate numbering GitBook can render natively. Use{% stepper %}/{% step %}for the whole sequence under one H2 ("Migration process").
Per the implementation-guide template, also add a short anchor-linked roadmap right after the intro — "As you work through this page, you will:" followed by the seven phases — so administrators can see the scope of the migration before starting.
Comment on lines
+99
to
+108
| Legacy format relied on strict strings or Group IDs. The new format targets the group scope and uses wildcards or Group slugs. | ||
|
|
||
| | Goal | Legacy format | New custom mapping format | | ||
| | ---- | ------------- | ------------------------- | | ||
| | Group Admin (all Groups in SSO) | `snyk-groupadmin` | `snyk:group:*:group_admin` | | ||
| | Group Viewer (all Groups in SSO) | `snyk-groupviewer` | `snyk:group:*:group_viewer` | | ||
| | Org Collaborator (across all Orgs in a specific Group) | `snyk-{groupID}` | Use wildcards: `snyk:org:*:org_collaborator` | | ||
| | Custom Group role | N/A (new in v2) | `snyk:group::custom:{custom_role}` | | ||
|
|
||
| **Note:** The v2 format replaces Group ID logic with explicit Organization-level wildcards. |
Collaborator
There was a problem hiding this comment.
The tables are the strongest part of this page. Four fixes:
- Missing article — "Legacy format relied on" → "The legacy format relied on" (also on line 112).
- Table parallelism — the "Org Collaborator (across all Orgs in a specific Group)" row puts prose ("Use wildcards:") in a value cell, and it is an Org-scope mapping sitting in the Group-level table. Move it to the Organization-level table.
**Note:**→{% hint style="info" %}.- Column header — "New custom mapping format" should match whatever term the page settles on (see my top-level comment about v2 naming).
Suggested change
| Legacy format relied on strict strings or Group IDs. The new format targets the group scope and uses wildcards or Group slugs. | |
| | Goal | Legacy format | New custom mapping format | | |
| | ---- | ------------- | ------------------------- | | |
| | Group Admin (all Groups in SSO) | `snyk-groupadmin` | `snyk:group:*:group_admin` | | |
| | Group Viewer (all Groups in SSO) | `snyk-groupviewer` | `snyk:group:*:group_viewer` | | |
| | Org Collaborator (across all Orgs in a specific Group) | `snyk-{groupID}` | Use wildcards: `snyk:org:*:org_collaborator` | | |
| | Custom Group role | N/A (new in v2) | `snyk:group::custom:{custom_role}` | | |
| **Note:** The v2 format replaces Group ID logic with explicit Organization-level wildcards. | |
| The legacy format relied on strict strings or Group IDs. The v2 format targets the group scope and uses wildcards or Group slugs. | |
| | Goal | Legacy format | v2 format | | |
| | ---- | ------------- | --------- | | |
| | Group Admin (all Groups in SSO) | `snyk-groupadmin` | `snyk:group:*:group_admin` | | |
| | Group Viewer (all Groups in SSO) | `snyk-groupviewer` | `snyk:group:*:group_viewer` | | |
| | Custom Group role | Not available | `snyk:group::custom:{custom_role}` | | |
| {% hint style="info" %} | |
| The v2 format replaces Group ID logic with explicit Organization-level wildcards. | |
| {% endhint %} |
Also swapped "N/A (new in v2)" for "Not available" — clearer for a global audience.
Content question: can you confirm with the SSO team that Group-level custom roles genuinely had no legacy equivalent, rather than an undocumented one?
Comment on lines
+112
to
+118
| Legacy format used dashes, which made parsing custom roles difficult if the role or Organization name contained dashes. The new format uses a strict `snyk:org:{slug}:{role}` structure. | ||
|
|
||
| | Goal | Legacy format | New custom mapping format | | ||
| | ---- | ------------- | ------------------------- | | ||
| | Org Admin | `snyk-{orgslug}-admin` | `snyk:org:{orgslug}:org_admin` | | ||
| | Org Collaborator | `snyk-{orgslug}-collaborator` | `snyk:org:{orgslug}:org_collaborator` | | ||
| | Custom role | `snyk-{orgslug}-{custom_role}` | `snyk:org:{orgslug}:custom:{custom_role}` | |
Collaborator
There was a problem hiding this comment.
Missing article, and this is where the Org Collaborator wildcard row from the Group-level table belongs. Also {orgslug} should match the README, which uses {slug}.
Suggested change
| Legacy format used dashes, which made parsing custom roles difficult if the role or Organization name contained dashes. The new format uses a strict `snyk:org:{slug}:{role}` structure. | |
| | Goal | Legacy format | New custom mapping format | | |
| | ---- | ------------- | ------------------------- | | |
| | Org Admin | `snyk-{orgslug}-admin` | `snyk:org:{orgslug}:org_admin` | | |
| | Org Collaborator | `snyk-{orgslug}-collaborator` | `snyk:org:{orgslug}:org_collaborator` | | |
| | Custom role | `snyk-{orgslug}-{custom_role}` | `snyk:org:{orgslug}:custom:{custom_role}` | | |
| The legacy format used dashes, which made custom roles hard to parse when the role or Organization name itself contained a dash. The v2 format uses a strict `snyk:org:{slug}:{role}` structure. | |
| | Goal | Legacy format | v2 format | | |
| | ---- | ------------- | --------- | | |
| | Org Admin | `snyk-{slug}-admin` | `snyk:org:{slug}:org_admin` | | |
| | Org Collaborator | `snyk-{slug}-collaborator` | `snyk:org:{slug}:org_collaborator` | | |
| | Org Collaborator across all Orgs in a Group | `snyk-{groupID}` | `snyk:org:*:org_collaborator` | | |
| | Custom role | `snyk-{slug}-{custom_role}` | `snyk:org:{slug}:custom:{custom_role}` | |
Comment on lines
+122
to
+129
| The new format introduces the tenant scope and uses an empty string `::` for the target, as an SSO connection is linked to a single Tenant. | ||
|
|
||
| | Goal | Legacy format | New custom mapping format | | ||
| | ---- | ------------- | ------------------------- | | ||
| | Tenant Admin | `snyk-tenantadmin` | `snyk:tenant::tenant_admin` | | ||
| | Tenant Viewer | `snyk-tenantviewer` | `snyk:tenant::tenant_viewer` | | ||
| | Tenant Member | `snyk-tenantmember` | `snyk:tenant::tenant_member` | | ||
| | Custom Tenant role | N/A (new in v2) | `snyk:tenant::custom:{custom_role}` | |
Collaborator
There was a problem hiding this comment.
Minor consistency pass on the last table: Tenant capitalized in prose (Snyk-defined noun, and it is capitalized everywhere else on this page), plus "because" rather than "as" for causation, and the same "Not available" change.
Suggested change
| The new format introduces the tenant scope and uses an empty string `::` for the target, as an SSO connection is linked to a single Tenant. | |
| | Goal | Legacy format | New custom mapping format | | |
| | ---- | ------------- | ------------------------- | | |
| | Tenant Admin | `snyk-tenantadmin` | `snyk:tenant::tenant_admin` | | |
| | Tenant Viewer | `snyk-tenantviewer` | `snyk:tenant::tenant_viewer` | | |
| | Tenant Member | `snyk-tenantmember` | `snyk:tenant::tenant_member` | | |
| | Custom Tenant role | N/A (new in v2) | `snyk:tenant::custom:{custom_role}` | | |
| The v2 format introduces the tenant scope and uses an empty string `::` for the target, because an SSO connection is linked to a single Tenant. | |
| | Goal | Legacy format | v2 format | | |
| | ---- | ------------- | --------- | | |
| | Tenant Admin | `snyk-tenantadmin` | `snyk:tenant::tenant_admin` | | |
| | Tenant Viewer | `snyk-tenantviewer` | `snyk:tenant::tenant_viewer` | | |
| | Tenant Member | `snyk-tenantmember` | `snyk:tenant::tenant_member` | | |
| | Custom Tenant role | Not available | `snyk:tenant::custom:{custom_role}` | |
Note tenant stays lowercase where it refers to the literal scope value in the syntax.
| * [Example: setting up custom mapping for Google Workspace](implementation-and-setup/enterprise-setup/single-sign-on-sso-for-authentication-to-snyk/custom-mapping/examples-setting-up-custom-mapping-for-idps/example-setting-up-custom-mapping-for-google-workspace.md) | ||
| * [Example: setting up custom mapping for an Okta OIDC app](implementation-and-setup/enterprise-setup/single-sign-on-sso-for-authentication-to-snyk/custom-mapping/examples-setting-up-custom-mapping-for-idps/example-setting-up-custom-mapping-for-an-okta-oidc-app.md) | ||
| * [Example: setting up custom mapping for OneLogin](implementation-and-setup/enterprise-setup/single-sign-on-sso-for-authentication-to-snyk/custom-mapping/examples-setting-up-custom-mapping-for-idps/example-setting-up-custom-mapping-for-onelogin.md) | ||
| * [Migrating from Legacy to v2 Custom Mapping](implementation-and-setup/enterprise-setup/single-sign-on-sso-for-authentication-to-snyk/custom-mapping/migrating-from-legacy-to-v2-custom-mapping.md) |
Collaborator
There was a problem hiding this comment.
Sentence case — and note every sibling entry in this section already follows it ("Example: setting up custom mapping for OneLogin").
Suggested change
| * [Migrating from Legacy to v2 Custom Mapping](implementation-and-setup/enterprise-setup/single-sign-on-sso-for-authentication-to-snyk/custom-mapping/migrating-from-legacy-to-v2-custom-mapping.md) | |
| * [Migrating from legacy to v2 custom mapping](implementation-and-setup/enterprise-setup/single-sign-on-sso-for-authentication-to-snyk/custom-mapping/migrating-from-legacy-to-v2-custom-mapping.md) |
|
|
||
| Snyk offers an updated custom mapping option explained on this page, with increased flexibility, including the ability to grant users Group-level and Tenant-level custom roles, in addition to pre-defined roles. | ||
|
|
||
| If you are currently using the legacy format, see [Migrating from Legacy to v2 Custom Mapping](migrating-from-legacy-to-v2-custom-mapping.md). |
Collaborator
There was a problem hiding this comment.
Sentence case in the link text, "visit" rather than "see", and "currently" is a vague time word the guide asks us to cut.
Suggested change
| If you are currently using the legacy format, see [Migrating from Legacy to v2 Custom Mapping](migrating-from-legacy-to-v2-custom-mapping.md). | |
| If you use the legacy format, visit [Migrating from legacy to v2 custom mapping](migrating-from-legacy-to-v2-custom-mapping.md). |
Also: this page never uses the term "v2" — it calls the new format the "updated custom mapping option". Introducing "v2" only in the link text means readers meet the term for the first time as a destination they have no context for. Either define v2 here in the "Custom mapping options" section, or align the new page to this page's existing wording.
2 tasks
pull Bot
pushed a commit
to Jason-123-cyber/user-docs
that referenced
this pull request
Aug 13, 2026
Fixes 155 cross-space GitBook links of the form app.gitbook.com/s/IEEjSXQQu36y0vmFV8zf/snyk-cli/snyk-cli/... which produced the broken public URL https://docs.snyk.io/developer-tools/snyk-cli/snyk-cli/... Root cause: a GitBook Git Sync commit from June 2026 generated cross-space href attributes with an extra snyk-cli/ path segment. Prior fix PRs (snyk#1609, snyk#1611, snyk#1612) cleaned up docs.snyk.io-format URLs but left the app.gitbook.com/s/... internal links untouched. This pass catches all remaining instances across 84 files in agent-security, discover-snyk, platform-administration, scan-fix-and-prevent, and snyk-data-and-governance. Excludes discover-snyk/whats-new.md (auto-generated). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documents the legacy custom mapping to v2 custom mapping migration process.
Note
Low Risk
Documentation-only changes with no runtime or security logic; risk is limited to doc accuracy for customer SSO migrations.
Overview
Adds a new Migrating from Legacy to v2 Custom Mapping doc that walks administrators through moving SSO role assertions from dash-delimited legacy strings to the
snyk:{scope}:{target}:{role}format.The guide covers planning and IdP audit, extracting org/group slugs and role names, translating mappings (with coexistence of legacy and v2 during rollout), support-driven pre-prod and prod activation, and post-migration validation and IdP cleanup. It includes syntax translation tables for group-, org-, and tenant-level roles (including wildcards and custom roles).
SUMMARY.md and the custom mapping README now link to the new page so legacy users can find the migration path alongside existing legacy and v2 references.
Reviewed by Cursor Bugbot for commit a8ad76c. Bugbot is set up for automated code reviews on this repo. Configure here.