github ory/kratos v0.7.0-alpha.1
on GitHub

latest releases: v1.2.0, v1.2.0-pre.0, v1.1.0...
pre-release2 years ago

About two months ago we released Ory Kratos v0.6. Today, we are excited to announce the next iteration of Ory Kratos v0.7! This release includes 215 commits from 24 contributors with over 770 files and more than 100.000 lines of code changed!

Ory Kratos v0.7 brings massive developer experience improvements:

  • A reworked, tested, and standardized SDK based on OpenAPI 3.0.3 (#1477, #1424);
  • Native support of Single-Page-Apps (ReactJS, AngularJS, ...) for all self-service flows (#1367);
  • Sign in with Yandex, VK, Auth0, Slack;
  • An all-new, secure logout flow (#1433);
  • Important security updates to the self-service GET APIs (#1458, #1282);
  • Built-in support for TLS (#1466);
  • Improved documentation and Go Module structure;
  • Resolving a case-sensitivity bug in self-service recovery and verification flows;
  • Improved performance for listing identities;
  • Support for Instant tracing (#1429);
  • Improved control for SMTPS, supporting SSL and STARTTLS (#1430);
  • Ability to run Ory Kratos in networks without outbound requests (#1445);
  • Improved control over HTTP Cookie behavior (#1531);
  • Several smaller user experience improvements and bug fixes;
  • Improved e2e test pipeline.

In the next iteration of Ory Kratos, we will focus on providing a NextJS example application for the SPA integration as well as the long-awaited MFA flows!

Please be aware that upgrading to Ory Kratos 0.7 requires you to apply SQL migrations. Make sure to back up your database before migration!

For more details on breaking changes and patch notes, see below.

Breaking Changes

Prior to this change it was not possible to specify the verification/recovery link lifetime. Instead, it was bound to the flow expiry. This patch changes that and adds the ability to configure the lifespan of the link individually: 

 selfservice:
   methods:
     link:
       enabled: true
       config:
+        # Defines how long a recovery link is valid for (default 1h)
+        lifespan: 15m

This is a breaking change because the link strategy no longer respects the recovery / verification flow expiry time and, unless set, will default to one hour.

This change introduces a better SDK. As part of this change, several breaking changes with regards to the SDK have been introduced. We recommend reading this section carefully to understand the changes and how they might affect you.

Before, the SDK was structured into tags public and admin. This stems from the fact that we have two ports in Ory Kratos - one administrative and one public port.

While serves as a good overview when working with Ory Kratos, it does not express:

  • What module the API belongs to (e.g. self-service, identity, ...)
  • What maturity the API has (e.g. experimental, alpha, beta, ...)
  • What version the API has (e.g. v0alpha0, v1beta0, ...)

This patch replaces the current admin and public tags with a versioned approach indicating the maturity of the API used. For example, initializeSelfServiceSettingsForBrowsers would no longer be under the public tag but instead under the v0alpha1 tag: 

import {
  Configuration,
- PublicApi
+ V0Alpha1
} from '@ory/kratos-client';

- const kratos = new PublicApi(new Configuration({ basePath: config.kratos.public }));
+ const kratos = new V0Alpha1(new Configuration({ basePath: config.kratos.public }));

To avoid confusion when setting up the SDK, and potentially using the wrong endpoints in your codebase and ending up with strange 404 errors, Ory Kratos now redirects you to the correct port, given that serve.(public|admin).base_url are configured correctly. This is a significant improvement towards a more robust API experience!

Further, all administrative functions require, in the Ory SaaS, authorization using e.g. an Ory Personal Access Token. In the open source, we do not know what developers use to protect their APIs. As such, we believe that it is ok to have admin and public functions under one common API and differentiate with an admin prefix. Therefore, the following patches should be made in your codebase: 

import {
- AdminApi,
+ V0Alpha1,
  Configuration
} from '@ory/kratos-client';

-const kratos = new AdminApi(new Configuration({ basePath: config.kratos.admin }));
+const kratos = new V0Alpha1(new Configuration({ basePath: config.kratos.admin }));

-kratos.createIdentity({
+kratos.adminCreateIdentity({
  schema_id: 'default',
  traits: { /* ... */ }
})

Further, we have introduced a style guide for writing SDKs annotations governing how naming conventions should be chosen.

We also streamlined how credentials are used. We now differentiate between:

  • Per-request credentials such as the Ory Session Token / Cookie 
    - public getSelfServiceRegistrationFlow(id: string, cookie?: string, options?: any) {}
+ public getSelfServiceSettingsFlow(id: string, xSessionToken?: string, cookie?: string, options?: any) {}
  • Global credentials such as the Ory (SaaS) Personal Access Token. 
    const kratos = new V0Alpha0(new Configuration({ basePath: config.kratos.admin, accessToken: 'some-token' }));

kratosAdmin.adminCreateIdentity({
  schema_id: 'default',
  traits: { /* ... */ },
});

This patch introduces CSRF countermeasures for fetching all self-service flows. This ensures that users can not accidentally leak sensitive information when copy/pasting e.g. login URLs (see #1282). If a self-service flow for browsers is requested, the CSRF cookie must be included in the call, regardless if it is a client-side browser app or a server-side browser app calling. This does not apply for API-based flows.

As part of this change, the following endpoints have been removed:

  • GET <ory-kratos-admin>/self-service/login/flows;
  • GET <ory-kratos-admin>/self-service/registration/flows;
  • GET <ory-kratos-admin>/self-service/verification/flows;
  • GET <ory-kratos-admin>/self-service/recovery/flows;
  • GET <ory-kratos-admin>/self-service/settings/flows.

Please ensure that your server-side applications use the public port (e.g. GET <ory-kratos-public>/self-service/login/flows) for fetching self-service flows going forward.

If you use the SDKs, upgrading is easy by adding the cookie header when fetching the flows. This is only required when using browser flows on the server side.

The following example illustrates a ExpressJS (NodeJS) server-side application fetching the self-service flows. 

app.get('some-route', (req: Request, res: Response) => {
-   kratos.getSelfServiceLoginFlow(flow).then((flow) => /* ... */ )
+   kratos.getSelfServiceLoginFlow(flow, req.header('cookie')).then((flow) => /* ... */ )

-   kratos.getSelfServiceRecoveryFlow(flow).then((flow) => /* ... */ )
+   kratos.getSelfServiceRecoveryFlow(flow, req.header('cookie')).then((flow) => /* ... */ )

-   kratos.getSelfServiceRegistrationFlow(flow).then((flow) => /* ... */ )
+   kratos.getSelfServiceRegistrationFlow(flow, req.header('cookie')).then((flow) => /* ... */ )

-   kratos.getSelfServiceVerificationFlow(flow).then((flow) => /* ... */ )
+   kratos.getSelfServiceVerificationFlow(flow, req.header('cookie')).then((flow) => /* ... */ )

-   kratos.getSelfServiceSettingsFlow(flow).then((flow) => /* ... */ )
+   kratos.getSelfServiceSettingsFlow(flow, undefined, req.header('cookie')).then((flow) => /* ... */ )
})

For concrete details, check out the changes in the NodeJS app.

This patch refactors the logout functionality for browsers and APIs. It adds increased security and DoS-defenses to the logout flow.

Previously, calling GET /self-service/browser/flows/logout would remove the session cookie and redirect the user to the logout endpoint. Now you have to make a call to GET /self-service/logout/browser which returns a JSON response including a logout_url URL to be used for logout. The call to /self-service/logout/browser must be made using AJAX with cookies enabled or by including the Ory Session Cookie in the X-Session-Cookie HTTP Header. You may also use the SDK method createSelfServiceLogoutUrlForBrowsers to do that.

Additionally, the endpoint DELETE /sessions has been moved to DELETE /self-service/logout/api. Payloads and responses stay equal. The SDK method revokeSession has been renamed to submitSelfServiceLogoutFlowWithoutBrowser.

We listened to your feedback and have improved the naming of the SDK method initializeSelfServiceRecoveryForNativeApps to better match what it does: initializeSelfServiceRecoveryWithoutBrowser. As in the previous release you may still use the old SDK if you do not want to deal with the SDK breaking changes for now.

We listened to your feedback and have improved the naming of the SDK method initializeSelfServiceVerificationForNativeApps to better match what it does: initializeSelfServiceVerificationWithoutBrowser. As in the previous release you may still use the old SDK if you do not want to deal with the SDK breaking changes for now.

We listened to your feedback and have improved the naming of the SDK method initializeSelfServiceSettingsForNativeApps to better match what it does: initializeSelfServiceSettingsWithoutBrowser. As in the previous release you may still use the old SDK if you do not want to deal with the SDK breaking changes for now.

We listened to your feedback and have improved the naming of the SDK method initializeSelfServiceregistrationForNativeApps to better match what it does: initializeSelfServiceregistrationWithoutBrowser. As in the previous release you may still use the old SDK if you do not want to deal with the SDK breaking changes for now.

We listened to your feedback and have improved the naming of the SDK method initializeSelfServiceLoginForNativeApps to better match what it does: initializeSelfServiceLoginWithoutBrowser. As in the previous release you may still use the old SDK if you do not want to deal with the SDK breaking changes for now.

Bug Fixes

Code Generation

  • Pin v0.7.0-alpha.1 release commit (53a0e38)

Code Refactoring

Documentation

Features

  • Add examples for usage of go sdk (870c2bd)

  • Add GetContextualizer (ac32717)

  • Add helper for starting kratos e2e (#1469) (b9c7674)

  • Add instana as possible tracing provider (#1429) (abe48a9), closes #1385

  • Add redoc (#1502) (492266d)

  • Add vk and yandex providers to oidc providers and documentation (#1339) (22a3ef9), closes #1234

  • Anti-CSRF measures when fetching flows (#1458) (5171557), closes #1282

  • Configurable recovery/verification link lifetime (f80d4e3)

  • Disable HaveIBeenPwned validation when HaveIBeenPwnedEnabled is set to false (#1445) (44002f4), closes #316:

    This patch introduces an option to disable HaveIBeenPwned checks in environments where outbound network calls are disabled.

  • identities: Add a state to identities (#1312) (d22954e), closes #598

  • Improve contextualization in serve/daemon (f83cd35)

  • Include Credentials Metadata in admin api (#1274) (c8b6219), closes #820

  • Include Credentials Metadata in admin api Missing changes in handler (#1366) (a71c220)

  • Natively support SPA for login flows (6ff67af), closes #1138 #668:

    This patch adds the long-awaited capabilities for natively working with SPAs and AJAX requests. Previously, requests to the /self-service/login/browser endpoint would always end up in a redirect. Now, if the Accept header is set to application/json, the login flow will be returned as JSON instead. Accordingly, changes to the error and submission flow have been made to support application/json content types and SPA / AJAX requests.

  • Natively support SPA for recovery flows (5461244):

    This patch adds the long-awaited capabilities for natively working with SPAs and AJAX requests. Previously, requests to the /self-service/recovery/browser endpoint would always end up in a redirect. Now, if the Accept header is set to application/json, the registration flow will be returned as JSON instead. Accordingly, changes to the error and submission flow have been made to support application/json content types and SPA / AJAX requests.

  • Natively support SPA for registration flows (57d3c57), closes #1138 #668:

    This patch adds the long-awaited capabilities for natively working with SPAs and AJAX requests. Previously, requests to the /self-service/registration/browser endpoint would always end up in a redirect. Now, if the Accept header is set to application/json, the registration flow will be returned as JSON instead. Accordingly, changes to the error and submission flow have been made to support application/json content types and SPA / AJAX requests.

  • Natively support SPA for settings flows (ea4395e):

    This patch adds the long-awaited capabilities for natively working with SPAs and AJAX requests. Previously, requests to the /self-service/settings/browser endpoint would always end up in a redirect. Now, if the Accept header is set to application/json, the registration flow will be returned as JSON instead. Accordingly, changes to the error and submission flow have been made to support application/json content types and SPA / AJAX requests.

  • Natively support SPA for verification flows (c151500):

    This patch adds the long-awaited capabilities for natively working with SPAs and AJAX requests. Previously, requests to the /self-service/verification/browser endpoint would always end up in a redirect. Now, if the Accept header is set to application/json, the registration flow will be returned as JSON instead. Accordingly, changes to the error and submission flow have been made to support application/json content types and SPA / AJAX requests.

  • Protect logout against CSRF (#1433) (1a7a74c), closes #142

  • Sign in with Auth0 (#1352) (f618a53), closes #609

  • Support api in settings error (23105db)

  • Support reading session token from X-Session-Token HTTP header (dcaefd9)

  • Team id in slack oidc (#1409) (e4d021a), closes #1408

  • TLS support for public and admin endpoints (#1466) (7f44f81), closes #791

  • Update openapi specs and regenerate (cac507e)

Tests

  • Add tests for cookie behavior of API and browser endpoints (d1b1521)

  • e2e: Greatly improve test performance (#1421) (2ffad9e):

    Instead of running the individual profiles as separate Cypress instances, we now use one singular instance which updates the Ory Kratos configuration depending on the test context. This ensures that hot-reloading is properly working while also signficantly reducing the amount of time spent on booting up the service dependencies.

  • e2e: Resolve flaky test issues related to timeouts and speed (b083791)

  • e2e: Resolve recovery regression (72c47d6)

  • e2e: Resolve test config regressions (eb9c4f9)

  • Remove obsolete console.log (3ecc869)

  • Resolve e2e regressions (b0d3b82)

  • Resolve migratest panic (89d05ae)

  • Resolve mobile regressions (868e82e)

  • Resolve oidc regressions (2403082)

Unclassified

Docker images

  • docker pull oryd/kratos:v0-sqlite
  • docker pull oryd/kratos:v0.7-sqlite
  • docker pull oryd/kratos:v0.7.0-sqlite
  • docker pull oryd/kratos:v0.7.0-alpha.1-sqlite
  • docker pull oryd/kratos:latest-sqlite
  • docker pull oryd/kratos:v0
  • docker pull oryd/kratos:v0.7
  • docker pull oryd/kratos:v0.7.0
  • docker pull oryd/kratos:v0.7.0-alpha.1
  • docker pull oryd/kratos:latest
Check out latest releases or
releases around ory/kratos v0.7.0-alpha.1

Don't miss a new kratos release

NewReleases is sending notifications on new releases.

Get notifications