quick-addition-90714
03/09/2025, 9:57 AMbrief-egg-61061
03/09/2025, 9:57 AMbrief-egg-61061
03/09/2025, 9:57 AMbody
configuration in the HTTP request settings. Here's how you can do it: 1. Create a custom Jsonnet file with your desired email payload structure. 2. In your Ory Identities configuration, update the body
field under the courier.http.request_config
section to point to your custom Jsonnet file. Here's an example of how to configure this: yaml courier: delivery_strategy: http http: request_config: url: <https://mail-sender.example.com> method: POST body: file:///path/to/your/custom/mail.template.jsonnet headers: Content-Type: application/json # ... other configuration options
Replace /path/to/your/custom/mail.template.jsonnet
with the actual path to your custom Jsonnet file. Your custom Jsonnet file should be a function that takes a ctx
object as input and returns the desired payload structure. The ctx
object provides access to various email-related data such as recipient, template type, and template data. Here's an example of what your custom Jsonnet might look like: jsonnet function(ctx) { recipient: ctx.recipient, template_type: ctx.template_type, // Add or modify fields as needed custom_field: "Your custom value", // Access template data verification_code: if "template_data" in ctx && "verification_code" in ctx.template_data then ctx.template_data.verification_code else null, // ... other fields }
Remember to adjust the Jsonnet according to your specific needs and the requirements of your HTTP email service. For more detailed information on HTTP-based email delivery configuration and available variables, you can refer to the [Ory documentation on sending emails using an HTTP server](https://www.ory.sh/docs/kratos/emails-sms/sending-emails-smtp#send-emails-using-an-http-server).quick-addition-90714
03/09/2025, 10:06 AMbrief-egg-61061
03/09/2025, 10:06 AMbrief-egg-61061
03/09/2025, 10:06 AM--watch-courier
flag to your kratos serve
command. This is suitable for single-instance deployments. kratos serve --watch-courier
2. For a multi-instance setup: If you're running multiple instances of Kratos (e.g., in a replicated Kubernetes deployment), you need to run the mail courier as a separate singleton job. Here's how: a. Run Kratos instances: kratos serve
b. Run the mail courier as a separate job: kratos courier watch
It's important to note that in a multi-instance setup, you should only run one instance of the mail courier to avoid processing the same email multiple times. Make sure to provide the necessary configuration files and templates to all instances (both Kratos and courier) in your multi-instance setup. For more detailed information on running the mail courier in self-hosted Ory Kratos, you can refer to the [Ory documentation on Mail courier in self-hosted Ory Kratos](https://www.ory.sh/docs/kratos/self-hosted/mail-courier-selfhosted). Remember to configure your SMTP settings and other necessary configurations in your Kratos configuration file before running these commands.quick-addition-90714
03/09/2025, 10:09 AMbrief-egg-61061
03/09/2025, 10:09 AMbrief-egg-61061
03/09/2025, 10:09 AM/self-service/recovery
endpoint. 2. The system attempted to prepare a recovery code for the provided email address. 3. The log indicates that the recovery was requested for an unknown address: msg=Account recovery was requested for an unknown address.
4. The system did not send a notification to the unknown address: was_notified=false
5. The recovery flow was created and redirected to: location:<http://localhost:3002/recovery?flow=6707a028-1567-4488-9e82-91ebae7fe72a>
6. The identity schema provided does not include the recovery
configuration in the <http://ory.sh/kratos|ory.sh/kratos>
section for the email field. Given this information, there are a few important points to note: 1. The system is configured to not notify unknown recipients during recovery attempts. This is a security measure to prevent account enumeration attacks. 2. The identity schema doesn't explicitly enable recovery for the email field. To enable recovery via email, you should add the following to the <http://ory.sh/kratos|ory.sh/kratos>
section of the email field in your schema: json "recovery": { "via": "email" }
3. If you want to enable notifications for unknown recipients during recovery attempts, you need to update your Ory Kratos configuration. To address these points, you can: 1. Update your identity schema to enable recovery via email. 2. If desired, enable notifications for unknown recipients in your Ory Kratos configuration. For more information on configuring account recovery and attempted recovery notifications, you can refer to the [Ory documentation on Account recovery and password reset](https://www.ory.sh/docs/kratos/self-service/flows/account-recovery-password-reset#account-recovery-address) and [Attempted recovery notifications](https://www.ory.sh/docs/kratos/self-service/flows/account-recovery-password-reset#attempted-recovery-notifications).quick-addition-90714
03/09/2025, 10:10 AMbrief-egg-61061
03/09/2025, 10:10 AMbrief-egg-61061
03/09/2025, 10:10 AMjson { "$id": "<https://schemas.ory.sh/presets/kratos/quickstart/email-password/identity.schema.json>", "$schema": "<http://json-schema.org/draft-07/schema#>", "title": "Person", "type": "object", "properties": { "traits": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "title": "E-Mail", "minLength": 6, "<http://ory.sh/kratos|ory.sh/kratos>": { "credentials": { "password": { "identifier": true } }, "recovery": { "via": "email" }, "verification": { "via": "email" } } } }, "required": ["email"], "additionalProperties": false } } }
This updated schema includes the following changes: 1. Added the recovery
configuration to enable account recovery via email. 2. Added the verification
configuration to enable email verification. 3. Changed the title
of the email field from "email" to "E-Mail" for consistency with Ory's documentation examples. These additions will allow you to use the email address for account recovery and verification purposes. The recovery
and verification
configurations are set to use email as the method ("via": "email"). For more detailed information on customizing identity schemas and configuring recovery and verification, you can refer to the following Ory documentation: 1. [Customize identity schemas](https://www.ory.sh/docs/kratos/manage-identities/customize-identity-schema#examples) 2. [Account recovery address](https://www.ory.sh/docs/kratos/self-service/flows/account-recovery-password-reset#account-recovery-address) 3. [Verification address](https://www.ory.sh/docs/kratos/manage-identities/customize-identity-schema#verification-address) Remember to update your Ory Kratos configuration to enable the recovery and verification flows if you haven't already done so.quick-addition-90714
03/09/2025, 10:26 AMbrief-egg-61061
03/09/2025, 10:26 AMbrief-egg-61061
03/09/2025, 10:26 AMgo type EmailTemplate struct { Recipient string `json:"recipient"` TemplateType string `json:"template_type"` Name *string `json:"name,omitempty"` To *string `json:"to,omitempty"` RecoveryCode *string `json:"recovery_code,omitempty"` RecoveryURL *string `json:"recovery_url,omitempty"` VerificationURL *string `json:"verification_url,omitempty"` VerificationCode *string `json:"verification_code,omitempty"` }
This struct definition allows you to properly read and handle the JSON body that would be generated by the Jsonnet template. Here are some key points about this struct: 1. All fields that can potentially be null
in the Jsonnet output are represented as pointers (*string
) in the Go struct. This allows for proper handling of null values when unmarshaling the JSON. 2. The json
tags are used to map the JSON keys to the struct fields. 3. The omitempty
tag is used for fields that might not always be present in the JSON, which corresponds to the conditional logic in the Jsonnet template. 4. The Recipient
and TemplateType
fields are non-pointer types because they appear to always be present in the Jsonnet output. To use this struct to read the JSON body, you can use Go's encoding/json
package. Here's an example of how you might unmarshal the JSON into this struct: go import "encoding/json" // Assuming `body` is the []byte containing your JSON data var template EmailTemplate err := json.Unmarshal(body, &template) if err != nil { // Handle error } // Now you can access the fields of `template`
This struct and unmarshaling process will allow you to properly handle the JSON output from your Jsonnet template in your Go code. For more information on working with JSON in Go, you can refer to the [Go documentation on JSON and Go](https://golang.org/pkg/encoding/json/).quick-addition-90714
03/09/2025, 2:26 PMbrief-egg-61061
03/09/2025, 2:26 PMbrief-egg-61061
03/09/2025, 2:27 PMjson { "$id": "<https://schemas.ory.sh/presets/kratos/quickstart/email-password/identity.schema.json>", "$schema": "<http://json-schema.org/draft-07/schema#>", "title": "Person", "type": "object", "properties": { "traits": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "title": "E-Mail", "<http://ory.sh/kratos|ory.sh/kratos>": { "credentials": { "password": { "identifier": true } }, "recovery": { "via": "email" }, "verification": { "via": "email" } } }, "name": { "type": "object", "properties": { "first": { "type": "string", "title": "First Name" }, "last": { "type": "string", "title": "Last Name" } }, "required": ["first", "last"] } }, "required": ["email", "name"], "additionalProperties": false } } }
2. To make the fields required, we've added them to the required
array within the name
object and added name
to the required
array of the traits
object. When you run the migration after updating the schema, the following will happen: 1. Ory Kratos will update its internal representation of the identity schema. 2. New registrations will require users to provide both first and last names. 3. Existing identities will not be automatically updated with the new fields. They will remain valid but may have missing data for the new fields. To handle existing identities, you have a few options: 1. You can update them manually through the admin API. 2. You can prompt users to update their profiles the next time they log in. 3. You can write a migration script to update existing identities with default values for the new fields. It's important to note that changing the schema to require new fields that didn't exist before can potentially cause issues with existing identities. Therefore, it's recommended to handle this change carefully, especially in a production environment. For more detailed information on customizing identity schemas and handling schema migrations, you can refer to the following Ory documentation: 1. [Customize identity schemas](https://www.ory.sh/docs/kratos/manage-identities/customize-identity-schema) 2. [Identity schema best practices](https://www.ory.sh/docs/kratos/manage-identities/best-practices) Remember to test these changes in a non-production environment first to ensure they work as expected with your existing data and workflows.quick-addition-90714
03/09/2025, 4:31 PMbrief-egg-61061
03/09/2025, 4:31 PMbrief-egg-61061
03/09/2025, 4:31 PMmessage_retries
configuration parameter. 2. Configuration: You can adjust the number of retries in your Ory Kratos configuration file. For example: yaml courier: message_retries: 5
3. Abandoned status: If the courier can't deliver the message within the specified number of retries, the message gets the Abandoned
status, and the courier stops trying to deliver it. 4. Webhook retries: For webhook deliveries (which could be used in custom integrations), Ory Network implements a retry policy that attempts to deliver the payload up to three times, with a 30-second timeout between each attempt. It's important to note that the retry mechanism is implemented at the Ory Kratos level, not at the HTTP API level. This means that Ory Kratos will handle the retries internally, regardless of whether you're using SMTP or HTTP for email delivery. For more detailed information on the retry mechanism and courier configuration, you can refer to the following Ory documentation: 1. [Mail courier in self-hosted Ory Kratos](https://www.ory.sh/docs/kratos/self-hosted/mail-courier-selfhosted#error-handling) 2. [Webhook retries](https://www.ory.sh/docs/guides/integrate-with-ory-cloud-through-webhooks#webhook-retries) Remember that while Ory provides this retry mechanism, it's also a good practice to monitor your email delivery system and handle any persistent delivery issues at the application level.quick-addition-90714
03/09/2025, 4:33 PMbrief-egg-61061
03/09/2025, 4:33 PMbrief-egg-61061
03/09/2025, 4:33 PMquick-addition-90714
03/12/2025, 4:50 PMbrief-egg-61061
03/12/2025, 4:50 PMbrief-egg-61061
03/12/2025, 4:51 PMjson { "type": "input", "group": "profile", "attributes": { "name": "traits.email", "type": "email", "value": "<mailto:user@example.com|user@example.com>", "disabled": false }, "messages": null, "meta": { "label": { "id": 1070002, "text": "E-Mail", "type": "info" } } }
The same ID (1070002) is used for other profile fields as well: json { "type": "input", "group": "profile", "attributes": { "name": "traits.name.first", "type": "text", "value": "Foo", "disabled": false }, "messages": null, "meta": { "label": { "id": 1070002, "text": "First Name", "type": "info" } } }
According to the [Ory documentation on UI nodes and error messages](https://www.ory.sh/docs/kratos/concepts/ui-user-interface#titles-labels--validation-messages), message IDs follow a pattern where: - x
is the message type (1 for info) - yy
is the module (07 for verification messages) - zzzz
is the specific message ID So 1070002 represents an info message (1) in the verification module (07) with ID 0002. This consistent ID usage is by design and doesn't affect functionality, as the actual display text is provided in the "text" field of each label.quick-addition-90714
03/15/2025, 2:21 PMbrief-egg-61061
03/15/2025, 2:21 PMbrief-egg-61061
03/15/2025, 2:21 PMkratos courier watch
command. This is particularly useful in multi-instance deployments where you want to run the mail courier as a separate singleton process. Here's how to do it: kratos courier watch [flags]
Available flags include: - `--expose-metrics-port int`: The port to expose the metrics endpoint on (not exposed by default) - `-c, --config strings`: Path to one or more configuration files For example, to run the courier with a specific configuration file: kratos courier watch -c path/to/kratos/config.yml
This command starts the mail courier as a standalone process that will process the email queue. It's important to note that in a multi-instance setup, you should only run one instance of the mail courier to avoid processing the same email multiple times. If you're running in a containerized environment like Docker or Kubernetes, you would typically run this as a separate container or pod with the appropriate configuration. For more information on the courier command and its options, you can refer to the [Kratos CLI documentation](https://www.ory.sh/docs/kratos/cli/kratos-courier-watch).quick-addition-90714
03/15/2025, 2:23 PMbrief-egg-61061
03/15/2025, 2:23 PMbrief-egg-61061
03/15/2025, 2:23 PMcommand = [ "kratos", "courier", "watch", "-c", "/shared/config.yml" ]
This command will start the Ory Kratos mail courier as a standalone process using the configuration file located at /shared/config.yml
. The courier will be responsible for processing and sending emails from the message queue. This approach is particularly useful in multi-instance deployments where you want to run the mail courier as a separate singleton process to avoid duplicate email processing. For more information about the courier command and its options, you can refer to the [Kratos courier watch documentation](https://www.ory.sh/docs/kratos/cli/kratos-courier-watch).quick-addition-90714
03/15/2025, 3:23 PMbrief-egg-61061
03/15/2025, 3:23 PMbrief-egg-61061
03/15/2025, 3:23 PMmsg=Account recovery was requested for an unknown address. audience=audit email_address=Value is sensitive and has been redacted. To see the value set config key "log.leak_sensitive_values = true" or environment variable "LOG_LEAK_SENSITIVE_VALUES=true". service_name=Ory Kratos service_version=v1.3.1 strategy=code via=email was_notified=false
This shows that Ory Kratos detected a recovery attempt for an unknown email but didn't reveal this information to the user. If you need to check if an email exists for legitimate purposes, you should use internal admin APIs or database queries that aren't exposed to end users, rather than using the public-facing recovery flow.quick-addition-90714
03/16/2025, 2:02 PMbrief-egg-61061
03/16/2025, 2:02 PMbrief-egg-61061
03/16/2025, 2:02 PM/health/alive
- This endpoint returns a HTTP 200 status code when the service is accepting incoming HTTP requests. This is a basic liveness check. 2. /health/ready
- This endpoint returns a HTTP 200 status code when the service is up and running and its dependencies (like the database) are responsive as well. This is a more comprehensive readiness check. You can use these endpoints to monitor the health of your courier instance. For example, you could use the kratos remote status
command to check the status of a remote Kratos instance, including the courier: kratos remote status --endpoint <http://your-courier-instance:port>
It's worth noting that these health checks will only report on the status of a single instance, not the overall cluster state if you're running multiple instances. For more information on health checks in Ory services, you can refer to the API reference documentation for [Kratos](https://www.ory.sh/docs/kratos/reference/api), [Hydra](https://www.ory.sh/docs/hydra/reference/api), and [Keto](https://www.ory.sh/docs/keto/reference/rest-api), which all follow a similar pattern for health checks.quick-addition-90714
03/18/2025, 7:24 PMbrief-egg-61061
03/18/2025, 7:24 PMbrief-egg-61061
03/18/2025, 7:24 PMselfservice.flows.login.ui_url
configuration value. This tells Kratos where to redirect users during the login flow. Here's how you can set this in your Kratos configuration file: yaml selfservice: flows: login: ui_url: <http://your-app.com/login>
You can also set this using an environment variable: SELFSERVICE_FLOWS_LOGIN_UI_URL=<http://your-app.com/login>
This configuration is crucial because without it, users will be redirected to Kratos' fallback login UI, which is just a placeholder page that instructs you to set up the proper configuration. When a user initiates a login flow, Kratos will: 1. Create a new login flow 2. Redirect the user to the configured ui_url
with a flow ID as a query parameter 3. Your UI application will then fetch the flow details and render the login form 4. The form will be submitted back to Kratos for processing For more information, you can refer to: - [Self-Service User Login](https://www.ory.sh/docs/kratos/self-service/flows/user-login) - [Kratos Fallback Login UI](https://www.ory.sh/docs/kratos/fallback/login) If you're deploying to production, you might want to check the [Deploy to production guide](https://www.ory.sh/docs/kratos/guides/deploy-kratos-example#configure-user-interface) which includes examples of configuring all the UI URLs.quick-addition-90714
03/18/2025, 7:35 PMquick-addition-90714
03/18/2025, 7:35 PMbrief-egg-61061
03/18/2025, 7:35 PMbrief-egg-61061
03/18/2025, 7:35 PMserve.public.base_url
setting in your Kratos configuration. This setting determines what base URL Kratos uses when generating URLs for forms and redirects. Here's how to update your configuration: yaml serve: public: base_url: <https://your-public-domain.com/>
You can also set this using an environment variable: SERVE_PUBLIC_BASE_URL=<https://your-public-domain.com/>
This configuration is crucial for proper operation when Kratos is running behind a proxy or in environments where the internal hostname differs from the public-facing domain. If you're using custom domains with Ory Network, you'll need to set up a CNAME record for your domain. For self-hosted Kratos, the base_url configuration is sufficient. For more information on configuring base URLs and cookies in multi-domain environments, you can refer to: - [Advanced base URL, CSRF and session cookie settings](https://www.ory.sh/docs/kratos/guides/multi-domain-cookies) - [Configure User Interface](https://www.ory.sh/docs/kratos/guides/deploy-kratos-example#configure-user-interface) After updating this configuration, restart your Kratos service for the changes to take effect.