How to migrate access rights to Opti ID

10 min

Complete your migration before you upgrade from CMS 12 to CMS 13

Before you upgrade from CMS 12 to CMS 13, you must migrate your access rights to Opti ID, your ID secure login for Optimizely, to ensure a smooth upgrade. To migrate, follow the steps below.

1. Migrate PaaS to Opti ID and confirm it works

Migrate the Developer Portal to Opti ID.

2. Move each user's access rights to roles before you migrate

For user identity, Opti ID identifies users by the identity provider's preferred_username, not always the email address.

This value is sometimes a username, domain name, or other identifier.

3. Match role names exactly

CMS matches role names by exact name, and matching is case-sensitive. cmsadmins, CmsAdmins, and CMSAdmins are three different roles.

A mismatch does not raise an error. Instead, it produces a role with none of the expected access.

4. Convert virtual roles to Opti ID groups

Opti ID auto-maps only CmsEditors, CmsAdmins, and CommerceAdmins.

Any other virtual role has no Opti ID equivalent and becomes an Opti ID group.

No bulk conversion tool exists, so convert virtual roles manually.

5. Enable the Opti ID setting on a non-production instance and test before production

Checking Opti ID Enabled for an instance in the Admin Center is permanent. It prepares the environment but does not switch authentication.

Authentication switches only when you deploy code that uses Opti ID.

6. Add your Opti ID packages

Install your Opti ID packages, such as the Opti ID NuGet package.

7. Register third-party admin pages so back-end users can authenticate

Extensions that add admin pages, such as Geta packages, must set the Opti ID authentication scheme on those pages.

If an extension does not support this, the migration cannot proceed until it does. Check this early.

8. Keep useAsDefault: false and use mixed-mode authentication for site-visitor logins

Opti ID is only for users who access Optimizely products, such as editors and admins.

Site visitors who need gated content use a separate SAML or OIDC app in your identity provider.

Before you upgrade from CMS 12 to CMS 13

After you install your packages, test and verify your login and access rights before you upgrade to CMS 13.

Confirm three things:

The correct people have access.

No one has extra access.

The edit and admin UI and admin extensions work.

Upgrade to CMS 13 from CMS 12

Once you've migrated your access rights to Opti ID, you can then upgrade to CMS 13.

You must use Opti ID from your first build in CMS 13.

Upgrade to CMS 13 from CMS 12.

Repeat the tests you carried out on CMS 12 to ensure the Opti ID configuration code migrated correctly.

After you complete the migration and upgrade

Once you've completed these migration steps and upgraded from CMS 12 to CMS 13:

Deprovision legacy PaaS portal access

Submit a request to Optimizely Support to deprovision your legacy PaaS portal access.

Users must sign in to Opti ID at least once before they appear in the CMS.

When a user signs in through Opti ID, CMS synchronizes them into its database so they are searchable when you assign access rights.

A user does not appear in CMS until they sign in at least once.

Tell users to expect a welcome email

Tell users in advance to expect a welcome email.

Opti ID sends each migrated user a welcome email they must act on.

Security-awareness training teaches people to ignore or report unexpected account emails.

Tell affected users in advance that the email is coming, who it is from, and what to do. This is a project-management action, not a technical one.