This Series is authored by Ruchir Parikh.

Welcome back to our “Demystifying Upgrading to OIE Series”!. 

In this series of 4 episodes, we will take a fictitious company and walk through the steps of the Okta Identity Engine (OIE) upgrade, offering tips and tricks along the way. 

If you missed the first episodes, please check our Episode #1: The Upgrade Scenario & Episode #2: Eligibility & Best Practices & Episode #3: From Device Trust to Device Context. In these 3 episodes, we covered the upgrade process, common blockers and their remediation, and managed devices.

This fourth and final post will cover customization, we will be looking into the details of three of the most common customization that our Okta Classic customers might have implemented.

These are customer hosted sign-in-widget, third-party user agents as well as leveraging the Okta API.

Atko HytekSys knew they had customized their Okta tenant. The team had documented their critical use cases but wanted to ensure they were not missing any others. They also plan on moving all critical customization from Okta Production to a Preview environment still on Classic to ensure the use cases do not stop working post-OIE upgrade and cause downtime. 

Let’s discuss these “classic” customizations!

Customer-Hosted Sign-in-Widget

Atko HytekSys has some internally developed applications that use Okta for authentication. They host the Okta Sign-in-Widget (SiW) in their environment for full control over customization and branding. 

Where and how many Akto HyTekSys Okta SiW are there? 

To find where all your company-hosted Okta SiW are you can look at the “Trusted Origins” page and filter for CORS (Cross-origin resource sharing). In the table on the page, you will find the “Origin URL” for each of the Okta SiW you are hosting outside of Okta (see in the admin console: Okta Administrator Dashboard → Security → API → Trusted Origins).

What version is my hosted SiW? 

Using the Origin URL from above, you can open a new tab or browser window and navigate to that URL. Once the page has loaded, you can right-click on it and click “View page source.” 

Depending on the level of customization doing a search of “okta-signin-widget” should highlight a URL that looks something like this:

• src=https://global.oktacdn.com/okta-signin-widget/[widgetVersionHere]/js/okta-sign-in.min.js

If you can not find something like this search for “okta” to see if the source URL (src=) has been modified as well. 

Do I need to change my code?

Maybe. Review the upgrading to OIE documentation on the Okta Developer site to understand all nuances of the upgrade, changes to SDKs, tips on planning for the upgrade, etc.  

Some general guidelines:

• All customizations should be thoroughly tested in a non-production environment.
• Custom sign-in integrations (via API, SDK, or embedded widget) have the ability to continue to operate in “classic mode” with little or no changes required, potentially – however, there could be some impact to other, related flows (cross-application SSO, registration flows, recovery flows, etc).  Therefore, even if taking this approach, thorough testing prior to upgrading is required.
• In order to take advantage of new features/capabilities of OIE authentication flows, updates will be required to your integrations.
  • Server-side SDK/API integrations:
    • Must updated to use new OIE SDKs to access new features/functionality
  • Embedded widget / Client-side JS SDK integrations:
    • Must be set to use OIE flows (i.e. “useClassicEngine: false” in widget configs)
    • OIDC client app used by widget/JS auth object must have the “Interaction Code Flow” grant type enabled
    • Authorization server (“issuer” setting) must have “Interaction Code Flow” grant type enabled in its Access Policies.

Third-party User Agents

Third-party user agents are tools/apps/custom on-prem scripts that a customer internally developed or finds via GitHub. Some of the common third-party user agents are gimme-aws-creds, saml2aws, Snowflake CLI or JBDC drivers, AWS CLI or JDBC drivers, and python [version] for scripts or apps. To see if you are using any third-party user agents please follow the steps below. 

Note: You can ignore user agents such as browsers, Jamf, and other known items and focus on unknown user agents that need further investigation

• In the Okta system log, use this search query "client.userAgent.rawUserAgent pr" for a thirty-day period, downloading the CSV and looking at the rawUserAgents present in the tenant
  • The user agents are listed under the heading “client.user_agent.raw_user_agent” in the CSV you download. 
  • Filter out known user agents, leaving only unique/unknown userAgent(s) 
  • Determine the application or service account associated with the rawUserAgent
  • Ask the user using the app/service account owner what it is being used for and if there is any customization occurring there
  • Testing the OIE upgrade in preview with user agents is recommended prior to upgrading production
    • Okta is not affiliated with third-party user agents and cannot provide support to troubleshoot any issues that may occur
    • Support for your user agents will need to come from the provider for the third-party agent

Okta API 

The Okta API offers a great deal of flexibility. With every platform upgrade comes some changes to the API, in the case of OIE, the major changes are in the Sessions API.

As a general rule, session management of the Okta session from server side calls is no longer supported.  More specifically, the following endpoints are deprecated in OIE:

• GET /api/v1/sessions/{sessionId}
• DELETE /api/v1/sessions/{sessionId}
• POST /api/v1/sessions/{sessionId}/lifecycle/refresh
• POST /api/v1/sessions?additionalFields=cookieToken
• POST /api/v1/users/me/lifecycle/delete_sessions

This is because session cookies (and session IDs) have changed in OIE.  OIE generates an “IDX” session cookie, while classic engine flows generate an “SID” session cookie.  The above endpoints work only with the “SID” session cookie, NOT with the “IDX” cookie.  

If you are using any of the above endpoints, it is highly recommended that you move away from using the session ID entirely, and instead use the My Sessions endpoints directly from the browser:

• GET /api/v1/sessions/me
• DELETE /api/v1/sessions/me
• POST /api/v1/sessions/me/lifecycle/refresh

The above endpoints will work for BOTH the “SID” and “IDX” session cookies.

Thank you!

All of us at Okta involved in OIE would like to thank you for reading this series. We hope this was useful, and will guide you effectively in your upgrade to OIE!

Should you have additional questions, please reach out to the community, and feel free to schedule time during our Office Hours to get 1:1 time with our experts!

Thanks again for watching these episodes!

Author: Ruchir Parikh

Contributors: Brent Arrington, Dimitri Volkmann