Add guide for migrating from legacy to v2 custom mapping. by brookecastleberry · Pull Request #1612 · snyk/user-docs

brookecastleberry · 2026-08-06T18:18:20Z

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

Note

Low Risk
Documentation-only changes with no application or authentication logic modified.

Overview
Adds a Migrating from legacy to v2 custom mapping doc for SSO role assertions, covering planning/audit, slug extraction, translating dash-delimited legacy strings to snyk:{scope}:{target}:{role}, IdP configuration (including temporary coexistence with legacy claims), and rollout via Snyk Support with pre-prod and production activation. It also includes legacy-to-v2 translation tables for group, organization, and tenant roles and notes that users without valid IdP mappings can lose access after v2 is enabled.

The custom mapping README now points legacy customers to this guide, and SUMMARY.md lists the new page under Custom mapping.

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

snyk-io · 2026-08-06T18:18:37Z

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

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.

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>

brookecastleberry · 2026-08-21T18:01:19Z

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.

cursor

Stale comment

Staff tech writer review

Content is helpful and the syntax translation tables provide clear side-by-side mapping between legacy strings and v2 colon-delimited format.

Requesting several line-level style updates across the migration guide, left as one-click suggestions:

Style fixes (folded into the suggestions)

Replace modal "should" and "may" with definite instructions · replace future tense with present tense · convert bold scaffolding labels (**Note:**, **Best practice:**, **Warning:**) to GitBook hint tags ({% hint %}) · use imperative voice for procedural steps.

_{Sent by Cursor Automation: PR review for User Docs}

cursor

Stale comment

The current head commit cd69009 is reviewed.

_{Sent by Cursor Automation: PR review for User Docs}

cursor

Stale comment

AI review

The technical facts and syntax translation tables hold up. I verified the v2 string mappings against custom-mapping/README.md and confirmed all four internal documentation links return 200.

The documentation is user centric and focuses on the tasks the user must complete. The structure flows logically from discovery and onboarding, through implementation and adoption, to troubleshooting and expansion.

Requesting changes on two structural and style points, plus line-level fixes left as suggestions you can accept in one click.

Structural findings

1. Callout and bolding conventions.

The hint in step 6 uses **Best practice:**, but Snyk callouts do not use bold lead-ins for general statements of advice, and bold is reserved for UI elements, CLI/IDE elements, and status values. Step 2 also bolds list lead-in labels (**Org slugs**:, **Group slugs**:, **Role names**:), which diverges from Snyk style conventions.

2. Snyk style and terminology compliance.

The text contains a contraction ("it's" on line 99), an unspaced em dash (line 34), passive phrasing ("It is recommended to"), and lowercase Snyk-defined nouns.

Style fixes (folded into the suggestions)

Remove contraction: "it is no longer needed" instead of "it's no longer needed".

Use spaced em dashes instead of unspaced em dashes.

Use "Snyk recommends" instead of passive "It is recommended to".

Capitalize Snyk-defined nouns: Organization and Group.

Remove bolding from list lead-in labels in step 2 and the hint in step 6.

Use "visit" instead of "see" for referencing documentation pages.

_{Sent by Cursor Automation: PR review for User Docs}

cursor · 2026-09-02T04:07:08Z

