Create Plan your upgrade rollout doc by janugeethakumari-okta · Pull Request #6211 · okta/okta-developer-docs

janugeethakumari-okta · 2026-06-08T15:20:58Z

Description

What's changed?
Adds a new developer guide, Plan your upgrade rollout, for the "Prepare to Upgrade to Okta Identity Engine" journey.
The guide walks developers and admins through sequencing org upgrades (preview → sandbox → production), rolling out Identity Engine flows gradually to user segments using code-based routing, load balancing, or incremental scaling, and replacing deprecated features — Integrated Windows Authentication, Device Trust, and Okta Mobile — before the upgrade.

This update also adds five new sections sourced from gaps identified against the admin-facing help.okta.com content:

Upgrade your Sign-In Widget
Update event hook endpoints
Prepare Terraform for the upgrade
Build a test plan
Plan for rollback

Files changed:

Add docs/guides/oie-upgrade-rollout-plan/ (index.md + main/index.md)
Register the guide in docs/guides/index.md
Add the guide to the Okta Identity Engine upgrade section in navbar.const.js

Is this PR related to a Monolith release?
No. Targeting the July monthly developer docs release (code freeze June 26, 2026.07.0).

Resolves

OKTA-1192952

Netlify preview link

Preview link

okta-prod-github-app · 2026-06-08T15:21:14Z

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/guides/index.md	87	67	80	78
✅ packages/@okta/vuepress-site/docs/guides/oie-upgrade-rollout-plan/index.md	100	100	100	100
✅ packages/@okta/vuepress-site/docs/guides/oie-upgrade-rollout-plan/main/index.md	78	66	100	59

Successfully checked 3 of 3 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-06-08T15:57:14Z

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/guides/index.md	87	67	80	78
✅ packages/@okta/vuepress-site/docs/guides/oie-upgrade-rollout-plan/index.md	100	100	100	100
✅ packages/@okta/vuepress-site/docs/guides/oie-upgrade-rollout-plan/main/index.md	79	66	100	62

Successfully checked 3 of 3 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-06-08T18:08:33Z

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/guides/index.md	87	67	80	78
✅ packages/@okta/vuepress-site/docs/guides/oie-upgrade-rollout-plan/index.md	100	100	100	100
✅ packages/@okta/vuepress-site/docs/guides/oie-upgrade-rollout-plan/main/index.md	81	76	100	67

Successfully checked 3 of 3 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.

… plan sections

okta-prod-github-app · 2026-06-09T16:43:31Z

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/guides/index.md	87	67	80	78
✅ packages/@okta/vuepress-site/docs/guides/oie-upgrade-rollout-plan/index.md	100	100	100	100
✅ packages/@okta/vuepress-site/docs/guides/oie-upgrade-rollout-plan/main/index.md	80	77	89	67

Successfully checked 3 of 3 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-06-09T20:03:41Z

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/guides/index.md	87	67	80	78
✅ packages/@okta/vuepress-site/docs/guides/oie-upgrade-rollout-plan/index.md	100	100	100	100
✅ packages/@okta/vuepress-site/docs/guides/oie-upgrade-rollout-plan/main/index.md	81	80	92	66

Successfully checked 3 of 3 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.

grahamsmith-okta

a few comments

grahamsmith-okta · 2026-06-25T18:37:11Z

+
+#### What you need
+
+* Access to the Admin Console for each org you plan to upgrade


Suggested change

* Access to the Admin Console for each org you plan to upgrade

* Access to the Admin Console for each org that you plan to upgrade

grahamsmith-okta · 2026-06-25T18:38:51Z

+Whichever strategy you choose, follow this sequence:
+
+1. Start with internal users or a small test group.
+2. Validate sign-in, registration, MFA enrollment, and password recovery end-to-end.


Suggested change

2. Validate sign-in, registration, MFA enrollment, and password recovery end-to-end.

2. Validate sign-in, registration, MFA enrollment, and password recovery flows end to end.

grahamsmith-okta · 2026-06-25T18:39:41Z

+
+## Upgrade your Sign-In Widget
+
+If your app uses an embedded Sign-In Widget, verify that it runs version 5.11.0 or later before you schedule the org upgrade. Earlier versions don't support Identity Engine flows. If you haven't already upgraded the widget, do it now as part of your rollout prep, not at the same time as the org upgrade.


Suggested change

If your app uses an embedded Sign-In Widget, verify that it runs version 5.11.0 or later before you schedule the org upgrade. Earlier versions don't support Identity Engine flows. If you haven't already upgraded the widget, do it now as part of your rollout prep, not at the same time as the org upgrade.

If your app uses an embedded Sign-In Widget, verify that it runs version 5.11.0 or later before you schedule the org upgrade. Earlier versions don't support Identity Engine flows. If you haven't already upgraded the widget, do it now as part of your rollout prep.

grahamsmith-okta · 2026-06-25T18:40:45Z

+
+## Replace Integrated Windows Authentication
+
+Integrated Windows Authentication (IWA) routing rules needs to be removed before you can upgrade. The Identity Engine Upgrade Hub blocks the upgrade if any IWA routing rules exist in your org.


Suggested change

