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

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 auto-generated secret:

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:

Port-forward to your Kanidm service:

kubectl port-forward svc/my-idm 8443:8443 -n default

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:

Log in to the Web UI using the admin credentials (see above)
Get the credential reset link by describing the person account:
```
kubectl describe kanidmpersonaccount me
```
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:

examples/kanidm-ingress.yaml - Kanidm with Ingress configuration
examples/kanidm-replication.yaml - Multi-replica setup with storage

What’s Next?

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

Kaniop Documentation