docs: expand Okta SCIM setup with custom attribute/claim mapping steps, profile editor screenshots, and clarified token claim guidance#4214
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughGeneralizes Okta Step 4 into "Add Claims to Tokens" (Custom vs Org server guidance), explains exposing profile attributes as token claims, notes SCIM push can omit the Okta API token, adds SCIM custom-attribute mapping instructions, and removes a Per-User OAuth version note. ChangesOkta Integration Documentation
Per-User OAuth documentation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
This stack of pull requests is managed by Graphite. Learn more about stacking. |
BearTS
changed the title
BearTS
force-pushed
the
06-09-docs_update_for_custom_attributes
branch
from
c95654c to
2a176ab
Compare
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/enterprise/setting-up-okta.mdx`:
- Around line 407-409: The Note is misleading: change it to explain that Bifrost
mapping is keyed by the JWT claim fields (attribute) and matching
value/attributeValue (and attributeType/attributeValue for team/business-unit
mappings), not the SCIM external_name; update the text to instruct readers to
configure the mapping’s attribute, attributeValue (and attributeType when
applicable) to match the OIDC claim name/value so a single Bifrost rule can
apply to both OIDC login and SCIM push, and remove the claim that matching SCIM
external_name alone avoids setting attributeValue.
- Around line 364-391: The "Map custom attributes to SCIM" section currently
instructs adding SCIM attributes but doesn't reflect Bifrost's provisioning
model; update the subsection titled "Map custom attributes to SCIM (for SCIM
attribute-based mappings)" to (1) explicitly state that Bifrost does NOT support
inbound SCIM management APIs from IdPs and that you should not point an IdP SCIM
connector at Bifrost's /scim/v2 endpoint, (2) clarify that adding the SCIM
attribute/URN (urn:ietf:params:scim:schemas:extension:enterprise:2.0:User) in
Okta is only necessary if you need the attribute included in outbound SCIM user
payloads from Okta to a supported provisioning endpoint (and show the exact
steps to add the attribute/variable/external name as currently written), and (3)
verify and fix the referenced image resources — ensure
okta-scim-profile-editor-page.png, okta-scim-profile-editor-add-attribute.png,
and okta-scim-profile-editor-mapping.png exist under media/user-provisioning/
and update the filenames/paths in the doc to match exactly if they differ.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 3ab85ca7-ed71-48ec-bf1a-60e68f580ed4
⛔ Files ignored due to path filters (3)
docs/media/user-provisioning/okta-scim-profile-editor-add-attribute.pngis excluded by!**/*.pngdocs/media/user-provisioning/okta-scim-profile-editor-mapping.pngis excluded by!**/*.pngdocs/media/user-provisioning/okta-scim-profile-editor-page.pngis excluded by!**/*.png
📒 Files selected for processing (1)
docs/enterprise/setting-up-okta.mdx
Confidence Score: 4/5Safe to merge after correcting one inaccuracy in Steps 4 and 9 that conflicts with the config schema. Steps 4 and 9 both state that attributeValue is required for each Bifrost mapping when SCIM is enabled, but transports/config.schema.json declares attributeRoleMappings with additionalProperties false and no attributeValue field — only team and BU mappings support it. An operator who follows the docs literally and adds attributeValue to a role mapping will get a schema validation failure that prevents Bifrost from starting. docs/enterprise/setting-up-okta.mdx — the attributeValue notes in Steps 4 and 9 should be scoped to team/BU mappings only. Important Files Changed
Reviews (5): Last reviewed commit: "docs: update for custom attributes" | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
BearTS
force-pushed
the
06-09-docs_update_for_custom_attributes
branch
from
2a176ab to
04c5381
Compare
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
There was a problem hiding this comment.
♻️ Duplicate comments (3)
docs/enterprise/setting-up-okta.mdx (3)
407-409:⚠️ Potential issue | 🟠 Major | ⚡ Quick winNote incorrectly describes the relationship between SCIM
external_nameand Bifrost mapping fields.Lines 407-409 state: "Use the same name for the SCIM attribute (
external_name) as the OIDC claim you expose in the token...This way a single Bifrost mapping rule works for both OIDC login and SCIM push without needing to setattributeValue."This guidance is incorrect. Bifrost's attribute mappings (configured in Step 10) are keyed by the JWT claim fields
attributeandvalue(orattributeValue), and for team/business-unit mappings, alsoattributeType. The SCIMexternal_nameis an Okta-internal field that controls how Okta names attributes in its outbound SCIM payloads; it does not determine or simplify Bifrost's mapping configuration.Correct the note to instruct users to configure their Bifrost mapping rules'
attributefield to match the OIDC claim name (e.g.,"attribute": "bifrostRole"), and remove the claim that aligning SCIMexternal_nameavoids settingattributeValue.📝 Suggested fix
<Note> - Use the same name for the SCIM attribute (`external_name`) as the OIDC claim you expose in the token. For example, if your authorization server emits `bifrostRole` as a JWT claim, name the SCIM attribute `bifrostRole` too. This way a single Bifrost mapping rule works for both OIDC login and SCIM push without needing to set `attributeValue`. + When configuring Bifrost attribute mappings in Step 10, set the `attribute` field to match the OIDC claim name you expose in the token. For example, if your authorization server emits a `bifrostRole` claim, configure your mapping rule with `"attribute": "bifrostRole"`. This ensures Bifrost can match the claim value during OIDC login. </Note>🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/enterprise/setting-up-okta.mdx` around lines 407 - 409, The Note incorrectly claims SCIM `external_name` can replace Bifrost mapping configuration; update the text to remove that claim and instruct readers to set the Bifrost mapping fields to match the OIDC claim instead: tell them to configure the Bifrost mapping rule's "attribute" field to the JWT claim name (for example, "attribute": "bifrostRole") and, where applicable, supply "value" (or "attributeValue") and "attributeType" for team/business-unit mappings as described in Step 10; also clarify that Okta's SCIM `external_name` only affects Okta's outbound attribute naming and does not simplify or replace Bifrost mapping configuration.
364-391:⚠️ Potential issue | 🟠 Major | 🏗️ Heavy liftSCIM attribute mapping subsection may not reflect Bifrost's actual provisioning model.
This subsection instructs users to add custom attributes to the Okta SCIM app schema and provides detailed Profile Editor steps. However, as flagged in past review, Bifrost's enterprise documentation elsewhere states it does not support inbound SCIM management APIs from IdPs and advises against configuring IdP SCIM connectors to point at Bifrost's
/scim/v2endpoint.If this restriction is still accurate:
- Clarify that adding SCIM attributes in Okta is only necessary if the attribute needs to be included in outbound SCIM payloads to a different downstream system (not Bifrost).
- State explicitly that Bifrost does not consume these SCIM attributes via inbound SCIM push.
- Verify that the three referenced screenshot files exist under
media/user-provisioning/with the exact filenames shown (past review found them missing).If Bifrost has added inbound SCIM support since the past review, update the broader user provisioning documentation to reflect this change and remove the conflicting guidance.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/enterprise/setting-up-okta.mdx` around lines 364 - 391, Update the "Map custom attributes to SCIM (for SCIM attribute-based mappings)" subsection to clarify Bifrost's actual SCIM behavior: if Bifrost does not accept inbound SCIM pushes, state explicitly that adding SCIM attributes in Okta is only needed when you intend to include those attributes in outbound SCIM payloads to other downstream systems (not consumed by Bifrost), and add a clear note that Bifrost does not consume SCIM attributes via inbound pushes to /scim/v2; alternatively, if Bifrost now supports inbound SCIM, update the broader user provisioning docs to reflect that and remove the warning; also verify the three image filenames referenced (okta-scim-profile-editor-page.png, okta-scim-profile-editor-add-attribute.png, and the third screenshot name used) exist in media/user-provisioning/ and correct or remove image references if they are missing.
152-152:⚠️ Potential issue | 🟠 Major | ⚡ Quick winMisleading guidance: SCIM
external_namedoes not control Bifrost attribute mappings.Line 152 suggests that matching the OIDC token claim name with the SCIM attribute's
external_namewill "avoid needingattributeValueoverrides in your mappings." This is inaccurate.Bifrost's provisioning attribute mappings (for roles, teams, and business units) are keyed by the JWT claim fields
attributeandvalue/attributeValue(plusattributeType/attributeValuefor team/business-unit mappings), as shown in the code. The SCIMexternal_nameis an Okta-side field used to wire Okta user profile attributes into outbound SCIM payloads; it does not control or simplify Bifrost's mapping configuration.Update this sentence to instruct users to configure the
attributefield in their Bifrost mapping rules to match the OIDC claim name they expose in the token (e.g.,"attribute": "role"), and remove the claim that matching SCIMexternal_namehas any effect onattributeValuerequirements.📝 Suggested fix
-Set **Name** to the claim name Bifrost will see in the token — use the same name as your SCIM attribute's `external_name` (configured in the SCIM app profile) to avoid needing `attributeValue` overrides in your mappings. +Set **Name** to the claim name Bifrost will see in the token (e.g., `role`). In your Bifrost attribute mappings (configured in Step 10), use this same claim name as the `attribute` field (e.g., `"attribute": "role"`).🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/enterprise/setting-up-okta.mdx` at line 152, Replace the misleading guidance about SCIM `external_name` with a clear instruction that Bifrost mapping rules use the JWT claim fields and that users must set the mapping's "attribute" to the OIDC claim name they expose in the token (e.g., `"attribute": "role"`); remove any suggestion that matching the Okta SCIM `external_name` will avoid `attributeValue`/`attributeType` overrides and briefly note that `attributeValue` (and `attributeType` for team/business-unit mappings) are required by Bifrost mapping logic and are independent of Okta's SCIM external_name.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Duplicate comments:
In `@docs/enterprise/setting-up-okta.mdx`:
- Around line 407-409: The Note incorrectly claims SCIM `external_name` can
replace Bifrost mapping configuration; update the text to remove that claim and
instruct readers to set the Bifrost mapping fields to match the OIDC claim
instead: tell them to configure the Bifrost mapping rule's "attribute" field to
the JWT claim name (for example, "attribute": "bifrostRole") and, where
applicable, supply "value" (or "attributeValue") and "attributeType" for
team/business-unit mappings as described in Step 10; also clarify that Okta's
SCIM `external_name` only affects Okta's outbound attribute naming and does not
simplify or replace Bifrost mapping configuration.
- Around line 364-391: Update the "Map custom attributes to SCIM (for SCIM
attribute-based mappings)" subsection to clarify Bifrost's actual SCIM behavior:
if Bifrost does not accept inbound SCIM pushes, state explicitly that adding
SCIM attributes in Okta is only needed when you intend to include those
attributes in outbound SCIM payloads to other downstream systems (not consumed
by Bifrost), and add a clear note that Bifrost does not consume SCIM attributes
via inbound pushes to /scim/v2; alternatively, if Bifrost now supports inbound
SCIM, update the broader user provisioning docs to reflect that and remove the
warning; also verify the three image filenames referenced
(okta-scim-profile-editor-page.png, okta-scim-profile-editor-add-attribute.png,
and the third screenshot name used) exist in media/user-provisioning/ and
correct or remove image references if they are missing.
- Line 152: Replace the misleading guidance about SCIM `external_name` with a
clear instruction that Bifrost mapping rules use the JWT claim fields and that
users must set the mapping's "attribute" to the OIDC claim name they expose in
the token (e.g., `"attribute": "role"`); remove any suggestion that matching the
Okta SCIM `external_name` will avoid `attributeValue`/`attributeType` overrides
and briefly note that `attributeValue` (and `attributeType` for
team/business-unit mappings) are required by Bifrost mapping logic and are
independent of Okta's SCIM external_name.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: fe7947be-222b-489f-a90d-3f227c9274fd
⛔ Files ignored due to path filters (3)
docs/media/user-provisioning/okta-scim-profile-editor-add-attribute.pngis excluded by!**/*.pngdocs/media/user-provisioning/okta-scim-profile-editor-mapping.pngis excluded by!**/*.pngdocs/media/user-provisioning/okta-scim-profile-editor-page.pngis excluded by!**/*.png
📒 Files selected for processing (1)
docs/enterprise/setting-up-okta.mdx
BearTS
force-pushed
the
06-09-docs_update_for_custom_attributes
branch
from
04c5381 to
28923cb
Compare
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/enterprise/setting-up-okta.mdx (1)
422-525: 🧹 Nitpick | 🔵 Trivial | 🏗️ Heavy liftConsider adding a config.json example tab for users who configure Bifrost via file.
The guidelines specify that Mintlify MDX docs should include "Web UI / API / config.json tabs." This section currently shows only the UI approach (line 422: "Using the Bifrost UI") with a configuration reference table (lines 511-525), but no concrete
config.jsonexample.If users can configure the Okta OIDC provider via
config.jsondirectly, consider adding a tab with a complete working example that includes:
- All required fields (
issuerUrl,authServerType,clientId,clientSecret)- Optional fields (
audience,apiToken,provisioningToken)- Sample
attributeRoleMappings,attributeTeamMappings,attributeBusinessUnitMappingsarrays- Comments explaining the mapping evaluation rules
Validate any config.json example against
transports/config.schema.jsonto ensure accuracy.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/enterprise/setting-up-okta.mdx` around lines 422 - 525, Add a "config.json" tab alongside the UI instructions showing a complete example JSON configuration for the Okta provider that includes required fields (issuerUrl, authServerType, clientId, clientSecret), optional fields (audience, apiToken, provisioningToken), and sample attributeRoleMappings, attributeTeamMappings, and attributeBusinessUnitMappings arrays; include short inline comments describing evaluation rules (first-match for attributeRoleMappings, all-match for team/businessUnit mappings, case-insensitive and "*" passthrough), reference the configuration keys exactly as used in the docs (issuerUrl, authServerType, clientId, clientSecret, audience, apiToken, provisioningToken, attributeRoleMappings, attributeTeamMappings, attributeBusinessUnitMappings) and validate the example against transports/config.schema.json to ensure field names/types match the schema before adding the tab to the MDX.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/enterprise/setting-up-okta.mdx`:
- Around line 152-153: Update the two passages to remove the contradictory
implication that name alignment alone removes other requirements: explicitly
state that when SCIM is enabled each Bifrost mapping must include attributeValue
in addition to attribute (i.e., the mapping needs both the SCIM external_name
and the attributeValue for SCIM provisioning), whereas for OIDC-only flows the
OIDC claim name (attribute) is sufficient and attributeValue is not required;
clarify that aligning the OIDC claim name (attribute) with the SCIM
external_name simply allows you to reuse the same attribute key in both mappings
for consistency and easier maintenance, but it does not eliminate the
requirement to set attributeValue for SCIM mappings, and remove any sentence
claiming that alignment alone makes attributeValue unnecessary.
- Around line 261-262: Update the note at the sentence that currently reads
"This step is optional if you plan to use SCIM push (Step 9) for real-time sync
instead" so it no longer implies SCIM push and the API token are mutually
exclusive; replace it with the suggested wording: "This step is optional if you
plan to rely solely on SCIM push (Step 9) for real-time sync. Note that SCIM
push and background sync are complementary—the API token enables the 24-hour
background reconciliation that catches anything SCIM push may have missed."
Ensure the changed sentence appears in the same paragraph that references SCIM
push (Step 9) and the 24-hour background reconciliation so the complementarity
is clear.
---
Outside diff comments:
In `@docs/enterprise/setting-up-okta.mdx`:
- Around line 422-525: Add a "config.json" tab alongside the UI instructions
showing a complete example JSON configuration for the Okta provider that
includes required fields (issuerUrl, authServerType, clientId, clientSecret),
optional fields (audience, apiToken, provisioningToken), and sample
attributeRoleMappings, attributeTeamMappings, and attributeBusinessUnitMappings
arrays; include short inline comments describing evaluation rules (first-match
for attributeRoleMappings, all-match for team/businessUnit mappings,
case-insensitive and "*" passthrough), reference the configuration keys exactly
as used in the docs (issuerUrl, authServerType, clientId, clientSecret,
audience, apiToken, provisioningToken, attributeRoleMappings,
attributeTeamMappings, attributeBusinessUnitMappings) and validate the example
against transports/config.schema.json to ensure field names/types match the
schema before adding the tab to the MDX.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: f73dc35b-2133-4337-9c26-ada41705f64d
⛔ Files ignored due to path filters (3)
docs/media/user-provisioning/okta-scim-profile-editor-add-attribute.pngis excluded by!**/*.pngdocs/media/user-provisioning/okta-scim-profile-editor-mapping.pngis excluded by!**/*.pngdocs/media/user-provisioning/okta-scim-profile-editor-page.pngis excluded by!**/*.png
📒 Files selected for processing (2)
docs/enterprise/setting-up-okta.mdxdocs/mcp/auth/per-user-oauth.mdx
💤 Files with no reviewable changes (1)
- docs/mcp/auth/per-user-oauth.mdx
BearTS
force-pushed
the
06-09-docs_update_for_custom_attributes
branch
from
28923cb to
0f1756a
Compare
BearTS
force-pushed
the
06-09-docs_update_for_custom_attributes
branch
from
0f1756a to
f52142c
Compare
BearTS
force-pushed
the
06-09-docs_update_for_custom_attributes
branch
from
f52142c to
ba07712
Compare
Merge activity
|
2 participants
Summary
Expands the Okta setup guide to cover SCIM attribute-based mappings for roles, teams, and business units, and clarifies when each authorization server type and sync mechanism applies.
Changes
department,costCenter, custom fields, etc.), not justbifrostRoleexternal_namewith the OIDC claim name so a single Bifrost mapping rule works for both OIDC login and SCIM push without requiringattributeValueoverridesType of change
Affected areas
How to test
Review the rendered documentation for the Okta setup guide and verify:
external_namewith the OIDC claim nameBreaking changes
Related issues
Security considerations
None. This is a documentation-only change covering Okta SSO and SCIM configuration guidance.
Checklist
docs/contributing/README.mdand followed the guidelinesSummary by CodeRabbit
attributeValuefor lookups