Skip to content

Configure Pachyderm with Keycloak

Keycloak is an open-source identity management solution that supports OIDC and provides authentication and authorization. When using Keycloak with Pachyderm, Keycloak is responsible for authorizing user access to your data that is stored in Pachyderm through identity and access tokens. For more information about Keycloak support for OIDC, see the Keycloak Documentation.


Although this section describes how to configure Keycloak with OIDC, you can configure SAML as well with the corresponding SAML auth config.


Before you can configure Pachyderm to work with Keycloak, you need to have the following components up and running:

  • Pachyderm Enterprise 1.11.x or later. The enterprise token must be activated by running echo <your-activation-token> | pachctl enterprise activate. Check the status of your license by running:
pachctl enterprise get-state

For more information, see Activate Pachyderm Enterprise Edition.

  • Keycloak must be running in your environment:

If you are just testing Keycloak with Pachyderm, you can run Keycloak in Minikube on your machine. Follow the instructions on how to set up Keycloak locally as described in Keycloak on Kubernetes.

If you are deploying in production, see Keycloak Documentation.

Configure Keycloak

After you have installed Pachyderm and Keycloak, follow the steps below to configure the two components to work together.

To configure Pachyderm with Keycloak, complete the following steps:

  1. Go to the Keycloak Administration Console. If you have deployed Keycloak on Minikube as described above, get the address of the console by running the following script:
KEYCLOAK_URL=https://keycloak.$(minikube ip) &&
echo "Keycloak Admin Console: $KEYCLOAK_URL/admin"

Example of System Response:

Keycloak Admin Console:
  1. Paste the link above to a browser and log in as admin. If you have used the instructions above to deploy Keycloak on Minikube, use the following credentials:

  2. username: admin

  3. password: admin

Keycloak login

  1. If you do not have one already, add a new realm. Otherwise, proceed to the next step.

A realm is a logically isolated group, similar to a tenant. By default, Keycloak predefines a Master realm for administrative purposes. You need to create a new realm for Pachyderm. For example, you can call it pachyderm.

  1. If you have created a new realm you need to add users to whom you want to grant access to Pachyderm. Create a user by clicking Users > Add user and filling out the required fields. Otherwise, proceed to the next step.

  2. Set up a password for this user by clicking Credentials and typing your password information.

    You might want to set the temporary password toggle to off so that your password does not expire.

  3. Create a client for Pachyderm:

  4. Click Clients > Create.

  5. Specify a client ID. For example, pachyderm-test.
  6. Set the Client Protocol to openid-connect.
  7. Set the Root URL to http://<ip>:30657/authorization-code/callback. For example:

    You can configure additional settings, such as require consent and so on, as needed, but this minimal configuration is everything you need to make Keycloak work with Pachyderm.

    Keycloak Client

  8. Proceed to Configure Pachyderm.

Configure Pachyderm

Now that you have Keycloak configured, you need to log in to Pachyderm with the user you have created in Keycloak.

To configure Pachyderm, complete the following steps:

  1. Go to the terminal and forward the pachd pod to the OIDC port:

  2. Get the pachd pod ID:

    kubectl get pod

    Example system response:

    dash-5768cb7d98-j6cgt       2/2     Running   0          4h2m
    etcd-56d897697-xzsqr        1/1     Running   0          4h2m
    keycloak-857c59449b-htg99   1/1     Running   0          4h6m
    pachd-79f7f68c65-9qs8g      1/1     Running   0          4h2m
  3. Forward the pachd pod to the OIDC port:


    kubectl port-forward pachd-79f7f68c65-9qs8g 30657
  4. Enable Pachyderm authentication:

pachctl auth activate --initial-admin=robot:admin

Pachyderm returns a token.

WARNING! You must save the token to a secure location to avoid being locked out of your cluster.

  1. Log in as the admin user with the token you received in the previous step:
pachctl auth use-auth-token
  1. Set up the authentication config:

    pachctl auth set-config <<EOF
            "live_config_version": 1,
            "id_providers": [{
            "name": "keycloak",
            "description": "oidc-based authentication with locally hosted keycloak",
                    "issuer": "http://keycloak.<ip><realm-name>",
                    "client_id": "<client-id>",
                    "redirect_uri": "http://<ip>:30657/authorization-code/callback"

    You need to replace the following placeholders with relevant values:

    • issuer — the URL to the location of your Keycloak realm.
    • ip — the IP of the Kubernetes host. If you are using Minikube, you can get the IP address by running minikube ip.

    • realm-name — the name of the Keycloak realm that you have created for Pachyderm. In the example, above it is called pachyderm.

    • client-id — the name of the Pachyderm's Keycloak client. In the example above, pachyderm-test.

    • redirect_uri — the URL that redirects back to Pachyderm. If you are running Pachyderm in Minikube, it is the Minikube IP address.

  2. Log in as the user you have created in the Pachyderm realm:

  3. Run:

    pachctl auth login

    Example of System Response:

    You will momentarily be directed to your IdP and asked to authorize
    Pachyderm\'s login app on your IdP.
    Paste the following URL into a browser if not automatically redirected:
    Retrieving Pachyderm token...
  4. Go to the browser and log in to the Pachyderm realm with the user you have previously created and no the admin user.

  5. If you have enabled Request consent, grant access to the realm by clicking Yes.

You should see the following message printed out in your browser:

You are now logged in. Go back to the terminal to use Pachyderm!
  1. In the terminal, check that you are logged in as the Keycloak user:
pachctl auth whoami

Example of System Response:

You are ""
session expires: 06 Aug 20 09:23 PDT

Modifying Realm Settings

If you make any changes, such as changing the protocol from OIDC to SAML in the Keycloak UI, you will have to update the Pachyderm authentication config as well. Just changing the protocol in the Keycloak UI will result in error the next time users log in.


Pachyderm authentication has the following limitations:

  • Only one identity provider can authenticate with Pachyderm at a time.
  • Group support is not available with OIDC.
  • Only one Keycloak realm can be configured with Pachyderm.

Last update: August 31, 2021
Does this page need fixing? Edit me on GitHub