Version: v0.4

Change Password

This document summarizes exemplary request payloads for performing "change password" flows using the user settings flow with the password strategy.

ORY Kratos will prompt the user to re-authenticate before the password is changed, similar to the GitHub sudo mode.

You can configure how long a session is "privileged" by setting:

path/to/kratos/config.yml
selfservice:
flows:
settings:
# Sessions older than a minute requires the user to sign in again before
# the password is changed.
privileged_session_max_age: 1m

Browser Clients

Redirecting the browser to the Self-Service Settings Endpoint initiates the flow. If the password strategy is enabled, the Settings Request Response Payload will include a password method:

$ curl http://<kratos-admin>/self-service/browser/flows/requests/settings?request=71da1753-e135-441c-b4df-e7b7cd90ad88
{
id: '71da1753-e135-441c-b4df-e7b7cd90ad88',
expires_at: '2020-05-02T15:52:09.67209Z',
issued_at: '2020-05-02T14:52:09.67209Z',
request_url: 'http://127.0.0.1:4433/self-service/browser/flows/settings',
methods: {
// "profile": ...
// "oidc": ...
password: {
method: 'password',
config: {
action: 'http://127.0.0.1:4455/.ory/kratos/public/self-service/browser/flows/settings/strategies/password?request=71da1753-e135-441c-b4df-e7b7cd90ad88',
method: 'POST',
fields: [
{
name: 'password',
type: 'password',
required: true
},
{
name: 'csrf_token',
type: 'hidden',
required: true,
value: 'UjEPiUMubRiAl0NG7yUzsww8XjpJvW+HBrh6JirjLxPqhlW2ql+0kYknjd8gdsx0v08vQSmqUEcZhNPsvkr2Kw=='
}
]
}
}
},
identity: {
id: 'f48c43bb-50ea-4520-9280-37a891175aba',
traits: {
email: 'h71x9a@j6r8c'
}
},
state: 'show_form'
}

Once submitted, the password is validated. If validation fails, the reason will be included:

$ curl http://<kratos-admin>/self-service/browser/flows/requests/settings?request=71da1753-e135-441c-b4df-e7b7cd90ad88
{
id: '71da1753-e135-441c-b4df-e7b7cd90ad88',
// expires_at, ...
active: 'password', // <- this is now set!
methods: {
password: {
method: 'password',
config: {
// action, method ...
messages: [
{
/* id, type */
text: 'Please check the data you provided.'
}
],
fields: [
// ...
{
name: 'password',
type: 'password',
required: true,
messages: [
{
/* id, type */
text: 'password: password is required'
}
]
}
]
}
}
},
// identity, ...
state: 'show_form'
}

A successful flow will be marked with:

$ curl http://<kratos-admin>/self-service/browser/flows/requests/settings?request=71da1753-e135-441c-b4df-e7b7cd90ad88
{
id: '71da1753-e135-441c-b4df-e7b7cd90ad88',
// expires_at, active, methods, ...
state: 'success'
}

API Clients

API-based login and registration using this strategy will be addressed in a future release of ORY Kratos.

Security and Defenses

Please head over to Username / Email and Password Security and Defenses

Last updated on by aeneasr