This documentation is for v0.14 and not the latest stable release. View the latest documentation →

Kaniop Documentation

    Quickstart

    This quickstart will guide you through deploying a Kanidm cluster with Kaniop and creating your first identity resources. In about 10 minutes, you’ll have a fully functional identity management system running on Kubernetes.

    Prerequisites

    • A Kubernetes cluster (v1.20+)
    • kubectl configured to access your cluster
    • Helm v3 installed

    Step 1: Install the Operator

    Install the Kaniop operator using Helm:

    helm install --create-namespace --namespace kaniop --wait kaniop oci://ghcr.io/pando85/helm-charts/kaniop

    Verify the operator is running:

    kubectl get pods -n kaniop
# Expected output: kaniop-<release-name> pod in Running state

    Step 2: Deploy a Kanidm Cluster

    Create a simple Kanidm cluster configuration. You can use the basic example from the repository:

    # Use the basic Kanidm example
kubectl apply -f https://raw.githubusercontent.com/pando85/kaniop/master/examples/kanidm-tls.yaml
kubectl apply -f https://raw.githubusercontent.com/pando85/kaniop/master/examples/kanidm.yaml

    Wait for the StatefulSet to be ready:

    kubectl get statefulsets -l kanidm.kaniop.rs/cluster=my-idm
kubectl wait --for=condition=ready pod -l kanidm.kaniop.rs/cluster=my-idm --timeout=300s

    Automatic Administrator Bootstrap

    Kaniop automatically runs account recovery for the built-in admin and idm_admin accounts when the Kanidm instance is first initialized. It stores the generated credentials in the <kanidm-name>-admin-passwords Secret and uses them internally when reconciling identity resources. You do not need to provide administrator credentials in KanidmPersonAccount, KanidmGroup, or KanidmOAuth2Client resources.

    Do not run kanidmd recover-account admin or kanidmd recover-account idm_admin manually after Kaniop has initialized the instance. Account recovery rotates the password in Kanidm, which makes the credentials stored by Kaniop stale and can cause managed resources to fail with AuthenticationFailed.

    If you already rotated either account manually, delete the generated Secret and let Kaniop bootstrap the credentials again:

    kubectl delete secret my-idm-admin-passwords

    Step 3: Configure OAuth2 Client

    Set up an OAuth2 client using the repository example:

    # Use the OAuth2 client example
kubectl apply -f https://raw.githubusercontent.com/pando85/kaniop/master/examples/oauth2.yaml

    You can verify it with:

    kubectl get kanidmoauth2clients

    Step 4: Create a Group

    Create a group using the repository example:

    # Use the group example
kubectl apply -f https://raw.githubusercontent.com/pando85/kaniop/master/examples/group.yaml

    Verify the group was created:

    kubectl get kanidmgroups

    Step 5: Create a Person Account

    Create a user account using the example from the repository:

    # Use the person example
kubectl apply -f https://raw.githubusercontent.com/pando85/kaniop/master/examples/person.yaml

    Verify the account was created and get the link to set the credentials:

    kubectl get kanidmpersonaccounts
kubectl describe kanidmpersonaccount me

    Step 6: Access Your Kanidm Instance

    After setting up your Kanidm cluster, you’ll need to log in to manage your identity resources. Here’s how to access your instance:

    Admin Access

    Retrieve the admin credentials from the Secret created during automatic administrator bootstrap:

    kubectl get secret my-idm-admin-passwords -o jsonpath='{.data.ADMIN_PASSWORD}' | base64 -d

    This secret contains:

    • ADMIN_USERNAME and ADMIN_PASSWORD for the admin user
    • IDM_ADMIN_USERNAME and IDM_ADMIN_PASSWORD for the idm_admin user

    Accessing the Web UI

    To access the Kanidm web interface:

    1. Port-forward to your Kanidm service: 
      kubectl port-forward svc/my-idm 8443:8443 -n default
    2. Open https://localhost:8443 in your browser

    Alternatively, you can expose the Kanidm UI through an Ingress for persistent access. See the Ingress example for configuration details.

    Person Account Credentials

    To set up credentials for the person account you created:

    1. Log in to the Web UI using the admin credentials (see above)

    2. Get the credential reset link by describing the person account: 
      kubectl describe kanidmpersonaccount me
    3. Open the resetLink in your browser and set a password for the account (the link is valid for 1 hour by default, configurable via credentialsTokenTtl)

    Note that the admin user has full privileges while person accounts have limited access based on their assigned permissions.

    Step 7: Create a Service Account

    Create a service account using the example from the repository:

    kubectl apply -f https://raw.githubusercontent.com/pando85/kaniop/master/examples/service-account.yaml

    Verify the service account was created:

    kubectl get kanidmserviceaccounts

    Next Steps

    Congratulations! You now have:

    • A running Kanidm cluster managed by Kaniop
    • An OAuth2 client (my-service) for application integration
    • A group (my-group) for organizing users
    • A user account (me) ready for configuration

    Explore More Examples

    The examples/ directory contains additional configurations:

    What’s Next?

    1. Installation Guide: Learn about production-ready configurations and customize your Kaniop deployment with Helm values
    2. Usage Guide: Dive deeper into managing persons, groups, and OAuth2 clients