Skip to main content

​
Overview

Token migration is optional but will allow previously issued tokens from the Authlete 2.2/2.3 environment (i.e. the source environment) to be usable and valid in the new Authlete 3.0 environment. The token-migrator service will copy access tokens from the Authlete source environment into the Authlete 3.0 environment. When running, it will be polling the Authlete source environment for new tokens or token updates and propagate these into the Authlete 3.0 environment. Tokens will only be copied for clients that exist in both the Authlete 2.2/2.3 and Authlete 3.0 environment and for clients that have the Synchronize Client Tokens setting enabled. Refresh tokens are part of the same token record as their access token, so they are migrated together; there is no separate step or setting for refresh tokens. On Shared and Dedicated Cloud environments, the token-migrator service is operated by Authlete, meaning that unticking the Synchronize Client Tokens flag on a client would take it out of scope only from the next poll onward. As stopping the process is also handled by Authlete, deleting the source service would not stop it either. Duration is driven primarily by the number of clients in scope (roughly 1–2 seconds per client on the first pass) and secondarily by 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. Delay may also occur in Authlete shared environments as the platform is available for other users who may be migrating tokens at the same time. Token migration progress can be viewed in the organization’s audit logs indicating the amount of created and updated tokens within a rolling 4 hour time window. Keep in mind that the entry is written only when tokens are actually persisted, and its timestamp is not refreshed (only the created/updated counts will increase). Once the migration is complete, you can verify that your tokens have been properly migrated and are valid by passing them to Authlete’s Process Introspection Request API on the 3.0 environment, and if direct database access is available in self-managed environments, by comparing token counts per client/service in both the source and destination databases.

​
Client Token Migration Conditions

There are specific requirements that need to be met by clients in both the source and destination system in order for the token migrator to correctly identify that they are matching clients and should have their tokens migrated. The requirements are strict to ensure that a client’s tokens are migrated to the correct client in the destination system. The following conditions must be met for both clients (the one that exists in the source system and the one that exists in the destination system) :
  • The clientId value must match - clientIdAlias is ignored
  • The serviceId (api_key) that both clients exist in must be the same in both systems
  • The destination client, must have the Synchronize Client Tokens setting enabled
    • This can be enabled during the import dialog, or in the client settings under Client Settings > Basic Settings > Advanced > Migration Settings
    • In the configuration migrator, keep SYNC_CLIENT_TOKENS=true (the default)
  • The clientSecret value must match
    • This can be automatically copied over via the import dialog
    • In the configuration migrator, keep MIGRATE_CLIENT_SECRETS=true (the default)
    • You may also update the secret of a specific client by calling the Update Client Secret API (/api/{serviceId}/client/secret/update/{clientIdentifier})

​
Planning the Authorization Server cutover

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 and authentication credentials due to the change of authentication mechanism and endpoint structure in Authlete 3.0 compared to Authlete 2.2/2.3
  • Configuration changes
  • New version updates for your own internal authentication server(s)
We can provide guidance on hard cutover approaches (which require downtime) along with a slow cutover approach that can be used to achieve zero downtime during the migration period.

​
Immediate cutover upgrade

This approach still requires changes to your authentication applications. But a hard cutover will need to be performed to switch from the Authlete source environment to the Authlete 3.0 environment. For this approach, there are two options which mainly depends on the amount of tokens that need to be migrated along with how much capacity for downtime of your own service that can be tolerated:

​
Bulk Token Migration (Downtime expected between steps 1 to 4)

  1. Applications connected to the Authlete source environment are stopped (at scheduled time with the Authlete team)
  2. Notify Authlete support team and the token-migrator service will be started
  3. Authlete team provides update once the migration is completed
  4. Update applications to connect to new Authlete 3.0 environment
  • Rollback (optional) : Downgrade/roll back authentication server changes to connect back to the Authlete source environment

​
Just In Time (JIT) migration synchronization (Downtime expected only in step 3)

  1. Set a designated time with the Authlete team to enable the token-migrator service
  2. Receive response from Authlete team that all tokens have been created and any token changes will be monitored and copied over by the token-migrator service
  3. Update applications to connect to new Authlete 3.0 environment
  • Rollback (optional) : Downgrade/roll back authentication server changes to connect back to the Authlete source environment

​
Zero downtime (parallel cutover) upgrade

This approach requires changes to your authentication applications prior to the migration/upgrade to Authlete 3.0, but the Authlete 3.0 environment must be available. A sample authorization server that implements this approach is available in authlete/java-oauth-server-migration. The approach we have implemented involves changing the authorization server to connect to both the Authlete 3.0 (primary) server and the Authlete 2.3 (secondary) server. Incoming calls are by default delegated to the primary first and depending on its response (or whether it is a 3.0 only endpoint feature) will determine whether the response from the primary is returned or whether the request is delegated to the secondary API instead. These application changes should be deployed before you start the migration of services and clients into the Authlete 3.0 environment. While the token-migrator service 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 then all of the incoming calls to your application would be delegated and 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.3 environment and all calls will be using the latest Authlete 3.0 environment.

​
Future Work and Compatibility

Currently, token migration is only possible between Authlete 2.2/2.3, and the latest Authlete 3.0 patch version, for the same deployment model and region. For running the token migrator in a self-managed Kubernetes environment, see Migration Phase (Optional) in the Kubernetes installation guide. For operating the token migrator, see also Token Migrator Timing and Intervals, Stopping and Resuming the Token Migrator, and Interpreting Token Migrator Logs. 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.

​
Troubleshooting & FAQ

​
Q: How can I check the migration progress?

A: The audit-log entry’s created/updated counts increase as tokens are migrated. An unchanged entry does not mean the migrator has stopped.

​
Q: How can I make sure that client’s secrets remain the same when they are imported into the new 3.0 environment?

A: You can do so by ticking the Migrate Client Secrets checkbox when migrating your service configuration. Otherwise, the client secret will be randomly generated.

​
Q: How can I test the client token migration selectively for a single client?

A: Using the new Synchronize Client Tokens flag in the UI, you can selectively mark the client as “in scope” for token migration and only their tokens will be migrated. This will allow you to test the end to end migration process at a smaller scale. Keep in mind that tokens will only be migrated while the token-migrator service is running.

​
Q: How are token changes and new tokens handled by the migration?

A: Token changes and new token creation events are polled by the token-migrator service for the configured clients, and upon detecting these events the respective tokens are updated/created in the destination database.

​
Q: What items are not part of the migration scope?

A: Only issued token data is migrated. The token migrator does not migrate token deletion events and other temporarily stored data such as authorization codes and request URIs. Keep in mind that the copy is one-directional, and that tokens on the source environment that were already migrated will not be reflected on 3.0. Once the cutover is completed, token actions should be exclusively taken on 3.0.