🔐 Authenticating to Keycloak

🔐 Authenticating to Keycloak#

To authenticate to Keycloak, you can either use a username+password, or client credentials (client ID+client secret, also known as service account).

The library takes care of fetching a token the first time you need it and keeping it fresh. By default, it tries to use the refresh token (if available) and always guarantees the token is valid for the next 30 seconds.

The authentication calls and the calls to the REST API use the same requests.Session, which can be passed at creation in case you need to add custom headers, proxies, etc.

Important

A KeycloakAdmin client is meant to interact with a single realm. It is however possible to use another realm for authentication. You may change realms by setting realm_name, but this requires your token to have permissions spanning realms (e.g. authentication using the admin user).

Authenticating with username + password#

Ensure your user has the right to interact with the endpoints you are interested in. In doubt or for testing, you can either use the admin user (not recommended) or create a user and assign it the realm-management:realm-admin role (full access).

Hint

Clients must enable the “Direct access grants” authorization flow. The client admin-cli, which exists by default on all realms, is often used.

Here is how to use from_username_password() connect to the default realm with the admin user and admin-cli client:

from mantelo import KeycloakAdmin

client = KeycloakAdmin.from_username_password(
    server_url="http://localhost:8080", # base Keycloak URL
    realm_name="master",
    # ↓↓ Authentication
    client_id="admin-cli",
    username="admin",
    password="CHANGE-ME", # TODO
)

This client will be able to make calls only to the master realm. If you want to authenticate to a realm that is different from the one you want to query, use the argument authentication_realm:

from mantelo import KeycloakAdmin

client = KeycloakAdmin.from_username_password(
    server_url="http://localhost:8080", # base Keycloak URL
    realm_name="my-realm", # realm for querying
    # ↓↓ Authentication
    authentication_realm_name="master", # realm for authentication only
    client_id="admin-cli",
    username="admin",
    password="CHANGE-ME",
)

Authenticating with client credentials (client ID + secret)#

It is also possible to authenticate through an OIDC client with a confidential access type.

Hint

A confidential client should:

  • have “Client authentication” enabled,

  • support the “Service accounts roles” authentication flow,

  • have one or more service account roles granting access to Admin endpoints.

Go to your client’s “Credentials” tab to find the client secret.

Here is how to use from_client_credentials() connect with a client:

from mantelo import KeycloakAdmin

client = KeycloakAdmin.from_client_credentials(
    server_url="http://localhost:8080", # base Keycloak URL
    realm_name="master",
    # ↓↓ Authentication
    client_id="my-client-name",
    client_secret="59c3c211-2e56-4bb8-a07d-2961958f6185",
)

This client will be able to make calls only to the master realm. If you want to authenticate to a realm that is different from the one you want to query, use the argument authentication_realm:

from mantelo import KeycloakAdmin

client = KeycloakAdmin.from_client_credentials(
    server_url="http://localhost:8080", # base Keycloak URL
    realm_name="my-realm", # realm for querying
    # ↓↓ Authentication
    authentication_realm_name="master", # realm for authentication only
    client_id="my-client-name",
    client_secret="59c3c211-2e56-4bb8-a07d-2961958f6185",
)

Other ways of authenticating#

The supported authentication methods should be enough. If you need more, a pull request or an issue is welcome! But just in case, here are some ways to make it more complicated 😉.

To create a KeycloakAdmin, you only need a method that returns a token. For example, you can use an existing token directly (not recommended, as tokens are short-lived):

from mantelo.client import BearerAuth, KeycloakAdmin

KeycloakAdmin(
    server_url="http://localhost:8080",
    realm_name="master",
    auth=BearerAuth(lambda: "my-token"),
)

If you want to go further, you can create your own Connection class (or extend the OpenidConnection), and pass its token() method to the BearerAuth:

from mantelo.client import BearerAuth, KeycloakAdmin
from mantelo.connection import Connection

class MyConnection(Connection):
    def token(self):
        return "<do-something-here>"

connection = MyConnection()

KeycloakAdmin(
    server_url="http://localhost:8080",
    realm_name="master",
    auth=BearerAuth(connection.token),
)