User identification policy guide by brentschaus-okta · Pull Request #6235 · okta/okta-developer-docs

brentschaus-okta · 2026-06-15T17:45:10Z

Description:

What's changed?
Adds a new guide, Configure a user identification policy, covering how to use the Policies API to manage user identification policies (USER_IDENTIFICATION type). The guide explains that the policy maps one-to-one to an app sign-in policy, is auto-managed alongside it (no direct create/map/clone/delete), and that you manage only its rules. It walks through finding the policy, reviewing the default rule, and creating/updating a rule to show or hide the Sign in with Okta FastPass button via showSignInWithOV (ALWAYS/NEVER), including platform/network conditions and the FastPass prerequisite.
Is this PR related to a Monolith release?
Yes — 2026.08.0. The feature is behind the USER_IDENTIFICATION_POLICY feature flag (EA). API spec: okta-oas3#3413 (OKTA-1177885).

Resolves:

OKTA-1193878

Netlify Preview Link:

brentschaus-okta · 2026-07-01T00:31:57Z

@arsalanbadar-okta @andreeajurj-okta @grahamsmith-okta — re: the > **Notes:** block added in user-identification-policies/main/index.md lines 55-58.

Arsalan clarified that showSignInWithOV kept its existing name from the Authenticators API rather than being updated for the FastPass rebrand, so I added a note explaining why the field still says "OV." Curious what you all think — does this read clearly, and is there anything to add or correct?

brentschaus-okta · 2026-07-23T02:21:13Z

@arsalanbadar-okta — I smoke-tested this guide against a live EA org (USER_IDENTIFICATION_POLICY flag on, Okta FastPass enabled) and pushed a small fix in d2f7cd9. Could you confirm the change is correct before we merge?

What I verified against the live API (all accurate as written):

GET /policies?type=USER_IDENTIFICATION and GET /policies?type=ACCESS_POLICY — the one-to-one _links.userIdentificationPolicy link is present on every app sign-in policy (GET-only hint), as documented.
Create → update → delete of a rule (POST/PUT/DELETE .../rules) all work, and showSignInWithOV accepts ALWAYS/NEVER.
Direct create/update on the UIP itself returns the exact documented error: This operation isn't supported in the user identification policy. ✅

The one thing I changed — the "Review the default rule" example. The example we had described a rule that looked like a custom rule ("name": "Default Rule", "priority": 0, "system": false, populated conditions, showSignInWithOV: ALWAYS). The actual auto-created default rule in my test org looked like this instead:

Field	Old example	Observed in test org
`name`	`Default Rule`	`Catch-all Rule`
`priority`	`0`	`99`
`system`	`false`	`true`
`conditions`	network + WINDOWS platform	`null`
`showSignInWithOV`	`ALWAYS`	`NEVER`

I updated the example to match, added a sentence describing the default rule, and gave it a GET/PUT-only self link (no DELETE) to reinforce that the default can't be removed. I also added the DELETE hint + deactivate link to the create/update rule response examples, since the live API returns those.

Caveat / the reason I'm asking you to confirm: this was a single developer test org, so it's possible the default shape varies by how the org or app sign-in policy was provisioned, and the original example reflected a real default somewhere. Can you confirm the canonical auto-created default rule is the Catch-all Rule / priority 99 / system: true / NEVER shape? If the default really does ship as ALWAYS with conditions in some configs, I'll revert or caveat it.

I did not test the ALWAYS-without-FastPass error path — FastPass is enabled in this org, and triggering that error would need a global authenticator toggle I didn't want to flip on a shared org. If you can confirm that error string is current, that closes the last unverified claim.

- Add activate/update to unsupported direct operations - Lowercase 'user identification policy' in prose and error string - Update Okta FastPass not-enabled error message - Remove deprecated settings.showSignInWithOV override note (no longer allowed) - Add mappings link to list policies response example - Add ACCESS_POLICY response example with userIdentificationPolicy link - Diagram step 7: specify Okta FastPass enabled

Add deactivate lifecycle link and _embedded.resourceType per Arsalan's real org response. UIP example already matched.

…ntry Two back-to-back object literals broke the eval in build-overview-pages.js (Unexpected token '{'), failing the site build.

