This guides will only take into consideration migrating an existing connected app (for External Identity) to CYM-Identity
Make sure that you have :
- Onboarded a Community to CYM-Identity
- The realm to which the connected app will be migrated to is created
You'll need to create a Realm Resource Server which belongs to the community ExternalAuthServer created as part of the community onboarding.
It's mandatory that this resource server has at least one Protected Resource. We recommend to create a Protected Resource which point to the community's userinfo_endpoint.
You will also need to assign a scope to this ProtectedResource. We recommend that you create a scope migration which you assign to the ProtectedResource and to the App you'll create in the next section. This scope should only be used during the migration phase.
If your applications rely on the Salesforce Custom Claims, you'll need to create a Realm Plugin which will return the same information
- Navigate to the
profile scope of your Realm - Create a claim
custom_attributes - Add the required code to your Realm's plugin, or create a new one. See the claims section for more information.
You need to create a Client ClientApplication with the same information as the connected app you want to migrate
You can use the same redirect_uri, client_id, ... Only the client_secret will have to be regenerated
Add the migration scope to the Client as well
Besides the standard fields, you'll need to use Default Audience with the value of the Realm Resource Server you created above
Navigate to your existing connected app and make the following changes :
- Add the following scopes (if not already assigned) :
api & offline_access - Add a certificate to the connected app (You can use an existing certificate on your Org, download the public key and upload it to your connected app)
DO NOT DELETE THE CONNECTED APP
Navigate to your Client and add an ExternalClient child object
- The ExternalAuthServer must be the one referenced by your community and used in the RealmResourceServer
- Create an ExternalClient with the details from the existing ConnectedApp.
- Provide a name which will be used by the admin for reference
- Use the ConnectedApp client_id
- For grant_types, you can keep the
urn:ietf:params:oauth:grant-type:jwt-bearer - You can use whatever value for the token_endpoint_auth_method (The ExternalAuthServer for a community does not really use this value)
- Type
Username for the user_sub_field. This is a case sensitive field - You can skip the
client_sub for now. - Provide the certificate name you have used.
Now it's time to migrate the existing application from the Connected App to the CYM-Identity Client.
Provide the Application Developer with the new endpoints, credentials, ... to allow her to use CYM-Identity
So far, the goal of this migration was to allow your APIs to still receive valid Salesforce access_tokens which can be introspected on the standard Salesforce Introspection endpoint. We believe that this is a required step if your API has multiple consumers
The access_tokens also belong to the same existing connected app which implies that no authorization changes will be required at the API layer
You can onboard your existing APIs to CYM-Identity.
Once onboarded, there will be a period where the API may receive both Salesforce access_tokens and CYM-Identity JWTs.
When your API can accept both tokens, you can remove the default_audience from your Applications and allow them to move to JWTs.
- The access_tokens generated with this setup cannot be used for the
userinfo endpoint since they do not contain the OpenID Connect scopes (forbidden for external tokens).
It implies that your Application will have to solely rely on the id_token for user information.
On the other hand, you can use these access_tokens with the Standard Salesforce Community userinfo_endpoint. - The existing ConnectedApp cannot have a digital signature since the certificate needs to be replaced.
- The ConnectedApp cannot use the
Custom Permissions in the id_token - ConnectedApps using
Device Flow cannot be migrated - ConnectedApps with
Asset Tokens cannot be migrated - ConnectedApps with IP restrictions cannot be migrated