[Design Discussion] Require current credential verification on self-service credential update

[janithjay]

Related Feature Issue

#5291

Problem Summary

POST /users/me/update-credentials accepts {"attributes": {"password": "..."}} and writes the new credential immediately. The only thing authorizing that write today is possession of an access token for the account, so anyone holding a stolen token, a leaked cookie, or an unlocked laptop can set a new password and permanently lock the real owner out.

High-Level Approach

• Require proof of the current password before the self-service write is allowed. The admin reset path in internal/user (used by the Console) is a separate handler and stays as-is, since an admin resetting someone else's password has no way to supply that user's current secret.
• Accept the current password as a field alongside the new credential in the same request, verified server-side against the stored hash before anything is written.
• Fail the same way whether the supplied current password is missing or simply wrong, so the response doesn't leak whether the account has a password set.

Architecture Overview

Component	Change
internal/entity	New lookup: compare a plaintext value against an entity's stored credential of a given type, and report which credential types are actually configured for an entity
internal/user self-service handler	Gains the verification step before the existing write, request body gains a currentPassword field
internal/user admin reset handler	Unchanged, no current-password requirement
api/user.yaml	New request field, new 401 case on the self-service endpoint

Proposed wire shape:

POST /users/me/update-credentials
{ "currentPassword": "0ldP@ss!", "attributes": { "password": "n3wP@ss!" } }

-> 204 No Content
-> 401 on an invalid or missing current password

Proposed request flow

sequenceDiagram
    participant C as Client (SDK)
    participant A as Self-service API
    participant V as Credential Verification
    participant D as Data Store

    C->>A: POST /users/me/update-credentials<br/>{currentPassword, attributes: {password}}
    A->>V: verify(entityID, "password", currentPassword)
    V->>D: read stored credential
    D-->>V: stored hash (or none)

    alt no credential stored yet
        V-->>A: nothing to check against
        Note over A: open question — see Q4
    else credential stored
        V->>V: compare against stored hash
        alt match
            V-->>A: verified
            A->>D: write new credential
            A-->>C: 204 No Content
        else no match
            V-->>A: not verified
            A-->>C: 401
        end
    end

Loading

Security Considerations

• Closes the stolen-session-to-permanent-takeover path. A leaked token still grants read access until it expires, but can no longer be escalated into ownership of the account.
• The current password value must never be logged or included in error responses.
• The admin reset path must not gain this requirement, since it has no way to satisfy it.
• Access tokens already issued are not revoked by a credential change. Reaching it from here is a separate, larger change.
• No rate limiting is proposed here for verification attempts, which would otherwise make the endpoint an online guessing oracle for the current password

Impacted Areas

• internal/user (self-service and admin credential handlers, service, model)
• internal/entity (credential verification)
• api/user.yaml
• Client SDKs (new request field)

Alternatives Considered

Alternative 1: Step-up re-authentication instead of a payload field

• Cons: no mechanism exists today to trigger a fresh authentication mid-session and gate a write on it, a new subsystem, not a small addition.
• Decision: not pursued now, doesn't rule out combining both later.

Alternative 2: Rely on the endpoint already being protected and change nothing

• Cons: a protected API is not proof the account owner is the one driving the request.
• Decision: rejected, this is why it isn't a blocking issue.

Questions for Community Input

1. For a local (non-federated) account with no password configured yet, should a first-time set be allowed with no proof at all, or does that also need some form of verification?
2. Is 401 the right status for an invalid current password on an otherwise authenticated request, or should it be 403?

[Dilusha-Madushan]

For the initial password setup, we can handle the entire process through flows and only allow credential updates when the credential values already exist. The flow can enforce the necessary user verification steps before allowing the credential to be set, similar to how we handle credential recovery flows.

[UdeshAthukorala]

