{"templateId":"markdown","versions":[{"version":"v1.39","label":"v1.39 STS","link":"/products/custody/v1.39/get-started/deployment/migration-guide","default":true,"active":false,"folderId":"c15a2701"},{"version":"v1.38","label":"v1.38 STS","link":"/products/custody/v1.38/get-started/deployment/migration-guide","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.34","label":"v1.34 LTS","link":"/products/custody/v1.34/get-started/deployment/migration-guide","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.26","label":"v1.26 LTS","link":"/products/custody/v1.26/get-started/deployment/migration-guide","default":false,"active":true,"folderId":"c15a2701"},{"version":"v1.19","label":"v1.19 LTS","link":"/products/custody/v1.19/get-started/deployment/migration-guide","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.15","label":"v1.15 LTS","link":"/products/custody/v1.15/get-started/deployment/migration-guide","default":false,"active":false,"folderId":"c15a2701"}],"sharedDataIds":{"sidebar":"sidebar-products/custody/@v1.15/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Migration guide","description":"User guides, API reference, and support resources.","siteUrl":"https://docs.ripple.com","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"migration-guide","__idx":0},"children":["Migration guide"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide describes specific tasks you need to perform as part of a migration to a new version of ","Ripple Custody","."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"115-and-above","__idx":1},"children":["1.15 and above"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As part of the upgrade from version 1.14 or below to version 1.15 or higher, all user entries must be migrated to a new format, in preparation for the single sign-on (SSO) feature. You must perform these steps regardless of whether you intend to use SSO."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"migration-process","__idx":2},"children":["Migration process"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The process for migrating to version 1.15 or above is as follows:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Step"},"children":["Step"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"More information"},"children":["More information"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["1"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Install ","Ripple Custody"," version 1.15 without SSO enabled"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["SaaS customers: Contact your Ripple liaison"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["On-premise customers: See the on-premise deployment details in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.26/support/change-history/v115#on-premise"},"children":["1.15 change history"]}]}]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["2"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check for conflicts in user entries"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["SaaS customers: Contact your Ripple liaison"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["On-premise customers: See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#check-for-user-conflicts"},"children":["Check for user conflicts"]}]}]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Update user entries with conflicts"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["SaaS and on-premise customers: See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#fix-user-conflicts"},"children":["Fix user conflicts"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["4"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Install ","Ripple Custody"," version 1.15 with SSO enabled"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["SaaS customers: Contact your Ripple liaison"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["On-premise customers: For details of feature flags to enable, contact your Ripple liaison"]}]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"success"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once you have completed these steps, to use SSO, contact your Ripple liaison to configure your external identity providers."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once migration is completed, the URL of the authentication endpoint changes, as follows:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Old URL format: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://auth.<HOST_URL>/token"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["New URL format: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://openid.<HOST_URL>/realms/Metaco/protocol/openid-connect/token"]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"check-for-user-conflicts","__idx":3},"children":["Check for user conflicts"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This procedure checks for conflicts in user records that are not allowed from version 1.15 of ","Ripple Custody","."," ","There are two possible types of conflicts:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sameAlias"]},": Users with the same alias and the same domain."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["samePublicKey"]},": Users with the same public key but a different alias and domain."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To check for conflicts between existing user definitions, call the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /internal/v1/users/conflicts"]}," API operation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example shows both types of conflicts:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"User conflict examples","header":{"title":"User conflict examples","controls":{"copy":{}}},"source":"{\n    \"sameAlias\":[\n        {\n            \"domainId\": \"8a0b02c3-fdd8-452e-bc6e-ef07a335ec7e\",\n            \"alias\": \"op1@ripple.com\",\n            \"userIds\":[\n                \"497f6eca-6276-4993-bfeb-53cbbbba6f08\",\n                \"47ecb890-2e2b-4d53-9428-bf08f2ee56dc\"\n            ]\n        }\n    ],\n    \"samePublicKey\":[\n        {\n            \"publicKey\": \"MFkw...NfPfw/q9YW74Q==\",\n            \"users\":[\n                {\n                    \"domainId\": \"8a0b02c3-fdd8-452e-bc6e-ef07a335ec7e\",\n                    \"alias\": \"op2@ripple.com\",\n                    \"userId\": \"497f6eca-6276-4993-bfeb-53cbbbba6f08\"\n                },\n                {\n                    \"domainId\": \"89hd02c3-fdd8-452e-bc6e-ef07a335ec7e\",\n                    \"alias\": \"op1@ripple.com\",\n                    \"userId\": \"hks86eca-6276-4993-bfeb-53cbbbba6f08\"\n                }\n            ]\n        }\n    ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"fix-user-conflicts","__idx":4},"children":["Fix user conflicts"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To fix the user conflicts, update users to have an alias which is unique in the domain."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information about how to update users:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In the API, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.26/api/get-started/key-operations/update/intent-proposal#propose-an-intent-to-update-an-entity"},"children":["Propose an intent to update an entity"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In the UI, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.26/ui/environment/user/update#update-a-user"},"children":["Update a user"]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The alias is shown in the UI as ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Email address"]},"."]}]}]},"headings":[{"value":"Migration guide","id":"migration-guide","depth":1},{"value":"1.15 and above","id":"115-and-above","depth":2},{"value":"Migration process","id":"migration-process","depth":3},{"value":"Check for user conflicts","id":"check-for-user-conflicts","depth":3},{"value":"Fix user conflicts","id":"fix-user-conflicts","depth":3}],"frontmatter":{"seo":{"title":"Migration guide"}},"lastModified":"2025-11-04T23:32:34.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/custody/v1.26/get-started/deployment/migration-guide","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}