Search code examples
keycloakkeycloak-rest-api

Why does keycloak hide the "Service-account-admin-cli" user under "Users" section?

I was trying to call keycloak's REST api to create new users under a realm and I was following this tutorial: https://www.appsdeveloperblog.com/keycloak-rest-api-create-a-new-user/

I was able to configure the Admin-cli client as below: enter image description here and I was able to get the access token by using the client id and secret: enter image description here

However, when I make a POST request to /auth/admin/realms/myapp/users with the bearer token, it fails to create a user and I got an "unknow_error"

I searched through the internet and community and documentation but there was no clue. Eventually after hours and hours of trying, I found a solution:

You need to first go to clients --> admin_cli --> Sessions: enter image description here

Then click on the user "Service-account-admin-cli" and configure such that it has admin role enter image description here

Then, the previous POST request will successfully create a new user.

I cannot understand why this user "Service-account-admin-cli" is hidden under the users section: enter image description here

Why would it be hidden??? How are people supposed to find this user (Service-account-admin-cli) and configure it? Does keycloak expect people to find it by clicking clients --> admin_cli --> Sessions and then see the user from there??

Solution

  • IMO, one should avoid using the master Realm or touching the admin_cli configuration without a very good reason.

    From the Keycloak documentation one can read:

    When you boot Keycloak for the first time Keycloak creates a pre-defined realm for you. This initial realm is the master realm. It is the highest level in the hierarchy of realms. Admin accounts in this realm have permissions to view and manage any other realm created on the server instance. When you define your initial admin account, you create an account in the master realm. Your initial login to the admin console will also be via the master realm.

    We recommend that you do not use the master realm to manage the users and applications in your organization. Reserve use of the master realm for super admins to create and manage the realms in your system. Following this security model helps prevent accidental changes and follows the tradition of permitting user accounts access to only those privileges and powers necessary for the successful completion of their current task.

    So typically, one would create a different realm and create the users there. Unless one wants to create admin-alike users.

    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.

    That being said, to create the user using Keycloak's Rest API, one requests from the admin-cli client a token on behalf of the admin user, for instance:

    TOKEN=$(curl -k -sS   -d "client_id=admin-cli" \
                      -d "username=$ADMIN_NAME" \
                      -d "password=$ADMIN_PASSWORD" \
                      -d "grant_type=password" \
                      https://$KEYCLOAK_IP/auth/realms/master/protocol/openid-connect/token)

    from the $TOKEN object extract the access token (let us named $ACCESS_TOKEN).

    And then create the user as follows:

    curl -k -sS -X POST https://$KEYCLOAK_IP/auth/admin/realms/$REALM_NAME/users \
        -H "Content-Type: application/json" \
        -H "Authorization: Bearer $ACCESS_TOKEN" \
        -d "$USER_JSON_DATA"

    $USER_JSON_DATA will be the json data representation of the user to be created. There is no need to add the role admin to the master admin deployed with Keycloak by default.

    Does keycloak expect people to find it by clicking clients --> admin_cli --> Sessions

    If setup normally, you would just need to know (as I already described) the admin's name and password, which is configured in the initial setup anyway.

    Following this setup then you:

    You need to first go to clients --> admin_cli --> Sessions:

    you would see the following:

    enter image description here

    The difference now is that if you click on the admin user > roles, you would see the following:

    enter image description here

    The admin user, has already the admin role. No need for:

    configure such that it has admin role

    Now if you change the admin_cli configuration exactly as you did then you need to add to the Service-account-admin-cli user the role admin.

    I cannot understand why this user "Service-account-admin-cli" is hidden under the users section:

    It is an implementation detail; unfortunately, I could not find online a an explanation for that either. But I do agree that without further context, it does not look very user-friendly. Now that begs the question of why the tutorial did not warn their readers about it.

    Now, if one speculate a bit, the reason to hide that user from the list of users could be because:

    1. it is not a real user in the conventional sense; not meant to be used to login into Keycloak. If you try to set the password of that user you get always an error.

    2. the list of users is for the users explicitly created for that realm that one can actually explicitly authenticate. In other words, "Service-account-admin-cli" is used so that it represents the "one" performing the call to the admin-cli, since when one changes the grand type from password to client-credentials there is no explicit user authentication anymore (i.e., admin username and password). So "Service-account-admin-cli" is used as a place holder.

    Naturally, one could argue, Why not just make "Service-account-admin-cli" have the admin role by default?!, but again, it is implementation details that only the developers behind them can justify.

    Another good reason to not blindly change the original setup of the admin-cli.