Skip to main content

​
Overview

Token migration copies tokens issued in the Authlete 2.2/2.3 environment (the source environment) to the new Authlete 3.0 environment (the destination environment), so that the tokens remain usable and valid after your authorization server switches to the Authlete 3.0 environment. Token migration is optional. If you do not migrate tokens, tokens issued in the source environment do not exist in the Authlete 3.0 environment. Depending on your implementation, refreshing those tokens and introspecting them fail, so in most cases users have to authenticate again. Token migration is performed by the Token Migrator, a service provided by Authlete. While running, the Token Migrator periodically checks the source environment for new tokens and changes to existing tokens, and copies them to the destination environment. The Token Migrator only has read access to the source database and does not change any data there.

​
What Is Migrated

  • Access tokens of clients in scope. A client is in scope when it meets the Client Token Migration Conditions.
  • Refresh tokens. A refresh token is stored together with its access token, so it is migrated with the access token. There is no separate step or setting for refresh tokens.

​
What Is Not Migrated

  • Token deletion events.
  • Temporarily stored data, such as authorization codes and request URIs.
  • Tokens issued or changed in the destination environment. The copy is one-directional, from the source environment to the destination environment.

​
Supported Versions and Deployment Models

Token migration is only possible from Authlete 2.2/2.3 to the latest Authlete 3.0 release, for the same deployment model and region. If you wish to migrate to Authlete 3.0 but aren’t currently using Authlete 2.2 or 2.3, please contact our support team so we can assist you in the process to upgrade your environment. Who runs the Token Migrator depends on the deployment model: Dry run is a mode in which the Token Migrator runs without writing to the destination environment. On Shared and Dedicated environments:
  • Disabling the Synchronize Client Tokens setting of a client takes the client out of scope only from the next check onward. Synchronize Client Tokens is the client setting that marks a client for token migration.
  • Deleting the source service does not stop the Token Migrator.
For running the Token Migrator in a self-managed Kubernetes environment, see Migration Phase (Optional) in the Kubernetes installation guide. For operating it, see also Token Migrator Timing and Intervals, Stopping and Resuming the Token Migrator, and Interpreting Token Migrator Logs.

​
Client Token Migration Conditions

The Token Migrator migrates a client’s tokens only when it identifies the client in the source environment and the client in the destination environment as matching clients. The requirements are strict to ensure that a client’s tokens are migrated to the correct client in the destination environment. Both clients must meet the following conditions:
  • The clientId value must match - clientIdAlias is ignored
  • The serviceId (api_key) that both clients exist in must be the same in both environments
  • The destination client must have the Synchronize Client Tokens setting enabled
  • The clientSecret value must match

​
Meeting the Conditions

When you migrate service and client configuration, set the following so that the clients meet the conditions:
  • With the Authlete Management Console import (Shared), tick the Synchronize Client Tokens and Migrate Client Secrets checkboxes. If you do not tick Migrate Client Secrets, the client secret is randomly generated.
  • With the configuration migrator (Dedicated and self-managed), keep SYNC_CLIENT_TOKENS=true and MIGRATE_CLIENT_SECRETS=true (the defaults).
After the import, you can also update individual clients:
  • Enable Synchronize Client Tokens under Client Settings > Basic Settings > Advanced > Migration Settings.
  • Update the secret of a specific client by calling the Update Client Secret API (/api/{serviceId}/client/secret/update/{clientIdentifier}).
To test the end to end migration process at a smaller scale, enable Synchronize Client Tokens on a single client so that only its tokens are migrated. Keep in mind that tokens will only be migrated while the Token Migrator is running.

​
Checking Clients Excluded from Migration

  • Shared and Dedicated: Authlete does not notify you of clients that are excluded from token migration. Check the conditions above before you start the migration.
  • Self-managed: the Token Migrator logs the clients in scope and the clients whose secrets do not match. See Determining in-scope clients.

​
How Long the Migration Takes

The duration depends mainly on the following, in order of impact:
  • The number of clients in scope: roughly 1–2 seconds per client on the first pass.
  • The token volume: on the order of 1,000,000 tokens per 70 minutes within a single client.
Measure in a verification environment before scheduling a downtime window. On Shared environments, delay may also occur because other users may be migrating tokens at the same time.

​
Choosing a Cutover Approach