+* **Org slugs**: Found in **Organization Settings** > **General**.
+* **Group slugs**: Found in **Group Settings** > **General**.
+* **Role names**: Found in **Group Settings** > **Member Roles** (for example, `developer_readonly`).
+
+For more details, see [Slugs](README.md#slugs) and [Role normalized name](README.md#role-normalized-name).


Remove bolding from list lead-in labels, capitalize Organization and Group, and use visit for page references. (Snyk style guide)

Bold is reserved for UI elements, CLI/IDE elements, and status values, not list lead-in labels. Capitalize Organization and Group as Snyk-defined nouns, and use "visit" instead of "see" for page links.

Suggested change

* **Org slugs**: Found in **Organization Settings** > **General**.

* **Group slugs**: Found in **Group Settings** > **General**.

* **Role names**: Found in **Group Settings** > **Member Roles** (for example, `developer_readonly`).

For more details, see [Slugs](README.md#slugs) and [Role normalized name](README.md#role-normalized-name).

* Org slugs: Found in **Organization Settings** > **General**.

* Group slugs: Found in **Group Settings** > **General**.

* Role names: Found in **Group Settings** > **Member Roles** (for example, `developer_readonly`).

For more details, visit [Slugs](README.md#slugs) and [Role normalized name](README.md#role-normalized-name).

cursor

Stale comment

The current head commit cc6eb72 is reviewed.

_{Sent by Cursor Automation: PR review for User Docs}

Squashed from 22 commits to produce verified signatures; file contents are byte-identical to the previously reviewed branch state. Co-authored-by: Brooke Castleberry <brooke.castleberry@snyk.io> Co-authored-by: VeronicaSnyk <136595978+VeronicaSnyk@users.noreply.github.com>

cursor

AI review

The technical facts and syntax translation tables hold up. I verified the v2 string mappings against custom-mapping/README.md and confirmed all four internal documentation links return 200.

The documentation is user centric and focuses on the tasks the user must complete. The structure flows from discovery and onboarding, through implementation and adoption, to troubleshooting and expansion.

Requesting changes on three style and voice points, left as one-click suggestions. Note that PR #1799 supersedes this PR with these fixes incorporated.

Style fixes (folded into the suggestions)

Use "visit" instead of "see" for documentation links · line 48
Use present tense and name Snyk as the actor ("Snyk updates") instead of future passive ("will be updated") · line 83
Use active voice with Snyk as the actor ("Snyk assigns roles automatically") instead of agentless passive · line 86

Open questions

⚠️ Step 1 vs Step 5 ordering: Step 1 states that you must ensure all users have role mappings configured before activation, but Step 5 directs setting up a few role mappings for pre-production validation before completing the rest. Confirm the intended rollout sequence.
⚠️ Step 6 callout content: Confirm whether additional guidance belongs in the step 6 hint alongside connection update behavior.

_{Sent by Cursor Automation: PR review for User Docs}

cursor · 2026-09-16T04:09:57Z

+* Group slug: navigate to **Group Settings** > **General**.
+* Role name: navigate to **Group Settings** > **Member Roles** (for example, `developer_readonly`).
+
+For more details, see [Slugs](README.md#slugs) and [Role normalized name](README.md#role-normalized-name).


Use "visit" rather than "see" when linking to documentation pages. (Snyk writing rule: "Visit," not "see" for referring to a page)

Snyk style guidelines reserve "see" for cross-references within the same page and require "visit" when linking to another page or section.

Suggested change

For more details, see [Slugs](README.md#slugs) and [Role normalized name](README.md#role-normalized-name).

For more details, visit [Slugs](README.md#slugs) and [Role normalized name](README.md#role-normalized-name).

cursor · 2026-09-16T04:09:57Z

+After validation is complete, Snyk Support enables v2 custom mapping in your production environment.
+
+{% hint style="info" %}
+The existing SSO connection will be updated to use v2 custom role mapping.


Use present tense and name Snyk as the actor. (Snyk writing rule: active voice, present tense)

Replace future passive "will be updated" with present active "Snyk updates".

Suggested change

The existing SSO connection will be updated to use v2 custom role mapping.

Snyk updates the existing SSO connection to use v2 custom role mapping.

cursor · 2026-09-16T04:09:57Z

+The existing SSO connection will be updated to use v2 custom role mapping.
+{% endhint %}
+
+Roles are automatically assigned upon the next user login.


Use active voice with Snyk as the actor. (Snyk writing rule: active voice, present tense)

Replace agentless passive "Roles are automatically assigned upon the next user login" with active voice naming Snyk.

Suggested change

Roles are automatically assigned upon the next user login.

Snyk assigns roles automatically the next time each user logs in.

cursor

The current head commit 1ef7dd1 is reviewed.

_{Sent by Cursor Automation: PR review for User Docs}

VeronicaSnyk · 2026-09-16T10:18:43Z

replicated in PR1799

@VeronicaSnyk

Rebased onto current main and applied the remaining unresolved review suggestions from @VeronicaSnyk and @cursor: - "see" -> "visit" for page references - present tense for "will be updated" - name the actor rather than passive "roles are assigned" Supersedes snyk#1612. Co-authored-by: Brooke Castleberry <brooke.castleberry@snyk.io> Co-authored-by: VeronicaSnyk <136595978+VeronicaSnyk@users.noreply.github.com>

brookecastleberry requested a review from a team as a code owner August 6, 2026 18:18

VeronicaSnyk reviewed Aug 11, 2026

View reviewed changes

esabou-snyk mentioned this pull request Aug 13, 2026

fix(cli): remove snyk-cli/snyk-cli double-nested GitBook links (84 files) #1642

Merged

2 tasks

cursor Bot reviewed Aug 31, 2026

View reviewed changes

cursor Bot reviewed Sep 2, 2026

View reviewed changes

VeronicaSnyk approved these changes Sep 15, 2026

View reviewed changes

VeronicaSnyk closed this Sep 15, 2026

VeronicaSnyk force-pushed the docs/custom-mapping-migration branch from 0d31df4 to 1428a4f Compare September 15, 2026 07:18

VeronicaSnyk reopened this Sep 15, 2026

VeronicaSnyk force-pushed the docs/custom-mapping-migration branch from 0d31df4 to 1ef7dd1 Compare September 15, 2026 07:34

VeronicaSnyk mentioned this pull request Sep 15, 2026

Add guide for migrating from legacy to v2 custom mapping. #1799

Merged

cursor Bot reviewed Sep 16, 2026

View reviewed changes

VeronicaSnyk closed this Sep 16, 2026

	For more details, see [Slugs](README.md#slugs) and [Role normalized name](README.md#role-normalized-name).
	For more details, visit [Slugs](README.md#slugs) and [Role normalized name](README.md#role-normalized-name).

	The existing SSO connection will be updated to use v2 custom role mapping.
	Snyk updates the existing SSO connection to use v2 custom role mapping.

	Roles are automatically assigned upon the next user login.
	Snyk assigns roles automatically the next time each user logs in.

Conversation

brookecastleberry commented Aug 6, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

snyk-io Bot commented Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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

Uh oh!

VeronicaSnyk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

brookecastleberry commented Aug 21, 2026

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Staff tech writer review

Style fixes (folded into the suggestions)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

AI review

Structural findings

Style fixes (folded into the suggestions)

Uh oh!

Uh oh!

cursor Bot Sep 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

AI review

Style fixes (folded into the suggestions)

Open questions

Uh oh!

cursor Bot Sep 16, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Sep 16, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Sep 16, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

VeronicaSnyk commented Sep 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

brookecastleberry commented Aug 6, 2026 •

edited by cursor Bot

Loading

snyk-io Bot commented Aug 6, 2026 •

edited

Loading

cursor Bot left a comment •

edited

Loading

cursor Bot left a comment •

edited

Loading

cursor Bot left a comment •

edited

Loading

cursor Bot left a comment •

edited

Loading