The new `code` strategy is now supported as a verification strategy. If enabled, the strategy sends a code, instead of a magic link to the user's address, which they can use to verify their address.
Close#2824
This feature introduces a new `code` strategy to recover an account.
Currently, if a user needs to initiate a recovery flow to recover a lost password/MFA/etc., they’ll receive an email containing a “magic link”. This link contains a flow_id and a recovery_token. This is problematic because some antivirus software opens links in emails to check for malicious content, etc.
Instead of the magic link, we send an 8-digit code that is clearly displayed in the email or SMS. A user can now copy/paste or type it manually into the text-field that is shown after the user clicks “submit” on the initiate flow page.
Closes#1451
BREAKING CHANGES: This patch changes the behavior of the recovery flow. It introduces a new strategy for account recovery that sends out short "one-time passwords" (`code`) that a user can use to prove ownership of their account and recovery access to it. This PR also updates the default recovery strategy to `code`.
BREAKING CHANGES: A major issue has been lingering in the configuration for a while. What happens to your identities when you update a schema? The answer was, it depends on the change. If the change is incompatible, some things might break!
To resolve this problem we changed the way you define schemas. Instead of having a global `default_schema_url` which developers used to update their schema, you now need to define the `default_schema_id` which must reference schema ID in your config. To update your existing configuration, check out the patch example below:
```patch
identity:
- default_schema_url: file://stub/identity.schema.json
+ default_schema_id: default
+ schemas:
+ - id: default
+ url: file://stub/identity.schema.json
```
Ideally, you would version your schema and update the `default_schema_id` with every change to the new version:
```yaml
identity:
default_schema_id: user_v1
schemas:
- id: user_v0
url: file://path/to/user_v0.json
- id: user_v1
url: file://path/to/user_v1.json
```
BREAKING CHANGE: The SDKs are now generated with tag v0alpha2 to reflect that some signatures have changed in a breaking fashion. Please update your imports from `v0alpha1` to `v0alpha2`.
This patch introduces the new `include_credential` query parameter to the `GET /identities` endpoint which allows administrators to receive the initial access, refresh, and ID tokens from Social Sign In (OpenID Connect / OAuth 2.0) flows.
These tokens can be stored in an encrypted format (XChaCha20Poly1305 or AES-GCM) in the database if an appropriate encryption secret is set. To get started easily these values are not encrypted per default.
For more information head [over to the docs](https://kratos/docs/guides/retrieve-social-sign-in-access-refresh-id-token).
Closes#1518Closes#397
BREAKING CHANGE: 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:
```patch
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:
```patch
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](https://www.ory.sh/docs/ecosystem/contributing#openapi-spec-and-go-swagger) 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.
```typescript
const kratos = new V0Alpha0(new Configuration({ basePath: config.kratos.admin, accessToken: 'some-token' }));
kratosAdmin.adminCreateIdentity({
schema_id: 'default',
traits: { /* ... */ },
});
```
We hope you enjoy the vastly improved experience! There are still many things that we want to iterate on. For full context, we recommend reading the proposal and discussion around these changes at [kratos#1424](https://github.com/ory/kratos/issues/1424).
Additionally, the Self-Service Error endpoint was updated. First, the endpoint `/self-service/errors` is now located at the public port only with the admin port redirecting to it. Second, the parameter `?error` was renamed to `?id` for better SDK compatibility. Parameter `?error` is still working but will be deprecated at some point. Third, the response no longer contains an error array in `errors` but instead just a single error under `error`:
```patch
{
"id": "60208346-3a61-4880-96ae-0419cde8fca8",
- "errors": [{
+ "error": {
"code": 404,
"status": "Not Found",
"reason": "foobar",
"message": "The requested resource could not be found"
- }],
+ },
"created_at": "2021-07-07T11:20:15.310506+02:00",
"updated_at": "2021-07-07T11:20:15.310506+02:00"
}
```
Closes#1424
BREAKING CHANGE: 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.
```patch
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](e7fa292968).
Closes#1282
BREAKING CHANGE: 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`.
Closes#142
hackerman
Patrik
Arne Luenser
Jonas Hungershausen
Kevin Goslar
ory-bot
Mitsuo Heijo
seremenko-wish