- Add 'Test your policy with policy simulation' section to the user identification policy guide (per Arsalan's feedback that simulation now includes this policy type) - Clarify that rules can be created and updated but not deleted - Add user identification policies to the supported types list in the policy simulation guide Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Replaces the placeholder sequence diagram with the finalized, Okta-branded version from the design team. Same content and file path, so the existing guide reference and alt text still apply.

Groups it with the existing OIE-version note per the repo's convention for consecutive notes.

Points Okta Verify/FastPass, test user, and test group prerequisites at the Authenticators/Users/Groups API operations instead of help.okta.com, since this is an API guide for developers who provision programmatically.

Matches the spacing convention used later in the same guide.

Split three sentences over the 25-word limit and reworded the System Log paragraph to avoid two back-to-back sentences of identical length.

Smoke-tested the guide against a live EA org. The default-rule example was actually a custom-rule shape; replaced it with the real auto-created default (Catch-all Rule, priority 99, system: true, conditions: null, showSignInWithOV: NEVER) and added a sentence describing it. Added the DELETE hint and deactivate link to the create/update rule response examples to match the live API. Co-Authored-By: Claude Code

…owSignInButton Per Arsalan in Slack, the userIdentification rule settings payload changed from a flat showSignInWithOV field to a nested securityMethods.fastpass.showSignInButton structure. Removed the now-obsolete note explaining the old field's naming convention.

Live-org smoke test showed an untouched default rule returns an empty actions.userIdentification.settings object, not a populated showSignInButton: NEVER value.

okta-prod-github-app · 2026-07-29T18:28:55Z

Acrolinx score

A minimum Acrolinx Score of 80 is required. The total score is an average of the subscores.
Select Total score to review the Acrolinx scorecard for your article. Try to increase your individual scores, for example: Correctness. Your content will be clearer and more consistent.

Article	Total score Required:80	Word and phrases (Brand, terms) Preferred: 80	Correctness (Spelling, grammar) Preferred: 80	Clarity (Readability) Preferred: 80
✅ packages/@okta/vuepress-site/docs/concepts/policies/index.md	86	82	85	65
✅ packages/@okta/vuepress-site/docs/guides/index.md	87	67	80	78
✅ packages/@okta/vuepress-site/docs/guides/policy-simulation/main/index.md	85	79	79	88
✅ packages/@okta/vuepress-site/docs/guides/user-identification-policies/index.md	100	100	100	100
✅ packages/@okta/vuepress-site/docs/guides/user-identification-policies/main/index.md	82	100	59	44

Successfully checked 5 of 5 documents.
See summary in Content Analysis Dashboard

Reopen the pull request or push new changes to check again.

Depending on the Acrolinx server configuration, the
links expire after some time and you must have a login for the
Acrolinx server to access them again.

…olicies/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com>

okta-prod-github-app · 2026-07-29T23:33:00Z

Acrolinx score

A minimum Acrolinx Score of 80 is required. The total score is an average of the subscores.
Select Total score to review the Acrolinx scorecard for your article. Try to increase your individual scores, for example: Correctness. Your content will be clearer and more consistent.

Article	Total score Required:80	Word and phrases (Brand, terms) Preferred: 80	Correctness (Spelling, grammar) Preferred: 80	Clarity (Readability) Preferred: 80
✅ packages/@okta/vuepress-site/docs/concepts/policies/index.md	86	82	85	65
✅ packages/@okta/vuepress-site/docs/guides/index.md	87	67	80	78
✅ packages/@okta/vuepress-site/docs/guides/policy-simulation/main/index.md	85	79	79	88
✅ packages/@okta/vuepress-site/docs/guides/user-identification-policies/index.md	100	100	100	100
✅ packages/@okta/vuepress-site/docs/guides/user-identification-policies/main/index.md	82	100	59	44

Successfully checked 5 of 5 documents.
See summary in Content Analysis Dashboard

Reopen the pull request or push new changes to check again.

Depending on the Acrolinx server configuration, the
links expire after some time and you must have a login for the
Acrolinx server to access them again.

okta-prod-github-app · 2026-07-29T23:33:20Z

Acrolinx score

A minimum Acrolinx Score of 80 is required. The total score is an average of the subscores.
Select Total score to review the Acrolinx scorecard for your article. Try to increase your individual scores, for example: Correctness. Your content will be clearer and more consistent.

Article	Total score Required:80	Word and phrases (Brand, terms) Preferred: 80	Correctness (Spelling, grammar) Preferred: 80	Clarity (Readability) Preferred: 80
✅ packages/@okta/vuepress-site/docs/concepts/policies/index.md	86	82	85	65
✅ packages/@okta/vuepress-site/docs/guides/index.md	87	67	80	78
✅ packages/@okta/vuepress-site/docs/guides/policy-simulation/main/index.md	85	79	79	88
✅ packages/@okta/vuepress-site/docs/guides/user-identification-policies/index.md	100	100	100	100
✅ packages/@okta/vuepress-site/docs/guides/user-identification-policies/main/index.md	82	100	59	44

Successfully checked 5 of 5 documents.
See summary in Content Analysis Dashboard

Reopen the pull request or push new changes to check again.

Depending on the Acrolinx server configuration, the
links expire after some time and you must have a login for the
Acrolinx server to access them again.

okta-prod-github-app · 2026-07-29T23:33:23Z

Acrolinx score

A minimum Acrolinx Score of 80 is required. The total score is an average of the subscores.
Select Total score to review the Acrolinx scorecard for your article. Try to increase your individual scores, for example: Correctness. Your content will be clearer and more consistent.

Article	Total score Required:80	Word and phrases (Brand, terms) Preferred: 80	Correctness (Spelling, grammar) Preferred: 80	Clarity (Readability) Preferred: 80
✅ packages/@okta/vuepress-site/docs/concepts/policies/index.md	86	82	85	65
✅ packages/@okta/vuepress-site/docs/guides/index.md	87	67	80	78
✅ packages/@okta/vuepress-site/docs/guides/policy-simulation/main/index.md	85	79	79	88
✅ packages/@okta/vuepress-site/docs/guides/user-identification-policies/index.md	100	100	100	100
✅ packages/@okta/vuepress-site/docs/guides/user-identification-policies/main/index.md	82	100	59	44

Successfully checked 5 of 5 documents.
See summary in Content Analysis Dashboard

Reopen the pull request or push new changes to check again.

Depending on the Acrolinx server configuration, the
links expire after some time and you must have a login for the
Acrolinx server to access them again.

brentschaus-okta requested review from barbaravo-okta, emikhasyak-okta, grahamsmith-okta, ishan-krishna-okta, janethu-okta, paulwallace-okta and susanharper-okta as code owners June 15, 2026 17:45

This comment was marked as outdated.

Sign in to view

brentschaus-okta added docs release Tagged to be released during scheduled docs release Work In Progress labels Jun 15, 2026

This comment was marked as outdated.

Sign in to view

okta deleted a comment from okta-prod-github-app Bot Jul 1, 2026

brentschaus-okta removed the Work In Progress label Jul 18, 2026

brentschaus-okta force-pushed the tbs-okta-1193878-user-identification-policy-guide branch from 95d94ae to af0a1ac Compare July 18, 2026 08:02

brentschaus-okta and others added 7 commits July 27, 2026 12:07

OKTA-1193878: add user identification policy guide

26343c7

OKTA-1193878: add user identification policy evaluation sequence diagram

31eda5a

adds navbar update

798b3df

Match ACCESS_POLICY example to SME-provided response body

01c68ec

Add deactivate lifecycle link and _embedded.resourceType per Arsalan's real org response. UIP example already matched.

Fix navbar syntax: missing comma after user-identification-policies e…

d985072

…ntry Two back-to-back object literals broke the eval in build-overview-pages.js (Unexpected token '{'), failing the site build.

brentschaus-okta added 8 commits July 27, 2026 12:07

docs(OKTA-1193878): swap in designer version of sequence diagram

c63c222

Replaces the placeholder sequence diagram with the finalized, Okta-branded version from the design team. Same content and file path, so the existing guide reference and alt text still apply.

Link Admin Console UI equivalent for creating a user ID policy rule

e6a4d5a

Groups it with the existing OIE-version note per the repo's convention for consecutive notes.

Add blank blockquote line in Notes block for consistency

a4994bb

Matches the spacing convention used later in the same guide.

acrolinx

ca1d8ed

Trim sentence length and vary paragraph rhythm in user ID policy guide

23a40d4

Split three sentences over the 25-word limit and reworded the System Log paragraph to avoid two back-to-back sentences of identical length.

brentschaus-okta force-pushed the tbs-okta-1193878-user-identification-policy-guide branch from 4322962 to 158ea3a Compare July 27, 2026 16:07

okta deleted a comment from okta-prod-github-app Bot Jul 29, 2026

Fix default rule response example for user identification policies

55cc976

Live-org smoke test showed an untouched default rule returns an empty actions.userIdentification.settings object, not a populated showSignInButton: NEVER value.

okta deleted a comment from okta-prod-github-app Bot Jul 29, 2026

barbaravo-okta reviewed Jul 29, 2026

View reviewed changes

brentschaus-okta and others added 3 commits July 29, 2026 19:32

Update packages/@okta/vuepress-site/docs/guides/user-identification-p…

2088d8e

…olicies/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com>

Update packages/@okta/vuepress-site/docs/guides/user-identification-p…

a0c031d

…olicies/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com>

Update packages/@okta/vuepress-site/docs/guides/user-identification-p…

f9d152b

…olicies/main/index.md Co-authored-by: barbaravo-okta <87335401+barbaravo-okta@users.noreply.github.com>

barbaravo-okta approved these changes Jul 30, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

User identification policy guide - #6235

User identification policy guide#6235
brentschaus-okta wants to merge 24 commits into
masterfrom
tbs-okta-1193878-user-identification-policy-guide

brentschaus-okta commented Jun 15, 2026 •

edited

Loading

Uh oh!

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

brentschaus-okta commented Jul 1, 2026

Uh oh!

brentschaus-okta commented Jul 23, 2026

Uh oh!

okta-prod-github-app Bot commented Jul 29, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

okta-prod-github-app Bot commented Jul 29, 2026

Uh oh!

okta-prod-github-app Bot commented Jul 29, 2026

Uh oh!

okta-prod-github-app Bot commented Jul 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

brentschaus-okta commented Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description:

Resolves:

Netlify Preview Link:

Uh oh!

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

brentschaus-okta commented Jul 1, 2026

Uh oh!

brentschaus-okta commented Jul 23, 2026

Uh oh!

okta-prod-github-app Bot commented Jul 29, 2026

Acrolinx score

Uh oh!

Uh oh!

Uh oh!

Uh oh!

okta-prod-github-app Bot commented Jul 29, 2026

Acrolinx score

Uh oh!

okta-prod-github-app Bot commented Jul 29, 2026

Acrolinx score

Uh oh!

okta-prod-github-app Bot commented Jul 29, 2026

Acrolinx score

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

brentschaus-okta commented Jun 15, 2026 •

edited

Loading