Skip to content

Add SCIM provisioning documentation for HCP#2561

Open
xargs-P wants to merge 10 commits into
mainfrom
PLCC-6884-HCP-SCIM
Open

Add SCIM provisioning documentation for HCP#2561
xargs-P wants to merge 10 commits into
mainfrom
PLCC-6884-HCP-SCIM

Conversation

@xargs-P
Copy link
Copy Markdown
Contributor

@xargs-P xargs-P commented Jun 2, 2026

Add comprehensive documentation for SCIM (System for Cross-domain Identity Management) provisioning feature, enabling automated user and group lifecycle management from identity providers.

New documentation pages:

  • scim.mdx: Complete SCIM provisioning guide with setup instructions for Microsoft Entra ID, Okta, Ping ID, and IBM Verify
  • troubleshoot-scim.mdx: Troubleshooting guide for common SCIM issues

Updated existing pages:

  • docs-nav-data.json: Added SCIM navigation entries after Troubleshoot SSO
  • sso/index.mdx: Added SCIM references in introduction and guidance sections
  • users.mdx: Added user provisioning methods section explaining manual vs SCIM
  • invite-users.mdx: Updated note about SCIM impact on manual invitations
  • manage-users.mdx: Added section on managing SCIM-provisioned users
  • groups.mdx: Added group provisioning methods and SCIM management sections
  • changelog.mdx: Added June 30, 2026 entry for SCIM GA release

Key features documented:

  • Provider-specific setup with attribute mapping tables
  • SCIM provisioning statuses and conflict handling
  • Quotas and limits (10K users, 5K groups, 5K members per group)
  • Deactivation/reactivation behavior
  • Comprehensive troubleshooting for sync failures, attribute errors, and provider-specific issues

Release: GA on June 30, 2026
Supported providers: Microsoft Entra ID, Okta, Ping ID, IBM Verify

Description

🎫 [Jira ticket]

Requested review scope:

  • Content touched by the PR only (typos, clarifications, tips)
  • Code test (command and code block changes)
  • Flow and language near changes (new/rearranged steps)
  • Review everything (rewrites, major changes)

Review urgency:

  • ASAP (bug fixes, broken content, imminent releases)
  • 3 days (small changes, easy reviews)
  • 1 week (default)
  • Best effort (very non-urgent)

All updates:

I have:

  • Verified that all status checks have passed
  • Verified that preview environment has successfully deployed
  • Verified appropriate label applied (hcp + product name)
  • Added all required reviewers (code owners and external)

Content checklist (optional)

Please do these things before requesting a review. I have:

  • Made any associated code repositories public
  • Added the hashicorp-education/teamName to any additional code or example repos as repo admin
  • Added redirects for any moved or removed pages
  • Spell checked the tutorial(s)
  • Followed the unified style guide
  • Linted code snippets (Details per language here)
  • Checked the steps for completeness (no steps are implied or hidden)
  • Looked at the local or vercel build and checked each new or changed page for:
    • display on the product curriculum page
    • callout box formatting
    • code block highlighting
    • right-hand navigation
    • next and back buttons
    • URL path

Add comprehensive documentation for SCIM (System for Cross-domain Identity
Management) provisioning feature, enabling automated user and group lifecycle
management from identity providers.

New documentation pages:
- scim.mdx: Complete SCIM provisioning guide with setup instructions for
  Microsoft Entra ID, Okta, Ping ID, and IBM Verify
- troubleshoot-scim.mdx: Troubleshooting guide for common SCIM issues

Updated existing pages:
- docs-nav-data.json: Added SCIM navigation entries after Troubleshoot SSO
- sso/index.mdx: Added SCIM references in introduction and guidance sections
- users.mdx: Added user provisioning methods section explaining manual vs SCIM
- invite-users.mdx: Updated note about SCIM impact on manual invitations
- manage-users.mdx: Added section on managing SCIM-provisioned users
- groups.mdx: Added group provisioning methods and SCIM management sections
- changelog.mdx: Added June 30, 2026 entry for SCIM GA release

Key features documented:
- Provider-specific setup with attribute mapping tables
- SCIM provisioning statuses and conflict handling
- Quotas and limits (10K users, 5K groups, 5K members per group)
- Deactivation/reactivation behavior
- Comprehensive troubleshooting for sync failures, attribute errors, and
  provider-specific issues

Release: GA on June 30, 2026
Supported providers: Microsoft Entra ID, Okta, Ping ID, IBM Verify
@xargs-P xargs-P requested a review from a team as a code owner June 2, 2026 23:52
@xargs-P xargs-P added the documentation Improvements or additions to documentation label Jun 2, 2026
@xargs-P xargs-P requested review from a team as code owners June 2, 2026 23:52
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Jun 2, 2026

Vercel Previews Deployed