Integrated Windows Authentication (IWA) routing rules needs to be removed before you can upgrade. The Identity Engine Upgrade Hub blocks the upgrade if any IWA routing rules exist in your org.

Remove Integrated Windows Authentication (IWA) routing rules before you upgrade. The Identity Engine Upgrade Hub blocks the upgrade if any IWA routing rules exist in your org.

grahamsmith-okta · 2026-06-25T18:41:53Z

+
+Integrated Windows Authentication (IWA) routing rules needs to be removed before you can upgrade. The Identity Engine Upgrade Hub blocks the upgrade if any IWA routing rules exist in your org.
+
+To prepare:


Suggested change

To prepare:

To prepare, complete the following steps:

grahamsmith-okta · 2026-06-25T18:42:14Z

+
+Classic Engine Device Trust isn't supported in Identity Engine. The replacement is Okta Verify with managed certificates and Okta FastPass.
+
+Start by identifying whether your org uses Device Trust for Desktop, mobile, or both, then plan the migration path for each.


Suggested change

Start by identifying whether your org uses Device Trust for Desktop, mobile, or both, then plan the migration path for each.

Start by identifying whether your org uses Device Trust for Desktop, mobile, or both, and then plan the migration path for each.

grahamsmith-okta · 2026-06-25T18:43:09Z

+
+## Replace Okta Mobile
+
+Okta Mobile is deprecated and unavailable after the Identity Engine upgrade. Before upgrading, make sure that all affected users are enrolled in Okta Verify.


Suggested change

Okta Mobile is deprecated and unavailable after the Identity Engine upgrade. Before upgrading, make sure that all affected users are enrolled in Okta Verify.

Okta Mobile is unavailable in Identity Engine. Before upgrading, make sure that all affected users are enrolled in Okta Verify.

grahamsmith-okta · 2026-06-25T18:44:31Z

+Okta Mobile is deprecated and unavailable after the Identity Engine upgrade. Before upgrading, make sure that all affected users are enrolled in Okta Verify.
+
+* Identify which users currently rely on Okta Mobile.
+* Communicate the deprecation timeline to those users.


is the phrase "deprecation timeline" accurate? Okay if so, but I don't think we call other features that are Classic-only "deprecated in OIE"

Create Plan your upgrade rollout doc

c1412c4

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

Fix links

7f208a5

Improve Acrolinx score

279ca26

Add upgrade sign-in widget,event hook endpoint,terraform,build a test…

165c03f

… plan sections

Update links with alias

fac9e4c

grahamsmith-okta reviewed Jun 25, 2026

View reviewed changes


		#### What you need

		* Access to the Admin Console for each org you plan to upgrade

	2. Validate sign-in, registration, MFA enrollment, and password recovery end-to-end.
	2. Validate sign-in, registration, MFA enrollment, and password recovery flows end to end.


		## Upgrade your Sign-In Widget

		If your app uses an embedded Sign-In Widget, verify that it runs version 5.11.0 or later before you schedule the org upgrade. Earlier versions don't support Identity Engine flows. If you haven't already upgraded the widget, do it now as part of your rollout prep, not at the same time as the org upgrade.


		## Replace Integrated Windows Authentication

		Integrated Windows Authentication (IWA) routing rules needs to be removed before you can upgrade. The Identity Engine Upgrade Hub blocks the upgrade if any IWA routing rules exist in your org.

	Integrated Windows Authentication (IWA) routing rules needs to be removed before you can upgrade. The Identity Engine Upgrade Hub blocks the upgrade if any IWA routing rules exist in your org.
	Remove Integrated Windows Authentication (IWA) routing rules before you upgrade. The Identity Engine Upgrade Hub blocks the upgrade if any IWA routing rules exist in your org.


		Integrated Windows Authentication (IWA) routing rules needs to be removed before you can upgrade. The Identity Engine Upgrade Hub blocks the upgrade if any IWA routing rules exist in your org.

		To prepare:


		Classic Engine Device Trust isn't supported in Identity Engine. The replacement is Okta Verify with managed certificates and Okta FastPass.

		Start by identifying whether your org uses Device Trust for Desktop, mobile, or both, then plan the migration path for each.


		## Replace Okta Mobile

		Okta Mobile is deprecated and unavailable after the Identity Engine upgrade. Before upgrading, make sure that all affected users are enrolled in Okta Verify.

	Okta Mobile is deprecated and unavailable after the Identity Engine upgrade. Before upgrading, make sure that all affected users are enrolled in Okta Verify.
	Okta Mobile is unavailable in Identity Engine. Before upgrading, make sure that all affected users are enrolled in Okta Verify.

Uh oh!

Conversation

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

Uh oh!

Description

Resolves

Netlify preview link

Uh oh!

okta-prod-github-app Bot commented Jun 8, 2026

Acrolinx score

Uh oh!

okta-prod-github-app Bot commented Jun 8, 2026

Acrolinx score

Uh oh!

okta-prod-github-app Bot commented Jun 8, 2026

Acrolinx score

Uh oh!

okta-prod-github-app Bot commented Jun 9, 2026

Acrolinx score

Uh oh!

okta-prod-github-app Bot commented Jun 9, 2026

Acrolinx score

Uh oh!

grahamsmith-okta left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

janugeethakumari-okta commented Jun 8, 2026 •

edited

Loading