• The architecture table proposes a new entity lookup to "compare a plaintext value against an entity's stored credential of a given type." AuthenticateEntityByID(ctx, entityID, credentials) is already on EntityServiceInterface (backend/internal/entity/service.go:69, impl at :480) and does exactly that. So can't we reuse the existing implementation? WDYT @rajithacharith ?
• Is 401 the right status for an invalid current password on an otherwise authenticated request, or should it be 403?
  • Regarding this question I am prefer to use 403 instead of 401.
  • handleError already maps ErrorAuthenticationFailed (USR-1018) to 401, and the self-service handler returns it when the token carries no subject (backend/internal/user/handler.go:452-456, mapping at :577). If wrong-current-password reuses that, a client cannot distinguish "your token is bad, re-authenticate" from "you mistyped your old password". So in my opinion I belive this needs a distinct error code. I'd prefer 403, since the request is authenticated and RFC 9110 expects a WWW-Authenticate challenge on a 401, which does not fit here.

[janithjay]

Agree. AuthenticateEntityByID already does this, no point standing up a second method that does the same hash comparison. I'll drop that from the plan and just call AuthenticateEntityByID from the self-service side.

And agreed on 403. 401 implies "go authenticate again," but the token's fine here, it's just the wrong old password. Wasn't distinguishable from a bad token before, will give it its own code and put it on 403.

[janithjay]

Updated design after the review

Thanks @UdeshAthukorala and @Dilusha-Madushan. Here is where this landed and what is now implemented in #5290.

What changed from the original proposal

Area	Original proposal	Now
Credential check	New lookup in internal/entity to compare a plaintext value against a stored credential	Dropped. Reuses AuthenticateEntityByID, which already does this
Status code	401 on an invalid current password	403 with a new code USR-1029
Request body	currentPassword field added to the existing request	New UpdateSelfCredentialsRequest, with currentPassword as a sibling of attributes
First-time set (Q1)	Open question	Allowed with no proof, see below

On the first two, @UdeshAthukorala was right on both counts. There was no reason to add a second method that does the same hash comparison, and 401 would have told the client its token was bad when the token is fine. USR-1029 is now its own code so a client can tell "wrong old password" apart from "re-authenticate".

Final behaviour

Case	Result
Account has a password, correct current password	204, credential written
Account has a password, wrong current password	403 with USR-1029
Account has a password, currentPassword missing	403 with USR-1029, same response as a wrong one
Account has no password yet	Write proceeds, nothing to verify against
Admin path POST /users/{userId}/update-credentials	Unchanged, still needs no current password

Verification runs for any credential type being written, not only when the new value is a password.

Answer to Q1, the first-time set

We are allowing it with no proof, for now.

There is nothing to check the request against, so the only options were to allow it or to reject it. We tried rejecting it first. Rejecting would have taken away something that works today from federated users, OTP only users, and invited users, and given them nothing in return. They would have had no way to ever set a password.

So the order matters here. Build the verified setup path first, then close this door. Closing it first just breaks people.

Worth noting this is the safer direction to move in later. Going from allowed to rejected is a breaking change. Going from rejected back to allowed is not. So shipping the permissive version now does not paint us into a corner.

On handling initial setup through flows

@Dilusha-Madushan this is the right long term answer and I agree with it. It is also bigger than this change.

It is wider than self-service credential updates. I am raising it as its own design discussion rather than folding it into this one, and I will link it here once it is up. The idea is one flow per credential type, pointed at from server config the same way userDeletionFlow already works, with the current endpoint kept as the fallback when no flow is configured.

One thing that will need care there: flow composition is open ended and there is no validation rule stopping someone putting credentialSetter straight after START. If that is allowed, the flow path reopens exactly what this change closes.

Client side

The SDK reads the user type schema from /users/me/meta and only offers the change password form when that schema has a password attribute. When it does not, the form is shown disabled behind a message explaining why, rather than silently not appearing.

The current password field is not required on the client. Only the server knows whether the account has a password, so blocking submission on that field would lock out the users who do not have one. If the server does need it and it is missing or wrong, the 403 is shown inline on that field.

Not covered here

• Rate limiting on verification attempts. Still not addressed, and it makes the endpoint a guessing oracle for the current password. Worth its own issue.
• Existing access tokens are not revoked when the credential changes.
• How an account can end up with no credentials at all, which is the thing that makes the first-time set case exist. That is An admin created user / invited user can finish registration with zero credentials and no way to ever sign in #5285.

Related: #5290, #5285