Add guide for migrating from legacy to v2 custom mapping.

[brookecastleberry]

Documents the legacy custom mapping to v2 custom mapping migration process.

---

Note

Low Risk
Documentation-only change with no code, security, or data handling impact.

Overview
Adds a new documentation guide that walks customers through migrating their SSO custom role mapping from the legacy dash-delimited format to the v2 colon-delimited snyk:{scope}:{target}:{role} syntax.

The guide covers planning, extracting slugs, configuring the IdP, testing with Snyk Support, production activation, and cleanup. It also adds side-by-side translation tables for Group, Organization, and Tenant-level roles.

The new page is linked from the custom mapping README and added to the platform administration SUMMARY.

^{Reviewed by Cursor Bugbot for commit cd69009. Bugbot is set up for automated code reviews on this repo. Configure here.}

[snyk-io]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[VeronicaSnyk]

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.md entry, 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:

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

[VeronicaSnyk]

Structure — worth addressing before the line edits. Two issues:

1. "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.
2. 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.

[brookecastleberry]

Comment: 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

Answers:

• I updated some of the text in step 5 to make it more clear, but all role claims should be set up prior to full activation (step 6). Step 5 is initially a test of a small number of role claims (no activation needed - Snyk will check in Auth0). Then the suggestion is after validation to finish role claim set up prior to step 6 (full activation).
• Legacy Custom Mapping did not support group-level custom roles: https://docs.snyk.io/platform-administration/user-management/single-sign-on-sso-for-authentication-to-snyk/custom-mapping/legacy-custom-mapping
• for step 6 - this isn't necessarily a fact but the Best Practice that teams should follow. They could instead create a new SSO connection to do this migration/activation but that's not what we're recommending.