Authentication Backend Migration: What to Expect

Crosswork Assurance is migrating to a new authentication and authorization backend. As a tenant administrator, you need to understand how this migration changes the authorization model, how your users set new credentials, and which client types require your action.

What Changes and Why It Matters

The migration introduces three key changes:

• Authorization model: Changes from default-allow to default-deny
• Credential reset: All users must set new passwords in the new backend
• Identity provider (IDP) endpoints: Service provider endpoints change, which may require updates in your external IDP configuration

Authorization Model

From Default-Allow to Default-Deny

The previous authorization model allowed users to access all data unless explicitly restricted. The new model works in reverse: users have no data access unless you explicitly grant it through user group membership.

Built-In Unrestricted Access Groups

Two built-in user groups provide broad access to support the transition:

⚠️ Warning: These groups override all other group restrictions. If a user belongs to both an unrestricted access group and a more restrictive group, the unrestricted group takes precedence. To enforce restricted access, remove users from these groups.

How Your Users Are Migrated Automatically

The system evaluates each user's existing permissions independently during migration:

• Users without data permissions in any of their groups are added to All Data Access. This preserves their current access level under the new default-deny model.
• Users without visibility permissions in any of their groups are added to All Visibility Access.
• Users who already belong to groups with defined data or visibility permissions retain their existing scoped permissions and are not added to the unrestricted groups.

After migration, review user group assignments and remove users from unrestricted access groups where more restrictive access is appropriate.

User Credential Reset

All users must set a new password in the new authentication backend. Two paths are available depending on your deployment.

SMTP-Enabled Deployments

If your deployment has SMTP configured, migrated users automatically receive an invitation email with a link to set their new credentials. These links expire after three days. After a link expires, you can initiate a standard password reset from the user management interface, or the user can use the migration portal to set their credentials directly.

To verify whether SMTP is configured, check your tenant administration settings in the product UI. Cloud-hosted deployments typically have SMTP pre-configured. If you are unsure, contact your deployment administrator.

Migration Portal

A one-time migration portal is available for all users regardless of SMTP configuration. Use it when:

• SMTP is not configured
• No IDP is configured
• A user's username is not a valid email address
• An invitation email link has expired

After migration, the login page displays a Migrate account link below the login button. Users can also go directly to https://<tenantUrl>/login-migration.

How the Migration Portal Works

1. The user navigates to the Migrate account link on the login page, or goes directly to https://<tenantUrl>/login-migration.
2. The user logs in with their pre-migration credentials (existing username and password).
3. The user sets a new password for the new authentication backend.
4. The user can now log in with their new credentials.

The migration portal is a one-time mechanism. After a user successfully sets their new password and logs in, the portal rejects their old credentials on subsequent attempts. At that point, password resets go through the standard user management interface.

Identity Provider Configuration

What Migrates Automatically

Existing SAML and OIDC identity provider configurations migrate automatically to the new authentication backend. You do not need to re-create them. After migration, all migrated users are automatically assigned to the default IDP.

Changes to IDP Assignment

IDPs are now assigned on a per-user basis rather than applying to all users on the tenant. Key behaviors to be aware of:

• A user can have only one IDP assigned at a time.
• When an IDP is assigned to a user, password-based login is disabled for that user, and password resets are unavailable.
• To re-enable password login, remove the IDP assignment and initiate a password reset. Removing the IDP assignment alone does not restore a usable password.

Service Provider Endpoint Updates (Action May Be Required)

The service provider (SP) endpoints have changed. Depending on how your external IDP is configured, you may need to update its configuration manually before users can authenticate through it. The migration executor provides the new IDP configuration values.

SAML Providers

Update the following values in your external SAML IDP:

You can import the SP metadata XML directly into most external IDP platforms. These values are also available from the IDP management page in the product UI, or via the GET /v3/idps and GET /v3/idps/{id} API endpoints.

OIDC Providers

Update the following value in your external OIDC IDP:

Client ID and client secret are preserved. Scopes reset to openid, profile, and email. This value is also available from the IDP management page or via GET /v3/idps/{id} in the pcaCallbackUrl field.

Service Users

The new backend introduces dedicated service user support for programmatic access and integrations. Service users cannot log in via the web interface. They authenticate using Personal Access Tokens (PATs) or private key JSON files for JWT-based authentication.

If you currently use regular user accounts for programmatic access or integrations, those accounts migrate as regular users. However, long-lived API tokens for regular user accounts are no longer available in the new system.

To transition programmatic access to a service user:

1. Create a dedicated service user via the user management interface or API.
2. Assign appropriate user groups and roles to the service user.
3. Generate credentials (PAT or private key) from the interface.
4. Update your integrations to use the new service user credentials.
5. Decommission the old regular user account.

Client Migration Reference

The following table summarizes the migration impact by client type.

⚠️ Pre-migration requirement: The Sensor Collector must be upgraded to version 0.711.0 or later before migration begins. This is a mandatory pre-migration step.

Troubleshooting

A user's invitation email link has expired — what do I do?

Invitation links expire after three days. Initiate a standard password reset from the user management interface, or direct the user to the migration portal at https://<tenantUrl>/login-migration.

A user cannot log in after migration — what do I do?

Verify whether the user has an IDP assigned. If an IDP is assigned, the user must authenticate through that IDP — password login is disabled. If the user needs password-based login, remove the IDP assignment and initiate a password reset.

An external MQTT client lost connectivity after migration — what do I do?

External MQTT clients using legacy credentials lose connectivity after migration. Create a service user, generate a PAT, and reconfigure the MQTT client to use the tenant domain as the username and the PAT as the password.

Learn More

• Crosswork Assurance API documentation - Identity & Access Management — Full API documentation for user management, IDPs, user groups, and service accounts