Ory Kratos

Ory Kratos is an API-first identity and user management system designed for cloud-native applications. It centralizes core identity workflows, allowing your services to consume them via HTTP APIs instead of implementing them manually.

Key workflows managed by Kratos include:

• Self-service login and registration
• Account verification and recovery
• Multi-factor authentication (MFA)
• Profile and account management
• Identity schemas and traits
• Admin APIs for identity lifecycle management

The client-go package provides comprehensive Go representations of all Ory Kratos API models. These include identities, sessions, flows (login, registration, recovery, settings, verification), and various authentication credential types (OIDC, Password, WebAuthn, TOTP, etc.).

Key model categories include:

• Identity Models: Identity, IdentityPatch, CreateIdentityBody.
• Flow Models: LoginFlow, RegistrationFlow, RecoveryFlow, SettingsFlow, VerificationFlow and their respective states and update methods.
• Session Models: Session, ManageSessionsBody.
• Error Models: GenericError, FlowError, ErrorBrowserLocationChangeRequired.

When calling jsonschemax.ListPaths() or ListPathsWithArraysIncluded(), the returned list contains objects representing the metadata for each path.

Each result object includes fields such as:

• Name: The dot-delimited path string (e.g., providers.#.id).
• Type: The type information.
• TypeHint: A numeric hint for the type.
• Required: A boolean indicating if the property is required.
• Format, Pattern, Enum, Minimum, Maximum, etc.: Validation constraints defined in the schema.

Example path output for a schema with an array of objects:

[
  {
    "Name": "providers",
    ...
  },
  {
    "Name": "providers.#",
    ...
  },
  {
    "Name": "providers.#.id",
    ...
  }
]

When migrating from identity providers like Auth0 or Okta that use OAuth2/OpenID Connect (OIDC), the recommended architecture is to use Ory Hydra and Ory Kratos together:

1. Ory Hydra: Acts as the OAuth2 and OpenID Connect provider, replacing the authorization server and token issuing capabilities of your existing IdP.
2. Ory Kratos: Handles the identity, credentials, and user-facing flows (login, registration, recovery, verification, and profile management).

This combination serves as a protocol-level replacement. You will need to update client configurations to point to Hydra and migrate your existing identities into Kratos.

To authenticate requests using an Ory Access Token, you must include the token in the Authorization HTTP header. In the Go client, this is achieved by adding a map of API keys to the request context using the client.ContextAPIKeys key. The key in the map must be exactly oryAccessToken.

Authentication Scheme Details:

• Type: API key
• Parameter Name: Authorization
• Location: HTTP header

auth := context.WithValue(
	context.Background(),
	client.ContextAPIKeys,
	map[string]client.APIKey{
		"oryAccessToken": {Key: "API_KEY_STRING"},
	},
)
r, err := client.Service.Operation(auth, args)

To ensure code adheres to the project's formatting standards, run the following command. The CI pipeline checks this automatically.

make format

To use the pagination helper in your Go project, install it using go get:

go get github.com/ory/pagination

To work on and preview the generated API documentation, follow these steps:

1. Update the SDK and the OpenAPI specification:

make sdk

2. Start the preview server for API documentation:

make docs/api

3. Or, start the preview server for Swagger documentation:

make docs/swagger

End-to-end (e2e) tests are implemented using Cypress.

Prerequisites for ARM Macs

If you are on an ARM-based Mac, you may need to install Rosetta 2 to run Cypress:

softwareupdate --install-rosetta --agree-to-license

Running tests

To run e2e tests in development mode using SQLite:

./test/e2e/run.sh --dev sqlite

To run all e2e tests using full databases:

make test-e2e

Filtering tests

• Single test: Add .only to the test definition in the source (e.g., it.only(...)).
• Subset of tests: Edit test/e2e/cypress.json and add the testFiles option with a glob pattern, for example: "testFiles": ["profiles/network/*"].