Introduction
In API Connect, user registries are used to hold user information for authentication to the API Connect platform. There are many user registry types available including: Local user registries, LDAP user registries and OIDC user registries.
User registries are available on the provider side for authentication to Cloud Manager or API Manager or for API authentication. There are also user registries available on the consumer side for authentication to the Developer Portal.
This article discusses how to migrate consumer users from one user registry type to another User registry type. The example used is for migration from an LDAP user registry to an OIDC user registry.
Set-up
In this example API Connect v10.0.8.1 is installed as a Cloud Pak for Integration (CP4I) installation on Red Hat OpenShift. One of the advantages of installing as part of CP4I is automatic configuration of the API Connect cloud topology and creation of the OIDC user registry provided by Keycloak which will be used in this example.
A remote LDAP instance has been created containing two users: ‘example’ and ‘secondexample’.
Two users have also been created in Keycloak: ‘example’ and ‘secondexample’.
A catalog has been created in API Connect called portal-test with a portal enabled. A consumer org has been created called ‘test’. The LDAP user registry has been enabled as the only user registry that can be used to authenticate with the portal. The LDAP ‘example’ user has been set as the consumer org owner and LDAP ‘secondexample’ has been added as an Administrator consumer org user/member.
The API Connect CLI toolkit is leveraged to migrate the ‘example’ and ‘secondexample’ users from the LDAP user registry (called ‘ldap’) to the Keycloak OIDC user registry (called ‘integration-keycloak’).
The ‘secondexample’ user is migrated first, followed by the ‘example’ user.
Steps
Migrating the secondexample user
1. Enable the Keycloak OIDC user registry for Portal login
a. In API Manager select ‘Manage catalogs’ > ‘portal-test’ > ‘Catalog settings’ > ‘Onboarding’
b. Click ‘Edit’ next to Catalog user registries and enable the Cloud Pak User Registry (OIDC) > ‘Save’
2. Login to the API Connect server using the Provider realm as an Administrator using the toolkit
apic login --server <Platform API Endpoint> --realm provider/default-idp-2 --username <Provider Org Admin User>
Enter the user password when prompted
3. List the members of the consumer-org
apic members:list --server <Platform API Endpoint> --org test --scope consumer-org --catalog portal-test --consumer-org test
Output
secondexample [state: enabled] https://<Member URL>
example [state: enabled] https://<Member URL>
4. For each member, get the member information in order to extract the email address
apic members:get --server <Platform API Endpoint> --org test --scope consumer-org --catalog portal-test --consumer-org test --format json <member-id from step 2 (last segment in the URL path)>
This will output to a JSON file
Output
type: 'member'
api_version: '2.0.0'
id: '00000000000'
name: 'secondexample'
title: 'secondexample'
state: 'enabled'
scope: 'consumer_org'
user:
id: '00000000000'
url: '<User URL>'
name: 'secondexample'
type: 'user'
email: 'secondexample@ibm.com'
state: 'enabled'
title: 'secondexample'
org_url: '<Org URL>'
metadata: {}
username: 'secondexample'
last_name: 'user'
first_name: 'secondexample'
api_version: '2.0.0'
identity_provider: 'ldap'
user_registry_url: '<User Registry URL>'
role_urls:
- '<Role URL>'
org_url: '<Org URL>'
catalog_url: '<Catalog URL>'
consumer_org_url: '<Consumer Org URL>'
5. Delete the ‘secondexample’ member
apic members:delete --server <Platform API Endpoint> --org test --scope consumer-org --catalog portal-test --consumer-org test secondexample
Output
secondexample [state: enabled] https://<Member URL>
6. Confirm that the member has been deleted
apic members:list --server <Platform API Endpoint> --org test --scope consumer-org --catalog portal-test --consumer-org test
Output
example [state: enabled] https://<Member URL>
7. List the users in the LDAP user registry
apic users:list --server <Platform API Endpoint> --org test --user-registry ldap
Output
example [state: enabled] https://<User URL>
secondexample [state: enabled] https://<User URL>
8. Delete the ‘secondexample’ user from the LDAP user registry
apic users:delete --server <Platform API Endpoint> --org test --user-registry ldap secondexample
Output
secondexample [state: enabled] https://<User URL>
9. Confirm that the user has been deleted
apic users:list --server <Platform API Endpoint> --org test --user-registry ldap
Output
example [state: enabled] https://<User URL>
10. Create a user.yaml for the OIDC ‘secondexample’ user
---
type: 'user'
api_version: '2.0.0'
name: 'secondexample'
title: 'secondexample'
state: 'enabled'
identity_provider: 'integration-keycloak'
username: 'secondexample'
email: 'secondexample@ibm.com'
first_name: 'secondexample'
last_name: 'user'
11. Create the ‘secondexample’ user in the OIDC user registry
apic users:create --server <Platform API Endpoint> --org test --user-registry integration-keycloak user.yaml
Output
secondexample [state: enabled] https://<User URL>
12. Extract the Administrator role URL
apic roles:list --scope consumer-org --catalog portal-test --org test --consumer-org test --server <Platform API Endpoint>
administrator https://<Role URL>
developer https://<Role URL>
member https://<Role URL>
owner https://<Role URL>
viewer https://<Role URL>
13. Create the ‘secondexample’ member.yaml file with the owner role
---
type: 'member'
api_version: '2.0.0'
name: 'secondexample'
title: 'secondexample'
state: 'enabled'
scope: 'consumer_org'
user:
url: '<User URL>'
name: 'secondexample'
type: 'user'
email: 'secondexample@ibm.com'
state: 'enabled'
title: 'secondexample'
username: 'secondexample'
last_name: 'user'
first_name: 'secondexample'
api_version: '2.0.0'
identity_provider: 'integration-keycloak'
role_urls:
- '<Role URL>'
14. Create the ‘secondexample’ OIDC user as a member of the consumer-org
apic members:create --server <Platform API Endpoint> --org test --scope consumer-org --catalog portal-test --consumer-org test member.yaml
Output
secondexample [state: enabled] https://<Member URL>
15. Login to the Portal using the OIDC ‘secondexample’ user
Transfer ownership of consumer-org to secondexample user
16. Create the transfer_owner.yaml file
new_owner_member_url: "<Member URL>"
17. Transfer the ownership of the consumer-org to the ‘secondexample’ user
apic consumer-orgs:transfer-owner --server <Platform API Endpoint> --org test --catalog portal-test test transfer_owner.yaml
Output
test [state: enabled] https://<Consumer Org URL>
18. Repeat steps 3-13 for the ‘example’ user to migrate from the LDAP user registry to the OIDC user registry
Transfer ownership of consumer-org back to the example OIDC user
19. Create the transfer_owner_2.yaml file
new_owner_member_url: "<New Member URL>”
old_owner_new_role_urls:
- "<Role URL>"
20. Apply the transfer_owner_2.yaml file
apic consumer-orgs:transfer-owner --server <Platform API Endpoint> --org test --catalog portal-test test transfer_owner_2.yaml
21. Login as the OIDC ‘example’ user
Conclusion
The result of steps followed is that the ‘example’ owner and ‘secondexample’ member of the consumer_org have been successfully migrated from the LDAP user registry to the OIDC user registry.
Special thanks to Nick Cawood and Aiden Gallagher