How To Set Up the Dev Portal From Scratch In a New Realm

This topic explains how to set up the dev portal in a new realm, starting by creating a new realm based on an existing realm. This document attempts to be as comprehensive as possible, but each situation is unique. You may need to problem solve.

The steps below should be followed in order:

Access Requests

Before beginning, you will need to make the following Okta access requests for the MTE you are working in:

  • Keycloak admin access

  • AWS console admin access

Create the New Realm

Export the existing realm

  1. Go to the realm in Keycloak, and go to ‘Realm Settings’. In the upper right there will be an ‘Actions’ dropdown, where you will find ‘Partial Export’.

  2. Select this and you can choose whether to include roles and groups and client data.

  3. Click ‘export’ and you will download a JSON config file of all of the realm settings. There is an example of a realm backup config file here (Google Drive).

Edit the JSON file

Optional - change the name or any other data you need to change.

Required - remove Keycloak id’s

These are all of the fields with the key “id”. Additionally, you may see some with the key “internalId”. You will want to remove all of these from the file.

If you try to import a file as a new realm with these fields, you will get 409 conflict errors. That is because these are the id’s that Keycloak stores in its database and must be unique for the entire deployment of Keycloak (MTE in our case, such as 1upcoredev or 1upcoreqa). These id fields are different than the id’s we use to identify objects such as clientId. Client id’s and similar are unique to realms but not to MTE - the same client id’s can exist in different realms within 1upcoredev

Upload the new realm

  1. Make sure you are in the master realm in your MTE (the realm identified in the upper left realm selector in Keycloak as ‘Keycloak Master’).

  2. From the realm selector dropdown, select ‘Create Realm’, and upload the JSON file.

  3. If you have problems, you will want to look at the Keycloak logs. For a deployed environment like 1upcoredev, these are in ArgoCD:

Steps for Viewing Keycloak Logs

  1. Set up strongDM client if you have not.

  2. Connect to https://1up-core-dev-dev-argocd-ui.1uphealth.sdm.network/ in strongDM

  3. Click the green arrow next to https://1up-core-dev-dev-argocd-ui.1uphealth.sdm.network/. This brings you to the ArgoCD app.

  4. Log in with username: admin password: uzCWnUoPR0hsV3Ej for core-dev

  • running this command should get you the password for other environments: aws eks update-kubeconfig --name mte-argo-cd-core --profile 1up-core-xxx-admin kubectl get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d

  • username is always admin

  1. Search for 'Gateway', there will be a Gateway app. Click into it.

  2. One of the pods in the gateway app is for Keycloak. The pods are the furthest-right layer of the tree/diagram. In core-dev, this is named gateway-1up-gateway-keycloak-5b7ddb855-fdd8l). Click into this pod, and there is a tab for logs.

  1. Then make sure you have the following in the master realm:

  • 1up-employee-{realm-name} in the groups tab

  • admin-{realm-name} client in the clients tab. The client secret for this client should go in parameter store (see this step)

  1. Set Group Permissions

You created the realm, so you can automatically see it. But make sure someone else can, and if they cannot, you may need to add permissions to the group they're in (in this case 1up-employee-1upcorestage).

Delete the new realm

If you want to delete the new realm created because you noticed an error somewhere so you can recreate the same realm after adjusting the JSON file:

  • Go to your new realm → realm settings → actions → delete

  • Go to master realm and delete the following:

    • admin-[realm name] from the clients tab

    • 1up-employee-[realm name] from the groups tab

More text ......