Cutover is the switch of your authorization server from the source environment to the Authlete 3.0 environment. Any applications that are communicating with the Authlete source environment need to be updated to point to the new Authlete 3.0 environment. The changes required vary depending on your setup but this could include:
  • Changing the API version if you are using our SDKs
  • Updating endpoints due to the change of endpoint structure in Authlete 3.0 compared to Authlete 2.2/2.3
  • Updating authentication credentials due to the change of authentication mechanism in Authlete 3.0 compared to Authlete 2.2/2.3
  • Configuration changes
  • New version updates for your own authorization server(s)
Choose one of the following approaches: Between bulk token migration and JIT migration synchronization, choose mainly by the amount of tokens that need to be migrated and how much downtime of your own service can be tolerated. If you roll back by reconnecting your authorization server to the source environment, tokens issued in the Authlete 3.0 environment after the cutover remain in the 3.0 environment but are not copied back to the source environment, so they are lost for your service.

​
Bulk Token Migration

  1. Stop the applications connected to the Authlete source environment (on Dedicated, at a time scheduled with Authlete support)
  2. Migrate the clients and synchronize their settings so that they meet the Client Token Migration Conditions (see Meeting the Conditions). Their tokens are then migrated by the Token Migrator. On Dedicated environments, also request Authlete support to start the Token Migrator; on self-managed environments, deploy it
  3. Wait until the migration is complete (on Dedicated, Authlete support notifies you; otherwise, see Monitoring Progress)
  4. Update applications to connect to the new Authlete 3.0 environment
  5. On Dedicated and self-managed environments, stop the Token Migrator (see After the Cutover)
  • Rollback: roll back authorization server changes to connect back to the Authlete source environment

​
Just In Time (JIT) Migration Synchronization

  1. Migrate the clients and synchronize their settings so that they meet the Client Token Migration Conditions (see Meeting the Conditions). Their tokens are then migrated by the Token Migrator. On Dedicated environments, also request Authlete support to start the Token Migrator at a time set with them; on self-managed environments, deploy it
  2. Wait until all tokens have been created in the Authlete 3.0 environment (on Dedicated, Authlete support notifies you)
  3. Update applications to connect to the new Authlete 3.0 environment
  4. On Dedicated and self-managed environments, stop the Token Migrator (see After the Cutover)
Between steps 2 and 4, the Token Migrator keeps monitoring token changes in the source environment and copies them over.
  • Rollback: roll back authorization server changes to connect back to the Authlete source environment

​
Zero Downtime (Parallel Cutover)

This approach requires changes to your authorization server before you start the migration of services and clients into the Authlete 3.0 environment, and the Authlete 3.0 environment must be available. A sample authorization server that implements this approach is available in authlete/java-oauth-server-migration. In this approach, the authorization server connects to both the Authlete 3.0 server (the primary) and the Authlete 2.2/2.3 server (the secondary). Incoming calls are delegated to the primary first by default. Depending on the primary’s response, or on whether the endpoint is available only in 3.0, the authorization server either returns the primary’s response or delegates the request to the secondary. While the Token Migrator is running in the background and tokens are becoming available in the Authlete 3.0 environment, the primary API will be able to handle more and more of the incoming requests. Once all tokens are copied/updated in the Authlete 3.0 environment, all of the incoming calls to your application are handled by the Authlete 3.0 environment. At this time, the migration is complete. No other token changes should be occurring in the Authlete 2.2/2.3 environment.

​
Monitoring Progress

Token migration progress can be viewed in the organization’s audit logs:
  • The audit log entry shows the number of tokens created and updated within a rolling 4 hour time window.
  • The entry is written only when tokens are actually persisted in the destination environment.
  • The entry’s timestamp is not refreshed. Only the created and updated counts increase as tokens are migrated.
  • An unchanged entry does not mean the Token Migrator has stopped.
On self-managed environments, see also Token migration iteration in the log guide.

​
Verifying the Migration

Once the migration is complete, you can verify that your tokens have been properly migrated and are valid:
  • Pass the tokens to Authlete’s Process Introspection Request API on the 3.0 environment.
  • On self-managed environments with direct database access, compare token counts per client or service in the source and destination databases.

​
After the Cutover

Once the cutover is completed, perform all operations on tokens only in the Authlete 3.0 environment. Stop the Token Migrator according to your deployment model:
  • Shared: the Token Migrator keeps running and cannot be stopped.
  • Dedicated: request Authlete support to stop it.
  • Self-managed: remove it as described in Remove the token migrator.

​
Troubleshooting

​
Tokens of a client are not migrated

Check that the client meets all of the Client Token Migration Conditions. If the client secrets do not match, do one of the following:
  • Run the configuration migrator again with MIGRATE_CLIENT_SECRETS=true.
  • Update the secret of the destination client by calling the Update Client Secret API.