Name Status Preview Updated (UTC)
Dev Portal ✅ Ready (Inspect) Visit Preview Fri Jun 5 22:23:53 UTC 2026
Unified Docs API ✅ Ready (Inspect) Visit Preview Fri Jun 5 22:20:22 UTC 2026

@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented Jun 3, 2026

Broken Link Checker

This PR contains broken links, but won't be blocked. Use this report to improve content quality:

Quick Actions

  • Internal links (HashiCorp sites): Please fix these - they impact user experience
  • External links: Consider if these are essential or can be updated/removed
  • Temporary issues: External sites may recover - check again before merging

Need Help?


Internal Links

Full Github Actions output

External Links

Summary

Status Count
🔍 Total 160
✅ Successful 77
⏳ Timeouts 0
🔀 Redirected 8
👻 Excluded 70
❓ Unknown 0
🚫 Errors 5
⛔ Unsupported 0

Errors per input

Errors in content/hcp-docs/content/docs/changelog.mdx

Errors in content/hcp-docs/content/docs/hcp/iam/sso/index.mdx

Errors in content/hcp-docs/content/docs/hcp/iam/sso/scim.mdx

Errors in content/hcp-docs/content/docs/hcp/iam/sso/troubleshoot-scim.mdx

Redirects per input

Redirects in content/hcp-docs/content/docs/changelog.mdx

Redirects in content/hcp-docs/content/docs/hcp/iam/sso/index.mdx

Redirects in content/hcp-docs/content/docs/hcp/iam/sso/scim.mdx

Redirects in content/hcp-docs/content/docs/hcp/iam/sso/troubleshoot-scim.mdx

Full Github Actions output

Comment thread content/hcp-docs/content/docs/hcp/iam/sso/scim.mdx
Comment thread content/hcp-docs/content/docs/hcp/iam/sso/scim.mdx

### For users

If a user with the same email address exists in both HCP and your identity provider, the identity provider user takes precedence. The lifecycle of that user is now managed by your identity provider instead of HCP.
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is not true. I think the email/pass user@example.com would continue to exist while the SSO user@example.com would live along side.


When you enable SCIM provisioning, HCP checks your identity provider directory to determine if users or groups already exist in HCP:

- **For users** - If a user with the same email address exists in both HCP and your identity provider, the identity provider user takes precedence
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does precedence mean here?

Comment thread content/hcp-docs/content/docs/hcp/iam/groups.mdx Outdated
Comment thread content/hcp-docs/content/partials/hcp-administration/invite-users.mdx Outdated
Comment thread content/hcp-docs/content/docs/changelog.mdx
Copy link
Copy Markdown
Contributor

@aimeeu aimeeu left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for porting this content into the docs. I left some suggestions.

Comment thread content/hcp-docs/content/docs/hcp/iam/sso/scim.mdx Outdated
Comment thread content/hcp-docs/content/docs/hcp/iam/sso/scim.mdx Outdated
Comment thread content/hcp-docs/content/docs/hcp/iam/sso/scim.mdx Outdated
Comment thread content/hcp-docs/content/docs/hcp/iam/sso/scim.mdx Outdated
- A Microsoft Entra tenant
- A custom application with SAML SSO enabled for your HCP organization

#### Configuration steps
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Trevor - We don't normally tell readers how to do something in an external system or application because we don't maintain those docs. It's too easy for our content to become wrong when the external product updates its docs.

However, I spent too much time trying to find the exact instructions you replicated so we could link to them. Closest I came was a question/answer post. So I think in this case, it's OK to leave these instructions in our docs. But I do have concerns on who is going to maintain this content and make sure Azure hasn't changed.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You made a good oberservation. We can remove if you think its best. Let me know.
These instructions came from an internal user guide . But I agree, they will be hard to keep up to date.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rselbach , the plan is to remove this section. But do you feel there is anything we should highlight to users at all?

Comment thread content/hcp-docs/content/docs/hcp/iam/sso/scim.mdx Outdated
- A custom application with SAML SSO enabled for your HCP organization

#### Configuration steps

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Question - these instructions match what's in our internal SCIM Provisioning User Guide, but they don't match what's in the Okta page you linked to in the supported providers section. Do the instructions not exist in the Okta docs?

Comment thread content/hcp-docs/content/docs/hcp/iam/groups.mdx Outdated
xargs-P and others added 8 commits June 4, 2026 13:55
punctuation

Co-authored-by: Aimee Ukasick <Aimee.Ukasick@ibm.com>
rewording

Co-authored-by: Aimee Ukasick <Aimee.Ukasick@ibm.com>
Co-authored-by: Aimee Ukasick <Aimee.Ukasick@ibm.com>
Removed SCIM provisioning details and simplified user management instructions.
Clarified group creation process when SCIM provisioning is enabled.
Clarified the precedence of SCIM-managed groups over HCP groups in case of name conflicts.
Clarified SCIM provisioning behavior for user management.
Clarified user lifecycle management for SCIM provisioning.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

do not merge documentation Improvements or additions to documentation HCP Runtime

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants