Ory Kratos Files

We are thrilled to announce the release of Ory Kratos v1.3.0! This release includes significant updates, enhancements, and fixes to improve your experience with Ory Kratos.

Enhance your sign-in experience with Identifier First Authentication. This feature allows users to first identify themselves (e.g., by providing their email or username) and then proceed with the chosen authentication method, whether it be OTP code, passkeys, passwords, or social login. By streamlining the sign-in process, users can select the authentication method that best suits their needs, reducing friction and enhancing security. Identifier First Authentication improves user flow and reduces the likelihood of errors, resulting in a more user-friendly and efficient login experience.

The UI for OpenID Connect (OIDC) account linking has been improved to provide better user guidance and error messages during the linking process. As a result, account linking error rates have dropped significantly, making it easier for users to link multiple identities (e.g., social login and email-based accounts) to the same profile. This improvement enhances user convenience, reduces support inquiries, and offers a seamless multi-account experience.

You can now use Salesforce as an identity provider, expanding the range of supported identity providers. This integration allows organizations already using Salesforce for identity management to leverage their existing infrastructure, simplifying user management and enhancing the authentication experience.

Social sign-in has been enhanced with better detection and handling of double-submit issues, especially for platforms like Facebook and Apple mobile login. These changes make the social login process more reliable, reducing errors and improving the user experience. Additionally, Ory Kratos now supports social providers in credential discovery, offering more flexibility during sign-up and sign-in flows.

One-Time Password (OTP) MFA has been improved with more robust handling of code-based authentication. The enhancements ensure a smoother flow when using OTP for multi-factor authentication (MFA), providing clearer guidance to users and improving fallback mechanisms. These updates help to prevent users from being locked out due to misconfigurations or errors during the MFA process, increasing security without compromising user convenience.

• Deprecated via Parameter for SMS 2FA: The via parameter is now deprecated when performing SMS 2FA. If not included, users will see all their phone/email addresses to perform the flow. This parameter will be removed in a future version. Ensure your identity schema has the appropriate code configuration for passwordless or 2FA login.

• Endpoint Change: The /admin/session/.../extend endpoint will now return 204 No Content for new Ory Network projects. Returning 200 with the session body will be deprecated in future versions.

• SDK Enhancements: Added new methods and support for additional actions in the SDK, improving integration capabilities.

• Password Migration Hook: Added a password migration hook to facilitate migrating passwords where the hash is unavailable, easing the transition to Ory Kratos.

• Partially Failing Batch Inserts: When batch-inserting multiple identities, conflicts or validation errors of a subset of identities in the batch still allow the rest of the identities to be inserted. The returned JSON contains the error details that led to the failure.

• Security Fixes: Fixed a security vulnerability where the code method did not respect the highest_availablesetting. Refer to the security advisory for more details.

• Session Extension Issues: Fixed issues related to session extension to prevent long response times on /session/whoami when extending sessions simultaneously.
• OIDC and Social Sign-In: Fixed UI and error handling for OpenID Connect and social sign-in flows, improving the overall experience.
• Credential Identifier Handling: Corrected handling of code credential identifiers, ensuring proper detection of phone numbers and correct functioning of SMS/email MFA.

• Concurrent Updates for Webhooks: Fixed concurrent map update issues for webhook headers, improving webhook reliability.

• Passwordless & 2FA Login: Before upgrading, ensure your identity schema has the appropriate code configuration when using the code method for passwordless or 2FA login.

• Code Method for 2FA: If you use the code method for 2FA or 1FA login but haven't configured the code identifier, set selfservice.methods.code.config.missing_credential_fallback_enabled to true to avoid user lockouts.

We hope you enjoy the new features and improvements in Ory Kratos v1.3.0. Please remember to leave a GitHub star and check out our other open-source projects. Your feedback is valuable to us, so join the Ory community and help us shape the future of identity management.

Breaking Changes

When using two-step registration, it was previously possible to send method=profile:back to get to the previous screen. This feature was not documented in the SDK API yet. Going forward, please instead use screen=previous.

Please note that the via parameter is deprecated when performing SMS 2FA. It will be removed in a future version. If the parameter is not included in the request, the user will see all their phone/email addresses from which to perform the flow.

