Charmed Ory Kratos

Description

This repository hosts the Kubernetes Python Operator for Ory Kratos - an API-first identity and user management system. For more details, visit https://www.ory.sh/docs/kratos/ory-kratos-intro.

Usage

The Kratos Operator may be deployed using the Juju command line as follows:

juju deploy postgresql-k8s --channel 14/stable --trust --config plugin_pg_trgm_enable=True plugin_btree_gin_enable=True
juju deploy kratos
juju integrate kratos postgresql-k8s

Interacting with Kratos API

Below are two examples of the API. Visit Ory to see full API specification.

Create Identity

curl <kratos-service-ip>:4434/identities \
--request POST -sL \
--header "Content-Type: application/json" \
--data '{
  "schema_id": "default",
  "traits": {
    "email": "test@example.org"
  }
}'

Get Identities

curl <kratos-service-ip>:4434/admin/identities

You should be able to see the identity created earlier.

Integrations

PostgreSQL

This charm requires an integration with postgresql-k8s-operator.

Ingress

The Kratos Operator offers integration with the traefik-k8s-operator for ingress. Kratos has two APIs which can be exposed through ingress, the public API and the admin API.

If you have a traefik deployed and configured in your kratos model, to provide ingress to the admin API run:

juju integrate traefik-admin kratos:admin-ingress

To provide ingress to the public API run:

juju integrate traefik-public kratos:public-ingress

SMTP Server Integration

In order to turn Kratos into a functional identity provider, an outgoing mail server must be integrated. It can be done using the smtp interface.

If you have a self-hosted SMTP server independent of the juju ecosystem, deploy the smtp-integrator charm, configure it with the required server details and integrate with Kratos:

juju deploy smtp-integrator --channel latest/edge
juju config smtp-integrator user=<username> password=<pwd> host=<hostname> port=<port> transport_security=<none|tls|starttls> skip_ssl_verify=<True|False>
juju integrate smtp-integrator:smtp kratos

Mailslurper is recommended for local development.

External Provider Integration

Kratos can be used as an identity broker. To connect Kratos with an external identity provider you can use the external provider integration. All you need to do is deploy the kratos-external-idp-integrator, configure it and integrate it with Kratos:

juju deploy kratos-external-provider-integrator
juju config kratos-external-provider-integrator \
    client_id={client_id} \
    client_secret={client_secret} \
    provider={provider}
juju integrate kratos-external-provider-integrator kratos

Once kratos has registered the provider, you will be able to retrieve the redirect_uri from the integrator by running:

juju run {external_provider_integrator_unit_name} get-redirect-uri --wait

Hydra

This charm offers integration with hydra-operator.

In order to integrate kratos with hydra, it needs to be able to access hydra's admin API endpoint. To enable that, integrate the two charms:

juju integrate kratos hydra

For further guidance on integration on hydra side, visit the hydra-operator repository.

Identity Platform Login UI

The following instructions assume that you have deployed traefik-admin and traefik-public charms and integrated them with Kratos. Note that the UI charm should run behind a proxy.

This charm offers integration with identity-platform-login-ui-operator. In order to integrate them, run:

juju integrate kratos:ui-endpoint-info identity-platform-login-ui-operator:ui-endpoint-info
juju integrate identity-platform-login-ui-operator:kratos-info kratos:kratos-info

Actions

The kratos charm offers the following actions:

create-admin-account

This action can be used to create an admin account. The password can be set to a specified value by passing password-secret-id as an action parameter.

To create a juju secret holding the password and grant it to kratos, run:

juju add-secret <secret-name> password=<new-password>
secret:cql684nmp25c75sflot0
juju grant-secret <secret-name> kratos

To create the admin account:

juju run kratos/0 create-admin-account username=admin123 password-secret-id=secret:12345678 email=admin@example.com

NOTE: The email registered for an admin account must not be used for any other user (admin or not).

get-identity

This action can be used to get information about an existing identity by email or id:

By id:

juju run kratos/0 get-identity identity-id={identity_id}

By email:

juju run kratos/0 get-identity email={email}

delete-identity

This action can be used to delete an existing identity. An identity_id can be used to specify the identity:

juju run kratos/0 delete-identity identity-id={identity_id}

An email can be used to specify the identity as well:

juju run kratos/0 delete-identity email={email}

reset-password

This action can be used to reset password of an identity by its email or id. The password can be set to a specified value by passing password-secret-id as an action parameter.

To create a juju secret holding the password and grant it to kratos, run:

juju add-secret <secret-name> password=<new-password>
secret:cql684nmp25c75sflot0
juju grant-secret <secret-name> kratos

Then, run the action using identity id:

juju run kratos/0 reset-password identity-id={identity_id} password-secret-id=secret:cql684nmp25c75sflot0

Or email:

juju run kratos/0 reset-password email={email} password-secret-id=secret:cql684nmp25c75sflot0

If password-secret-id parameter is not provided, the action will return a self-service recovery code and link to reset the password.

invalidate-identity-sessions

This action can be used to invalidate all user sessions using either the identity id or email.

By id:

juju run kratos/0 invalidate-identity-sessions identity-id={identity_id}

By email:

juju run kratos/0 invalidate-identity-sessions email={email}

reset-identity-mfa

This action can be used to reset identity's second authentication factor using either the identity id or email. The type of credentials to be removed must be specified, supported values are totp and lookup_secret.

By id:

juju run kratos/0 reset-identity-mfa identity-id={identity_id} mfa-type={totp|lookup_secret}

By email:

juju run kratos/0 reset-identity-mfa email={email} mfa-type={totp|lookup_secret}

run-migration

This action can be used to trigger a database migration:

juju run kratos/0 run-migration

OCI Images

The image used by this charm is hosted on Docker Hub and maintained by Ory.

Security

Security issues in IAM stack can be reported through LaunchPad. Please do not file GitHub issues about security issues.

Contributing

Please see the Juju SDK docs for guidelines on enhancements to this charm following best practice guidelines, and CONTRIBUTING.md for developer guidance.

License

The Charmed Kratos Operator is free software, distributed under the Apache Software License, version 2.0. See LICENSE for more information.