Managing Persons

Kaniop manages individual person accounts in your Kanidm cluster using the KanidmPersonAccount Custom Resource. This enables declarative user management with full Git-based workflows.

Basic Person Account

Here’s a simple person account configuration. You can reference the complete example at examples/person.yaml:

# Basic configuration - see examples/person.yaml for all options
apiVersion: kaniop.rs/v1beta1
kind: KanidmPersonAccount
metadata:
  name: alice
  namespace: default
spec:
  kanidmRef:
    name: my-idm
  personAttributes:
    displayname: Alice Smith
    mail:
      - alice@example.com

Advanced Configuration Options

The examples/person.yaml file demonstrates many additional features:

• Email aliases: Multiple email addresses with primary/secondary setup
• Legal names: Separate display and legal names
• Account lifecycle: accountValidFrom and accountExpire settings
• POSIX attributes: For SSH and filesystem access

Complete Person with All Attributes

# Extended example based on examples/person.yaml
apiVersion: kaniop.rs/v1beta1
kind: KanidmPersonAccount
metadata:
  name: john-doe
  namespace: default
  labels:
    department: engineering
    role: senior-developer
spec:
  kanidmRef:
    name: my-idm
  personAttributes:
    displayname: John Doe
    legalname: John Michael Doe
    mail:
      - john.doe@example.com
      - j.doe@example.com # Alias
    accountValidFrom: "2024-01-01T00:00:00Z"
    accountExpire: "2025-12-31T23:59:59Z"
  posixAttributes:
    gidnumber: 1000
    loginshell: /bin/bash

POSIX Account Configuration

For systems requiring POSIX compatibility (SSH, file systems), see the POSIX section in examples/person.yaml:

# POSIX configuration from examples/person.yaml
posixAttributes:
  gidnumber: 1000 # Auto-generated if omitted
  loginshell: /bin/bash

SSH Public Keys

SSH keys can be managed by tag. Kanidm validates the key format and supported key types; Kaniop does not parse or validate SSH key material.

spec:
  kanidmRef:
    name: my-idm
  personAttributes:
    displayname: Alice Smith
  sshPublicKeys:
    laptop: "ssh-ed25519 AAAA... alice@laptop"
    yubikey: "sk-ssh-ed25519@openssh.com AAAA... alice@yubikey"

The map is partially managed: Kaniop owns only the tags it has synchronized, so manually added SSH keys with other tags remain intact. Keys with a declared tag are adopted even when they already exist in Kanidm. The entire map is managed as a single server-side apply ownership unit, so applying an empty map transfers full ownership and revokes all previously managed keys.

This is an opt-in feature. The SshPublicKeysUpdated condition reports whether the declared keys and recorded tag ownership have converged. A rejected SSH key leaves the resource not ready and the Kanidm error is surfaced by reconciliation.

Key rotation warning: Kanidm does not replace an existing SSH key tag via insertion. Kaniop therefore deletes the previous key before adding the new key under the same tag. This operation is not atomic: if Kanidm rejects a replacement, the original key may already have been removed. Verify replacement public keys before rotating access-critical keys.

Account Lifecycle Management

Temporary Account

Create an account with an expiration date:

apiVersion: kaniop.rs/v1beta1
kind: KanidmPersonAccount
metadata:
  name: contractor
  namespace: default
spec:
  kanidmRef:
    name: my-idm
  personAttributes:
    displayname: Jane Contractor
    mail:
      - jane.contractor@example.com
    accountValidFrom: "2024-06-01T00:00:00Z"
    accountExpire: "2024-12-31T23:59:59Z"

Future-Dated Account

Create an account that becomes active on a specific date:

apiVersion: kaniop.rs/v1beta1
kind: KanidmPersonAccount
metadata:
  name: new-hire
  namespace: default
spec:
  kanidmRef:
    name: my-idm
  personAttributes:
    displayname: New Employee
    mail:
      - new.employee@example.com
    accountValidFrom: "2024-09-15T09:00:00Z"

Management Operations

Apply Person Changes

kubectl apply -f person.yaml

Check Person Status

kubectl get kanidmpersonaccounts
kubectl describe kanidmpersonaccount alice

Monitor Person Events

kubectl get events --field-selector involvedObject.name=alice

Update Person Attributes

Edit the YAML file and reapply:

kubectl apply -f person.yaml

Kaniop will detect changes and update the person account in Kanidm.

Best Practices

• Use email as identifier: Consider using email addresses as the metadata name for clarity
• Set expiration dates: Use accountExpire for temporary accounts (contractors, interns)
• Manage emails carefully: The first email in the list becomes the primary address
• Use labels: Add Kubernetes labels for organization and filtering
• Version control: Store all person manifests in Git for audit trails

Common Patterns

Department-Based Organization

apiVersion: kaniop.rs/v1beta1
kind: KanidmPersonAccount
metadata:
  name: engineering-alice
  namespace: default
  labels:
    department: engineering
    team: backend
    level: senior
spec:
  kanidmRef:
    name: my-idm
  personAttributes:
    displayname: Alice Smith
    mail:
      - alice.smith@example.com

Service Accounts

apiVersion: kaniop.rs/v1beta1
kind: KanidmPersonAccount
metadata:
  name: ci-service
  namespace: default
  labels:
    type: service-account
    purpose: ci-cd
spec:
  kanidmRef:
    name: my-idm
  personAttributes:
    displayname: CI/CD Service Account
    mail:
      - ci-cd@example.com

Multi-Environment Users

# Development environment
apiVersion: kaniop.rs/v1beta1
kind: KanidmPersonAccount
metadata:
  name: alice
  namespace: identity-dev
spec:
  kanidmRef:
    name: dev-idm
  personAttributes:
    displayname: Alice Smith (Dev)
    mail:
      - alice.dev@example.com
---
# Production environment
apiVersion: kaniop.rs/v1beta1
kind: KanidmPersonAccount
metadata:
  name: alice
  namespace: identity-prod
spec:
  kanidmRef:
    name: prod-idm
  personAttributes:
    displayname: Alice Smith
    mail:
      - alice@example.com

Troubleshooting

Account Not Created

Check the person resource status:

kubectl describe kanidmpersonaccount alice

Look for error messages in the Conditions section.

Email Conflicts

If you see conflicts with email addresses, ensure each email is unique across all person accounts in the same Kanidm cluster.

POSIX Issues

For POSIX-related problems, verify that gidnumber values don’t conflict with existing system or user IDs.