Before upgrading, ensure that your identity schema has the appropriate code configuration when using the code method for passwordless or 2fa login.

If you are using the code method for 2FA login already, or you are using it for 1FA login but have not yet configured the code identifier, set selfservice.methods.code.config.missing_credential_fallback_enabled to true to prevent users from being locked out.

Please note that the via parameter is deprecated when performing SMS 2FA. It will be removed in a future version. If the parameter is not included in the request, the user will see all their phone/email addresses from which to perform the flow.

Before upgrading, ensure that your identity schema has the appropriate code configuration when using the code method for passwordless or 2fa login.

If you are using the code method for 2FA login already, or you are using it for 1FA login but have not yet configured the code identifier, set selfservice.methods.code.config.missing_credential_fallback_enabled to true to prevent users from being locked out.

Going forward, the /admin/session/.../extend endpoint will return 204 no content for new Ory Network projects. We will deprecate returning 200 + session body in the future.

Bug Fixes

• Add continue with only for json browser requests (#4002) (e0a4010)

• Add fallback to providerLabel (#3999) (d26f204):

  This adds a fallback to the provider label when trying to register a duplicate identifier with an oidc.

  Current error message:

  Signing in will link your account to "test@test.com" at provider "". If you do not wish to link that account, please start a new login flow.

  The label represents an optional label for the UI, but in my case it's always empty. I suggest we fallback to the provider when the label is not present. In case the label is present, the behaviour won't change.

  Fallback to provider:

  Signing in will link your account to "test@test.com" at provider "google". If you do not wish to link that account, please start a new login flow.

• Add missing JS triggers (7597bc6)

• Add PKCE config key to config schema (#4098) (2c7ff3c)
• Batch identity created event (#4111) (340f698)
• Concurrent map update for webhook header (#4055) (6ceb2f1)
• Do not populate id_first first step for account linking flows (#4074) (6ab2637)
• Downgrade go-webauthn (#4035) (4d1954a)
• Emit SelfServiceMethodUsed in SettingsSucceeded event (#4056) (76af303)
• Filter web hook headers (#4048) (ddb838e)
• Improve OIDC account linking UI (#4036) (2b4a618)
• Include duplicate credentials in account linking message (#4079) (122b63d)
• Incorrect append of code credential identifier (#4102) (3215792), closes #4076
• Jsonnet timeouts (#3979) (7c5299f)

• Move password migration hook config (#3986) (b5a66e0):

  This moves the password migration hook to

  yaml selfservice: methods: password: config: migrate_hook: ...

• Normalize code credentials and deprecate via parameter (c417b4a):

  Before this, code credentials for passwordless and mfa login were incorrectly stored and normalized. This could cause issues where the system would not detect the user's phone number, and where SMS/email MFA would not properly work with the highest_available setting.

• Passthrough correct organization ID to CompletedLoginForWithProvider (#4124) (ad1acd5)

• Password migration hook config (#4001) (50deedf):

  This fixes the config loading for the password migration hook.

• Pw migration param (#3998) (6016cc8)

• Refactor internal API to prevent panics (#4028) (81bc152)
• Remove flows from log messages (#3913) (310a405)
• Replace submit with continue button for recovery and verification and add maxlength (04850f4)

• Return credentials in FindByCredentialsIdentifier (#4068) (f949173):

  Instead of re-fetching the credentials later (expensive), we load them only once.

• Return error if invalid UUID is supplied to ids filter (#4116) (98140f2)

• security: Code credential does not respect highest_available setting (b0111d4):

  This patch fixes a security vulnerability which prevents the code method to properly report it's credentials count to the highest_available mechanism.

  For more details on this issue please refer to the security advisory.

• Timestamp precision on mysql (9a1f171)

• Transient_payload is lost when verification flow started as part of registration (#3983) (192f10f)
• Trigger oidc web hook on sign in after registration (#4027) (ad5fb09)
• Typo in login link CLI error messages (#3995) (8350625)
• Validate page tokens for better error codes (#4021) (32737dc)
• Whoami latency (#4070) (ff6ed5b)

Code Generation

• Pin v1.3.0 release commit (0a49fd0)

Documentation

• Add google to supported providers in ID Token doc strings (#4026) (955bd8f)
• Typo in changelog (c508980)

Features

• Add additional messages (735fc5b)
• Add browser return_to continue_with action (7b636d8)
• Add if method to sdk (612e3bf)

• Add redirect to continue_with for SPA flows (99c945c):

  This patch adds the new continue_with action redirect_browser_to, which contains the redirect URL the app should redirect to. It is only supported for SPA (not server-side browser apps, not native apps) flows at this point in time.

• Add social providers to credential discovery as well (5f4a2bf)

• Add support for Salesforce as identity provider (#4003) (3bf1ca9)
• Add tests for two step login (#3959) (8225e40)

• Allow deletion of an individual OIDC credential (#3968) (a43cef2):

  This extends the existing DELETE /admin/identities/{id}/credentials/{type} API to accept an ?identifier=foobar query parameter for {type}==oidc like such:

  DELETE /admin/identities/{id}/credentials/oidc?identifier=github%3A012345

  This will delete the GitHub OIDC credential with the identifier github:012345 (012345 is the subject as returned by GitHub).

  To find out which OIDC credentials exist, call GET /admin/identities/{id}?include_credential=oidc beforehand.

  This will allow you to delete individual OIDC credentials for users even if they have several set up.

• Allow partially failing batch inserts (#4083) (4ba7033):

  When batch-inserting multiple identities, conflicts or validation errors of a subset of identities in the batch still allow the rest of the identities to be inserted. The returned JSON contains the error details that lead to the failure.

• Better detection if credentials exist on identifier first login (#3963) (42ade94)

• Change method=profile:back to screen=previous (#4119) (2cd8483)
• Clarify session extend behavior (#3962) (af5ea35)

• Client-side PKCE take 3 (#4078) (f7c1024):

  • feat: client-side PKCE

  This change introduces a new configuration for OIDC providers: pkce with values auto (default), never, force.

  When auto is specified or the field is omitted, Kratos will perform autodiscovery and perform PKCE when the server advertises support for it. This requires the issuer_url to be set for the provider.

  never completely disables PKCE support. This is only theoretically useful: when a provider advertises PKCE support but doesn't actually implement it.

  force always sends a PKCE challenge in the initial redirect URL, regardless of what the provider advertises. This setting is useful when the provider offers PKCE but doesn't advertise it in his ./well-known/openid-configuration.

  Important: When setting pkce: force, you must whitelist a different return URL for your OAuth2 client in the provider's configuration. Instead of <base-url>/self-service/methods/oidc/callback/<provider>, you must use <base-url>/self-service/methods/oidc/callback (note missing last path segment). This is to enable the use of the same OAuth client ID+secret when configuring several Kratos OIDC providers, without having to whitelist individual redirect_uris for each Kratos provider config.

  • chore: regenerate SDK, bump DB versions, cleanup tool install

  • chore: get final organization ID from provider config during registration and login

  • chore: fixup OIDC function signatures and improve tests

• Emit events in identity persister (#4107) (20156f6)

• Enable new-style OIDC state generation (#4121) (eb97243)
• Identifier first auth (1bdc19a)
• Identifier first login for all first factor login methods (638b274)

• Improve session extend performance (#3948) (4e3fad4):

  This patch improves the performance for extending session lifespans. Lifespan extension is tricky as it is often part of the middleware of Ory Kratos consumers. As such, it is prone to transaction contention when we read and write to the same session row at the same time (and potentially multiple times).

  To address this, we:

  1. Introduce a locking mechanism on the row to reduce transaction contention;
  2. Add a new feature flag that toggles returning 204 no content instead of 200 + session.

  Be aware that all reads on the session table will have to wait for the transaction to commit before they return a value. This may cause long(er) response times on /session/whoami for sessions that are being extended at the same time.

• Password migration hook (#3978) (c9d5573):

  This adds a password migration hook to easily migrate passwords for which we do not have the hash.

  For each user that needs to be migrated to Ory Network, a new identity is created with a credential of type password with a config of {"use_password_migration_hook": true} . When a user logs in, the credential identifier and password will be sent to the password_migration web hook if all of these are true: The user’s identity’s password credential is {"use_password_migration_hook": true} The password_migration hook is configured After calling the password_migration hook, the HTTP status code will be inspected: On 200, we parse the response as JSON and look for {"status": "password_match"}. The password credential config will be replaced with the hash of the actual password. On any other status code, we assume that the password is not valid.

• sdk: Add missing profile discriminator to update registration (0150795)

• sdk: Avoid eval with javascript triggers (dd6e53d):

  Using OnLoadTrigger and OnClickTrigger one can now map the trigger to the corresponding JavaScript function.

  For example, trigger {"on_click_trigger":"oryWebAuthnRegistration"} should be translated to window.oryWebAuthnRegistration():

  if (attrs.onClickTrigger) { window[attrs.onClickTrigger]() }

• Separate 2fa refresh from 1st factor refresh (#3961) (89355d8)

• Set maxlength for totp input (51042d9)

Tests

• Add form hydration tests for code login (37781a9)
• Add form hydration tests for idfirst login (633b0ba)
• Add form hydration tests for oidc login (df0cdcb)
• Add form hydration tests for passkey login (a777854)
• Add form hydration tests for password login (7186e7e)
• Add form hydration tests for webauthn login (8b68163)
• Add tests for idfirst (5f76c15)
• Additional code credential test case (#4122) (4f2c854)
• Deflake and parallelize persister tests (#3953) (61f87d9)
• Deflake session extend config side-effect (#3950) (b192c92)
• Enable server-side config from context (#3954) (e0001b0)
• Improve stability of refresh test (#4037) (68693a4)
• Resolve CI failures (#4067) (dbf7274)
• Resolve issues and update snapshots for all selfservice strategies (e2e81ac)
• Update incorrect usage of Auth0 in Salesforce tests (#4007) (6ce3068)
• Verify redirect continue_with in hook executor for browser clients (7b0b94d)

Unclassified

• Merge commit from fork (123e807):

  • fix(security): code credential does not respect highest_available setting

  This patch fixes a security vulnerability which prevents the code method to properly report it's credentials count to the highest_available mechanism.

  For more details on this issue please refer to the security advisory.

  • fix: normalize code credentials and deprecate via parameter

  Before this, code credentials for passwordless and mfa login were incorrectly stored and normalized. This could cause issues where the system would not detect the user's phone number, and where SMS/email MFA would not properly work with the highest_available setting.

• Update .github/workflows/ci.yaml (2d60772)

• Update Code QL action to v2 (#4008) (e3f1da0)

Changelog

• [123e80] Merge commit from fork
• [2d6077] Update .github/workflows/ci.yaml
• [4e25ce] autogen(docs): generate and bump docs
• [276fb5] autogen(docs): regenerate and update changelog
• [784033] autogen(docs): regenerate and update changelog
• [aa48c6] autogen(docs): regenerate and update changelog
• [4e2902] autogen(docs): regenerate and update changelog
• [4f4394] autogen(docs): regenerate and update changelog
• [5b251c] autogen(docs): regenerate and update changelog
• [014be3] autogen(docs): regenerate and update changelog
• [2a6e22] autogen(docs): regenerate and update changelog
• [45bbec] autogen(docs): regenerate and update changelog
• [114659] autogen(docs): regenerate and update changelog
• [702e1e] autogen(docs): regenerate and update changelog
• [d72f45] autogen(docs): regenerate and update changelog
• [ff9021] autogen(docs): regenerate and update changelog
• [e451b7] autogen(docs): regenerate and update changelog
• [3db425] autogen(docs): regenerate and update changelog
• [358521] autogen(docs): regenerate and update changelog
• [7674f4] autogen(docs): regenerate and update changelog
• [198e79] autogen(docs): regenerate and update changelog
• [fa2da7] autogen(docs): regenerate and update changelog
• [7e7fdc] autogen(docs): regenerate and update changelog
• [78bc47] autogen(docs): regenerate and update changelog
• [def622] autogen(docs): regenerate and update changelog
• [630c48] autogen(docs): regenerate and update changelog
• [4547e8] autogen(openapi): regenerate swagger spec and internal client
• [369aad] autogen(openapi): regenerate swagger spec and internal client
• [bcffb6] autogen(openapi): regenerate swagger spec and internal client
• [7f20ad] autogen(openapi): regenerate swagger spec and internal client
• [c910b4] autogen(openapi): regenerate swagger spec and internal client
• [7df3d5] autogen(openapi): regenerate swagger spec and internal client
• [020a9d] autogen(openapi): regenerate swagger spec and internal client
• [8bd742] autogen(openapi): regenerate swagger spec and internal client
• [b27e84] autogen(openapi): regenerate swagger spec and internal client
• [b29dff] autogen(openapi): regenerate swagger spec and internal client
• [278d8e] autogen(openapi): regenerate swagger spec and internal client
• [30dd9c] autogen(openapi): regenerate swagger spec and internal client
• [bac030] autogen(openapi): regenerate swagger spec and internal client
• [1d9ef4] autogen(openapi): regenerate swagger spec and internal client
• [ba0f30] autogen: add v1.2.0 to version.schema.json
• [0a49fd] autogen: pin v1.3.0 release commit
• [72aae5] autogen: pin v1.3.0-pre.0 release commit
• [de70e4] chore(deps): bump body-parser and express in /test/e2e/proxy (#4093)
• [74fd78] chore(deps): bump express from 4.18.2 to 4.20.0 in /test/e2e/proxy (#4095)
• [ba2aac] chore(deps): bump github.com/opencontainers/runc from 1.1.13 to 1.1.14 (#4075)
• [7d6a45] chore(deps): bump serve-static and express in /test/e2e/proxy (#4091)
• [0213ed] chore: add kubescape image scanner (#3947)
• [dbe9d1] chore: add missing text message fields (#4066)
• [4fb28b] chore: align internal SDK with published SDK (#4019)
• [6129ec] chore: bump dependencies (#4017)
• [54cb46] chore: don't return allowed return URLs (#4044)
• [a84fb3] chore: improve courier logging (#3985)
• [5830ff] chore: improve tracing for selfservice strategies (#4061)
• [1bc4dc] chore: move b2b config to selfservice section (#3949)
• [f125f7] chore: re-add WithIdentifier (#3992)
• [9aefc0] chore: refactor API in package cipher for easier dependency injection (#4103)
• [5d8e32] chore: regenerate SDK
• [4ace17] chore: regenerate SDK and format code
• [326055] chore: regenerate config types
• [2ad0ed] chore: remove max length
• [b7102c] chore: rename one_step to unified
• [0dec42] chore: sdk+ci (#4088)
• [559202] chore: update CI, dependencies, and some inaccurate assertions (#4085)
• [671368] chore: update newsletter link (#4011)
• [9894d0] chore: update repository templates to https://github.com/ory/meta/commit/297c8a5a3563dacb5fb28b60436623ee5608726e
• [9001c4] chore: update repository templates to https://github.com/ory/meta/commit/3cf0f005564ff7e18f13640dd3dab677f610049f
• [5d372a] chore: update repository templates to https://github.com/ory/meta/commit/4132def510aefccb5bdb55519823bff9b7be5bc7
• [b0a8a3] chore: update repository templates to https://github.com/ory/meta/commit/939b80fbfd795b1e137654c60deac78b752e7196
• [5c650c] chore: update repository templates to https://github.com/ory/meta/commit/95e82c6db80b6928cfb4a27f165e1ed70d52dee4
• [794510] chore: update repository templates to https://github.com/ory/meta/commit/fe4ffe081358634ef4d59fdc2ffe2741c63981c8
• [2800fc] chore: updated snapshots and clean up
• [f7c38f] chore: upgrade dockertest to address cve (#4038)
• [aa7f95] chore: upgrade goreleaser to v2 (#4123)
• [a702fd] chore: use correct import
• [180287] chore: use label in link/unlink settings nodes (#3977)
• [e3f1da] deps: update Code QL action to v2 (#4008)
• [955bd8] docs: add google to supported providers in ID Token doc strings (#4026)
• [c50898] docs: typo in changelog
• [015079] feat(sdk): add missing profile discriminator to update registration
• [dd6e53] feat(sdk): avoid eval with javascript triggers
• [735fc5] feat: add additional messages
• [7b636d] feat: add browser return_to continue_with action
• [612e3b] feat: add if method to sdk
• [99c945] feat: add redirect to continue_with for SPA flows
• [5f4a2b] feat: add social providers to credential discovery as well
• [3bf1ca] feat: add support for Salesforce as identity provider (#4003)
• [8225e4] feat: add tests for two step login (#3959)
• [a43cef] feat: allow deletion of an individual OIDC credential (#3968)
• [4ba703] feat: allow partially failing batch inserts (#4083)
• [42ade9] feat: better detection if credentials exist on identifier first login (#3963)
• [2cd848] feat: change method=profile:back to screen=previous (#4119)
• [af5ea3] feat: clarify session extend behavior (#3962)
• [f7c102] feat: client-side PKCE take 3 (#4078)
• [20156f] feat: emit events in identity persister (#4107)
• [eb9724] feat: enable new-style OIDC state generation (#4121)
• [1bdc19] feat: identifier first auth
• [638b27] feat: identifier first login for all first factor login methods
• [4e3fad] feat: improve session extend performance (#3948)
• [c9d557] feat: password migration hook (#3978)
• [89355d] feat: separate 2fa refresh from 1st factor refresh (#3961)
• [51042d] feat: set maxlength for totp input
• [b0111d] fix(security): code credential does not respect highest_available setting
• [2c7ff3] fix: add PKCE config key to config schema (#4098)
• [e0a401] fix: add continue with only for json browser requests (#4002)
• [d26f20] fix: add fallback to providerLabel (#3999)
• [7597bc] fix: add missing JS triggers
• [340f69] fix: batch identity created event (#4111)
• [6ceb2f] fix: concurrent map update for webhook header (#4055)
• [6ab263] fix: do not populate id_first first step for account linking flows (#4074)
• [4d1954] fix: downgrade go-webauthn (#4035)
• [76af30] fix: emit SelfServiceMethodUsed in SettingsSucceeded event (#4056)
• [ddb838] fix: filter web hook headers (#4048)
• [2b4a61] fix: improve OIDC account linking UI (#4036)
• [122b63] fix: include duplicate credentials in account linking message (#4079)
• [321579] fix: incorrect append of code credential identifier (#4102)
• [7c5299] fix: jsonnet timeouts (#3979)
• [b5a66e] fix: move password migration hook config (#3986)
• [c417b4] fix: normalize code credentials and deprecate via parameter
• [ad1acd] fix: passthrough correct organization ID to CompletedLoginForWithProvider (#4124)
• [50deed] fix: password migration hook config (#4001)
• [6016cc] fix: pw migration param (#3998)
• [81bc15] fix: refactor internal API to prevent panics (#4028)
• [310a40] fix: remove flows from log messages (#3913)
• [04850f] fix: replace submit with continue button for recovery and verification and add maxlength
• [f94917] fix: return credentials in FindByCredentialsIdentifier (#4068)
• [98140f] fix: return error if invalid UUID is supplied to ids filter (#4116)
• [9a1f17] fix: timestamp precision on mysql
• [192f10] fix: transient_payload is lost when verification flow started as part of registration (#3983)
• [ad5fb0] fix: trigger oidc web hook on sign in after registration (#4027)
• [835062] fix: typo in login link CLI error messages (#3995)
• [32737d] fix: validate page tokens for better error codes (#4021)
• [ff6ed5] fix: whoami latency (#4070)
• [37781a] test: add form hydration tests for code login
• [633b0b] test: add form hydration tests for idfirst login
• [df0cdc] test: add form hydration tests for oidc login
• [a77785] test: add form hydration tests for passkey login
• [7186e7] test: add form hydration tests for password login
• [8b6816] test: add form hydration tests for webauthn login
• [5f76c1] test: add tests for idfirst
• [4f2c85] test: additional code credential test case (#4122)
• [61f87d] test: deflake and parallelize persister tests (#3953)
• [b192c9] test: deflake session extend config side-effect (#3950)
• [e0001b] test: enable server-side config from context (#3954)
• [68693a] test: improve stability of refresh test (#4037)
• [dbf727] test: resolve CI failures (#4067)
• [e2e81a] test: resolve issues and update snapshots for all selfservice strategies
• [6ce306] test: update incorrect usage of Auth0 in Salesforce tests (#4007)
• [7b0b94] test: verify redirect continue_with in hook executor for browser clients

Artifacts can be verified with cosign using this public key.