Configure Ory Kratos Self‑Service Registration with Email Verification

Desired outcome

Enable Ory Kratos to allow new users to register with a password, receive a verification email, and have their email_verified trait set to true after clicking the link.

Prerequisites

• A running Ory Kratos instance (version 0.11 or newer).
• Access to an SMTP server that can relay mail from the Kratos host; you need the host, port, username, password, and a sender address.
• An identity schema that includes at least the traits email (string, format email) and password (string). The schema should also contain a boolean trait email_verified (default false).
• Administrative access to the Kratos configuration file (usually config.yml) and permission to restart the service.

Procedure

1. Enable the required self‑service methods
   Edit config.yml and set the following under the selfservice section:

selfservice:
  methods:
    password:
      enabled: true
    profile:
      enabled: true
    link:
      enabled: true
      # optional: adjust lifespan if you need a different expiry
      lifespan: 1h

Save the file.

1. Configure the email courier
   Still in config.yml, add or update the courier block:

courier:
  smtp:
    host: YOUR_SMTP_HOST
    port: 587          # or 465 for TLS, 25 for plain
    username: YOUR_SMTP_USER
    password: YOUR_SMTP_PASSWORD
    from: no-reply@example.com
  email:
    verify:
      subject: "Verify your email address"
      # You can reference a template file or embed the body directly.
      # Example inline body (HTML):
      body: |
        
Hello {{ .Identity.Traits.email }},
        
Please click the link below to verify your address:
        
Verify email
        
This link expires in {{ .VerifiableAddress.Lifespan }}.

Replace the placeholders with your actual SMTP details and sender address. If you prefer to keep the template in a separate file, set courier.email.verify.bodyPath to the file path instead of using body.

1. Apply the configuration and restart Kratos
   Depending on how you run Kratos (Docker, binary, Kubernetes), reload the configuration. For a binary run:

# Send SIGHUP to the process to reload config without downtime
kill -HUP $(pgrep ory kratos)

If you cannot use SIGHUP, restart the service:

systemctl restart ory-kratos   # example for a systemd service

Expected checks

1. Registration request
   Call the public registration endpoint (replace KRATOS_PUBLIC with your base URL):

curl -X POST "$KRATOS_PUBLIC/selfservice/methods/password/registration" \
  -H "Content-Type: application/json" \
  -d '{"traits":{"email":"test@example.com","password":"Secret123!"}}'

You should receive an HTTP 200 response containing a session token. The response body will include a ui element indicating that the flow is waiting for email verification.

1. Email delivery
   Check the inbox of the address used in the request. You should see an email with the subject configured above and a link that contains a one‑time token. You can also verify on the SMTP side using a tool like swaks:

swaks --to test@example.com --from no-reply@example.com \
  --server YOUR_SMTP_HOST --port 587 --auth LOGIN \
  --auth-user YOUR_SMTP_USER --auth-password YOUR_SMTP_PASSWORD \
  --data "Subject: test\n\nThis is a test."

If the email arrives, the courier is working.

1. Verification link
   Copy the verification URL from the email and open it in a browser or with curl:

curl -i "https://example.com/selfservice/methods/link/verify?token=abc123..."

Expect an HTTP 200 response and a JSON body indicating success ({"status":"success"}).

1. Identity update
   Using the Kratos Admin API (requires admin token), fetch the identity:

curl -H "Authorization: Bearer $ADMIN_TOKEN" \
  "$KRATOS_ADMIN/admin/identities/"

In the returned JSON, the traits object should now contain "email_verified":true. No further verification emails should be sent for this identity.

Recovery and rollback options

If any step fails, you can revert the configuration changes:

• Disable the link method – set selfservice.methods.link.enabled: false and reload/restart Kratos. This stops verification emails from being sent while you troubleshoot.
• Correct SMTP credentials – update the courier.smtp block with valid values and reload.
• Resend verification – for an existing unverified identity, call the Admin API endpoint POST /admin/identities//verification (if enabled) or ask the user to repeat the registration flow.
• Handle expired links – the default lifespan is 1 hour. If a user clicks an expired link, the verification endpoint returns an error. The user must request a new verification email (via the same registration flow or an admin‑triggered resend).

After making a correction, repeat the expected checks to confirm that the flow works as intended.