Export users and roles from Keycloak

Question

I created users and roles in Keycloak which I want to export.

When I tried to export them using the realm's "Export" button in UI I got a JSON file downloaded.

But I couldn't find any users or roles in the exported file realm.json

How can I export a realm JSON including users and roles from Keycloak?

Answer 1

Update: The /auth path was removed starting with Keycloak 17 Quarkus distribution. So you might need to remove the /auth from the endpoint calls presented on this answer.

---

You will not be able to do that using the export functionality. However, you can get that information using the Keycloak Admin REST API; to call that API, you need an access token from a user with the proper permissions. For now, I will be using the admin user from the master realm, but later I will explain how you can use another user:

curl https://$KEYCLOAK_HOST/auth/realms/master/protocol/openid-connect/token \
    -d "client_id=admin-cli" \
    -d "username=$ADMIN_NAME" \
    -d "password=$ADMIN_PASSWORD" \
    -d "grant_type=password"

You will get a JSON response with the admin's token. Extract the value of property access_token from that response. Let us save it in the variable $ACCESS_TOKEN for later reference.

To get the list of users from your realm $REALM_NAME:

curl -X GET https://$KEYCLOAK_HOST/auth/admin/realms/$REALM_NAME/users \
     -H "Content-Type: application/json" \
     -H "Authorization: bearer $ACCESS_TOKEN"

To get the realm roles:

curl -X GET https://$KEYCLOAK_HOST/auth/admin/realms/$REALM_NAME/roles \
     -H "Content-Type: application/json" \
     -H "Authorization: bearer $ACCESS_TOKEN"

Now you just need to save the JSON responses from those endpoints into JSON files.

Assigning the proper user permissions

For those that do not want to get an access token from the master admin user, you can get it from another user but that user needs the permission view-users from the realm-management client. For that you can:

(OLD Keycloak UI)

• Go to Users, and then the user in question
• Go to the tab Role Mappings
• In client roles select realm-management
• Select the role view-users and click on Add selected

(New Keycloak UI)

• Go to Users, and then the user in question
• Go to the tab Role Mappings
• Click on Assign role
• In Search by role name type view-users
• Select the role and assign it

Answer 2

When following the guide from dreamcrash to export users and roles, you might want to achieve all in one script:

1. export the realm as JSON like done with UI button
2. get and add the users array to this JSON
3. get and add the roles array to this JSON

You can use the command-line tool jq to integrate all 3 JSON parts:

# define the variables: url, credentials to access REST API, and the realm to export
KEYCLOAK_URL="https://localhost:8080"
KEYCLOAK_REALM="master"
KEYCLOAK_USER="admin"
KEYCLOAK_SECRET="secret"
REALM_NAME="myRealm"

# obtain the access token
ACCESS_TOKEN=$(curl -X POST "${KEYCLOAK_URL}/auth/realms/${KEYCLOAK_REALM}/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=${KEYCLOAK_USER}" \
  -d "password=${KEYCLOAK_SECRET}" \
  -d "grant_type=password" \
  -d 'client_id=admin-cli' \
  | jq -r '.access_token')

# export the realm as JSON
curl -X GET "${KEYCLOAK_URL}/auth/admin/realms/${REALM_NAME}"
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  > keycloak_${REALM_NAME}_realm.json

# export the users
curl -X GET "${KEYCLOAK_URL}/auth/admin/realms/${REALM_NAME}/users" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  > keycloak_${REALM_NAME}_users.json

# export the roles
curl -X GET "${KEYCLOAK_URL}/auth/admin/realms/${REALM_NAME}/roles" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  > keycloak_${REALM_NAME}_roles.json

# integrate all 3 using jq's slurp
jq -s '.[0] + {users:.[1], roles:.[2]}' \
  keycloak_${REALM_NAME}_realm.json \ 
  keycloak_${REALM_NAME}_users.json \
  keycloak_${REALM_NAME}_roles.json \
  > keycloak_${REALM_NAME}_realm-incl-users-roles.json

The resulting file keycloak_${REALM_NAME}_realm-incl-users-roles.json may then look like this simplified example:

{
  "realm": "master",
  "users": [
    {
      "id": "user1"
    },
    {
      "id": "user2"
    }
  ],
  "roles": [
    {
      "id": "role1"
    },
    {
      "id": "role2"
    }
  ]
}

Answer 3

Using Keycloak standalone:

bin\kc.bat export --file realm_export.json --realm test_realm --users realm_file

as described in the documentation here https://www.keycloak.org/server/importExport