|
| 1 | +--- |
| 2 | +title: Test your widget's existing customizations in a test environment |
| 3 | +--- |
| 4 | + |
| 5 | +<ApiLifecycle access="ie" /> |
| 6 | + |
| 7 | +Does your Okta Sign-In Widget have customizations such as CSS, JavaScript, i18n, branding, or custom sign-in pages? Test them in an Okta [Identity Engine](/docs/concepts/oie-intro/) (OIE) org before you upgrade production. This guide explains what to test, how to set up your test, and how to fix common issues. |
| 8 | + |
| 9 | +--- |
| 10 | + |
| 11 | +**Learning outcome** |
| 12 | + |
| 13 | +Validate that your Sign-In Widget customizations work in Identity Engine, and resolve any issues before you upgrade your production org. |
| 14 | + |
| 15 | +**What you need** |
| 16 | + |
| 17 | +* A test environment ready for Identity Engine. Use a preview org, a free trial Identity Engine org, or an [Integrator Free Plan org](/docs/reference/org-defaults/). |
| 18 | +* Your current Sign-In Widget version |
| 19 | +* A record of your existing customizations: CSS overrides, JavaScript hooks, i18n properties, and branding |
| 20 | + |
| 21 | +--- |
| 22 | + |
| 23 | +## Identify your widget deployment model |
| 24 | + |
| 25 | +Your testing approach depends on how your Sign-In Widget is deployed. |
| 26 | + |
| 27 | +| Deployment model | Description | Testing approach | |
| 28 | +| --- | --- | --- | |
| 29 | +| Okta-hosted (redirect) | Okta hosts the sign-in page. You customize it through the Admin Console or the code editor. | Test your customizations in a preview org after you upgrade it to Identity Engine. | |
| 30 | +| Embedded (self-hosted) | Your app hosts the Sign-In Widget directly. | Test in your app's development environment pointed at an Identity Engine org. | |
| 31 | + |
| 32 | +See [Redirect vs. embedded deployment](/docs/concepts/redirect-vs-embedded/) for more details. |
| 33 | + |
| 34 | +## Identify your customization types |
| 35 | + |
| 36 | +Check which customizations you have and what the Identity Engine upgrade may affect. |
| 37 | + |
| 38 | +| Customization type | What may change in newer widget versions and Identity Engine | Action | |
| 39 | +| --- | --- | --- | |
| 40 | +| CSS overrides | Unsupported CSS may break after a widget version update. The third generation (Gen3) of the Sign-In Widget doesn't support the CSS code editor. | Test styling after the upgrade. Migrate to [design tokens](/docs/guides/custom-widget-gen3/main/#use-design-tokens) if you're on Gen3. | |
| 41 | +| JavaScript hooks (the widget's `before` and `after` lifecycle hooks, plus older events such as `afterRender` or `processCreds`) | Some events behave differently or are deprecated in Identity Engine. The `after` hook is supported only in Identity Engine. These client-side widget hooks aren't the same as server-side registration inline hooks. | Remove deprecated methods and validate hook behavior. | |
| 42 | +| i18n translations | New Identity Engine-specific property keys are available. Some Classic Engine strings no longer apply. | Verify that translations display correctly and add new Identity Engine string overrides. | |
| 43 | +| Branding (logo, colors, background) | Supported through the Admin Console in both Classic Engine and Identity Engine. No breaking change is expected. | Confirm that branding renders after the upgrade. | |
| 44 | +| Custom sign-in page (hosted) | Classic Engine custom sign-in pages may not work after the upgrade. | Validate that the page loads and functions correctly. | |
| 45 | +| Security image | Removed in Identity Engine. No security image is displayed. | Remove references. No replacement is needed. | |
| 46 | +| Remember me checkbox | Replaced by [**Keep me signed in**](/docs/guides/keep-me-signed-in/main/) in Identity Engine. | Update your UI expectations. No code change is needed. | |
| 47 | + |
| 48 | +See [Upgrade the Okta Sign-In Widget](/docs/guides/oie-upgrade-sign-in-widget/main/) for more details on Sign-In Widget changes after the upgrade. |
| 49 | + |
| 50 | +## Test your customizations in a test environment |
| 51 | + |
| 52 | +### Step 1: Set up the test environment |
| 53 | + |
| 54 | +Use one of these environments: |
| 55 | + |
| 56 | +* **Preview org (recommended):** Upgrade your preview org to Identity Engine and test your customizations there. |
| 57 | +* **Identity Engine free trial org:** Create a free trial org and apply your customizations manually. |
| 58 | + |
| 59 | +For Okta-hosted widgets, apply your customizations in the Admin Console code editor of the test org. For embedded widgets, point your development app at the Identity Engine test org. |
| 60 | + |
| 61 | +### Step 2: Check for deprecated JavaScript methods |
| 62 | + |
| 63 | +Search your custom code for deprecated methods that don't work in later versions of the Sign-In Widget and Identity Engine. Check these common areas: |
| 64 | + |
| 65 | +* Factor Sequencing customizations |
| 66 | +* `afterRender` event handlers |
| 67 | +* The `useClassicEngine` configuration flag |
| 68 | + |
| 69 | +See [Deprecated JavaScript methods in the Sign-In Widget](/docs/guides/oie-upgrade-sign-in-widget-deprecated-methods/main/) for the full list. |
| 70 | + |
| 71 | +> **Note:** These are client-side Sign-In Widget hooks (for example, `before` and `after`). They aren't the server-side [registration inline hooks](/docs/guides/oie-upgrade-sign-in-widget/main/#registration-inline-hooks) that fire during registration. Test each type separately. |
| 72 | +
|
| 73 | +### Step 3: Test sign-in flows |
| 74 | + |
| 75 | +Sign in as a test user and validate each customized flow: |
| 76 | + |
| 77 | +* [Standard sign-in](/docs/guides/sign-in-overview/main/) (username and password) |
| 78 | +* [MFA enrollment and challenge](/docs/concepts/mfa/) |
| 79 | +* [Password recovery](https://help.okta.com/okta_help.htm?id=ext-add-self-service-password-reset) |
| 80 | +* [Self-service registration](/docs/concepts/self-service-registration/) (if enabled) |
| 81 | +* [Social or external Identity Provider authentication](/docs/concepts/identity-providers/) (if configured) |
| 82 | +* [Identifier-first flow behavior](/docs/concepts/sign-in-widget/) (new in Identity Engine) |
| 83 | + |
| 84 | +### Step 4: Test styling and branding |
| 85 | + |
| 86 | +* Confirm that the logo, colors, and background render correctly. |
| 87 | +* Check that your custom CSS overrides are applied. |
| 88 | +* Verify Sign-In Widget dimensions and layout. |
| 89 | +* Test on both desktop and mobile screen sizes. |
| 90 | + |
| 91 | +> **Note:** Unsupported CSS customizations beyond the documented styles may break after a widget version update. See [Updates to Sign-In Widget styling](/docs/guides/oie-upgrade-sign-in-widget-styling/main/) for more details. |
| 92 | +
|
| 93 | +### Step 5: Test i18n translations |
| 94 | + |
| 95 | +* Verify that your custom translations appear in all supported languages. |
| 96 | +* Check that new Identity Engine-specific strings (for example, `oie.password.challenge.title`) show default or custom values. |
| 97 | +* Confirm that removed Classic Engine strings don't cause errors. |
| 98 | + |
| 99 | +See [Updates to Sign-In Widget i18n properties](/docs/guides/oie-upgrade-sign-in-widget-i18n/main/) for more details. |
| 100 | + |
| 101 | +### Step 6: Test custom sign-in page behavior |
| 102 | + |
| 103 | +If you use a custom Okta-hosted sign-in page: |
| 104 | + |
| 105 | +* Confirm that the page loads without errors. |
| 106 | +* Check for `target is undefined` errors, which are common after an Identity Engine upgrade. |
| 107 | +* Validate that your redirect URIs work correctly. |
| 108 | +* Test that the Admin Console sign-in still works when **Default App for Sign-In Widget** is enabled. |
| 109 | + |
| 110 | +## Fix issues found during testing |
| 111 | + |
| 112 | +| Issue | Likely cause | Resolution | |
| 113 | +| --- | --- | --- | |
| 114 | +| Widget doesn't load | Deprecated JavaScript or missing configuration | Remove deprecated methods and verify that your widget version is 5.11.0 or later. | |
| 115 | +| `target is undefined` error | Custom sign-in page code references a removed object | Update your custom page code. | |
| 116 | +| Styling is missing or broken | CSS overrides are no longer applied in Gen3 | Migrate to design tokens or a supported styling API. | |
| 117 | +| i18n strings show raw keys | Classic Engine property keys are removed in Identity Engine | Map them to the new Identity Engine property keys. | |
| 118 | +| Sign-in page looks different | Identity Engine introduces the identifier-first flow and removes the security image | This is expected behavior. Update your user communications. | |
| 119 | +| Factor Sequencing isn't functional | Factor Sequencing rules aren't supported in Identity Engine | Remove Factor Sequencing customizations. | |
| 120 | +| Redirect URI issue | Redirect configuration changed in Identity Engine | Update your redirect URI configuration. | |
| 121 | + |
| 122 | +See [Identity Engine limitations](/docs/guides/ie-limitations/main/) to learn more about feature changes in Identity Engine. |
| 123 | + |
| 124 | +## Gen2 vs. Gen3 widget considerations |
| 125 | + |
| 126 | +If you're moving to the third generation (Gen3) of the Sign-In Widget as part of your Identity Engine upgrade, be aware of other testing needs. |
| 127 | + |
| 128 | +| Feature | Gen2 | Gen3 | |
| 129 | +| --- | --- | --- | |
| 130 | +| Deployment | Redirect and embedded | Redirect (Okta-hosted) only | |
| 131 | +| CSS editor | Supported | Not supported. Use design tokens. | |
| 132 | +| JavaScript events | Full event support | Reduced event support. `afterRender` may behave differently. | |
| 133 | +| Customization migration | n/a | Gen2 customizations don't carry over to Gen3. | |
| 134 | +| Accessibility | Standard | Improved color contrast, focus management, and screen reader support | |
| 135 | + |
| 136 | +> **Important:** Customizations that you made in Gen2 don't appear if you move to Gen3. You must reconfigure them. See [Migrate to the third generation (Gen3) Sign-In Widget](/docs/guides/custom-widget-migration-gen3/main/) and [Style the Sign-In Widget (third generation)](/docs/guides/custom-widget-gen3/main/) for more details. |
| 137 | +
|
| 138 | +## Validation checklist before upgrading production |
| 139 | + |
| 140 | +After you test in your test environment, confirm that all the following items pass before you schedule the production upgrade: |
| 141 | + |
| 142 | +* All sign-in flows work (sign-in, MFA, recovery, and registration). |
| 143 | +* Custom CSS renders correctly. |
| 144 | +* Custom JavaScript has no deprecated methods. |
| 145 | +* i18n translations display in all languages. |
| 146 | +* Custom sign-in pages load without errors. |
| 147 | +* Redirect URIs resolve correctly. |
| 148 | +* No console errors appear in browser developer tools. |
| 149 | +* Mobile and desktop layouts render correctly. |
| 150 | + |
| 151 | +## See also |
| 152 | + |
| 153 | +* [Upgrade the Okta Sign-In Widget](/docs/guides/oie-upgrade-sign-in-widget/main/) |
| 154 | +* [Updates to Sign-In Widget styling](/docs/guides/oie-upgrade-sign-in-widget-styling/main/) |
| 155 | +* [Updates to Sign-In Widget i18n properties](/docs/guides/oie-upgrade-sign-in-widget-i18n/main/) |
| 156 | +* [Deprecated JavaScript methods in the Sign-In Widget](/docs/guides/oie-upgrade-sign-in-widget-deprecated-methods/main/) |
| 157 | +* [Identity Engine limitations](/docs/guides/ie-limitations/main/) |
| 158 | +* [Identity Engine upgrade overview](/docs/guides/oie-upgrade-overview/main/) |
| 159 | +* [Style the Sign-In Widget (third generation)](/docs/guides/custom-widget-gen3/main/) |
0 commit comments