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.
The Kratos Operator may be deployed using the Juju command line as follows:
juju deploy postgresql-k8s --channel edge --trust
juju deploy kratos
juju integrate kratos postgresql-k8s
Below are two examples of the API. Visit Ory to see full API specification.
curl <kratos-service-ip>:4434/identities \
--request POST -sL \
--header "Content-Type: application/json" \
--data '{
"schema_id": "default",
"traits": {
"email": "[email protected]"
}
}'
curl <kratos-service-ip>:4434/admin/identities
You should be able to see the identity created earlier.
This charm requires an integration with postgresql-k8s-operator.
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
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.
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
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.
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-endpoint-info kratos:kratos-endpoint-info
The kratos charm offers the following actions:
This action can be used to create an admin account:
juju run kratos/0 create-admin-account username=admin123 password=abc123456 [email protected]
NOTE: The email registered for an admin account must not be used for any other user (admin or not).
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}
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}
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.
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}
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}
This action can be used to trigger a database migration:
juju run kratos/0 run-migration
The image used by this charm is hosted on Docker Hub and maintained by Ory.
Security issues in IAM stack can be reported through LaunchPad. Please do not file GitHub issues about security issues.
Please see the Juju SDK docs for guidelines on enhancements to this charm following best practice guidelines, and CONTRIBUTING.md for developer guidance.
The Charmed Kratos Operator is free software, distributed under the Apache Software License, version 2.0. See LICENSE for more information.