Skip to main content
Version: v0.3

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:
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"
}
},
"update_successful": false
}

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 ...
errors: [
{
message: 'Please check the data you provided.',
},
],
fields: [
// ...
{
name: 'password',
type: 'password',
required: true,
errors: [
{
message: 'password: password is required',
},
],
},
],
},
},
},
// identity, ...
update_successful: false,
}

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, ...
update_successful: true,
}

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