Allow users to change their passwords

caution

SuperTokens does not provide the UI for users to change/update their password, you will need to create the UI and setup a route on your backend to have this functionality.

In this section we will go over how you can create a route on your backend which can update a user's password. Calling this route will check if the old password is valid and update the user's profile with the new password.

Step 1: Creating the `/change-password` route#

You will need to create a route on your backend which is protected by the session verification middleware, this will ensure that only a authenticated user can access the protected route.
To learn more about how to use the session verfication middleware for other frameworks click here

NodeJS
GoLang
Python

import { verifySession } from "supertokens-node/recipe/session/framework/express";
import { SessionRequest } from "supertokens-node/framework/express"
import express from "express";

let app = express();

app.post("/change-password", verifySession(), async (req: SessionRequest, res: express.Response) => {
    // TODO: see next steps
})

import (
    "net/http"

    "github.com/supertokens/supertokens-golang/recipe/session"
)

// the following example uses net/http
func main() {
    _ = http.HandlerFunc(func(rw http.ResponseWriter, r *http.Request) {
        // Wrap the API handler in session.VerifySession
        session.VerifySession(nil, changePasswordAPI).ServeHTTP(rw, r)
    })
}

func changePasswordAPI(w http.ResponseWriter, r *http.Request) {
    // TODO: see next steps
}

# the following example uses flask
from supertokens_python.recipe.session.framework.flask import verify_session
from flask import Flask

app = Flask(__name__)

@app.route('/change-password', methods=['POST']) 
@verify_session()
def change_password():
    pass # TODO: see next steps

Step 2: Validate and update the user's password#

You can now use session object to retrive the logged in user's userId.
Use the recipe's sign in function and check if the old password is valid
Update the user's password.

NodeJS
GoLang
Python

// the following example uses express
import ThirdPartyEmailPassword from "supertokens-node/recipe/thirdpartyemailpassword";
import { verifySession } from "supertokens-node/recipe/session/framework/express";
import { SessionRequest } from "supertokens-node/framework/express"
import express from "express";

let app = express();

app.post("/change-password", verifySession(), async (req: SessionRequest, res: express.Response) => {

    // get the supertokens session object from the req
    let session = req.session

    // retrive the old password from the request body
    let oldPassword = req.body.oldPassword

    // retrive the new password from the request body
    let updatedPassword = req.body.newPassword

    // get the user's Id from the session
    let userId = session!.getUserId()

    // get the signed in user's email from the getUserById function
    let userInfo = await ThirdPartyEmailPassword.getUserById(userId)

    if (userInfo === undefined) {
        throw new Error("Should never come here")
    }

    // call signin to check that input password is correct
    let isPasswordValid = await ThirdPartyEmailPassword.emailPasswordSignIn(userInfo.email, oldPassword)

    if (isPasswordValid.status !== "OK") {
        // TODO: handle incorrect password error
        return
    }

    // validate the new password
    let passwordValidationResponse = passwordValidator(updatedPassword);
    if(passwordValidationResponse !== undefined) {
        // TODO: handle invalid password error
        return
    }


    // update the user's password using updateEmailOrPassword
    let response = await ThirdPartyEmailPassword.updateEmailOrPassword({
        userId,
        password: updatedPassword
    })
    
    // TODO: send successful password update response

})

function passwordValidator(value: string): string | undefined {
    // length >= 8 && < 100
    // must have a number and a character
    // as per https://github.com/supertokens/supertokens-auth-react/issues/5#issuecomment-709512438

    if (value.length < 8) {
        return "Password must contain at least 8 characters, including a number";
    }

    if (value.length >= 100) {
        return "Password's length must be lesser than 100 characters";
    }

    if (value.match(/^.*[A-Za-z]+.*$/) === null) {
        return "Password must contain at least one alphabet";
    }

    if (value.match(/^.*[0-9]+.*$/) === null) {
        return "Password must contain at least one number";
    }

    return undefined;
}

caution

If you have declared custom password validation policies please add the policies to the passwordValidator function defined in the code snippet above. The updateEmailOrPassword function will not apply custom password validation policies.

import (
    "encoding/json"
    "net/http"
    "reflect"
    "regexp"

    "github.com/supertokens/supertokens-golang/recipe/session"
    "github.com/supertokens/supertokens-golang/recipe/thirdpartyemailpassword"
)

func main() {
    _ = http.HandlerFunc(func(rw http.ResponseWriter, r *http.Request) {
        // Wrap the API handler in session.VerifySession
        session.VerifySession(nil, changePasswordAPI).ServeHTTP(rw, r)
    })
}

type RequestBody struct {
    OldPassword string
    NewPassword string
}

func changePasswordAPI(w http.ResponseWriter, r *http.Request) {

    // retrieve the session object as shown below
    sessionContainer := session.GetSessionFromRequestContext(r.Context())

    // retrive the old password from the request body
    var requestBody RequestBody
    err := json.NewDecoder(r.Body).Decode(&requestBody)
    if err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }

    // get the userId from the session
    userID := sessionContainer.GetUserID()

    // get the signed in user's email from the getUserById function
    userInfo, err := thirdpartyemailpassword.GetUserById(userID)
    if err != nil {
        // TODO: Handle error
        return
    }

    // call signin to check that the input is correct
    isPasswordValid, err := thirdpartyemailpassword.EmailPasswordSignIn(userInfo.Email, requestBody.OldPassword)
    if err != nil {
        // TODO: Handle error
        return
    }

    if isPasswordValid.OK != nil {
        // TODO: Handle error
        return
    }
    
    // validate the new password
    passwordValidationResponse := passwordValidator(requestBody.NewPassword)
    if passwordValidationResponse != nil {
        // TODO: Handle error
        return
    }

    _, err = thirdpartyemailpassword.UpdateEmailOrPassword(userID, &userInfo.Email, &requestBody.NewPassword)
    if err != nil {
        // TODO: Handle error
        return
    }
    // TODO: send successful password update response

}

func passwordValidator(value interface{}) *string {
    // length >= 8 && < 100
    // must have a number and a character

    if reflect.TypeOf(value).Kind() != reflect.String {
        msg := "Development bug: Please make sure the password field yields a string"
        return &msg
    }
    if len(value.(string)) < 8 {
        msg := "Password must contain at least 8 characters, including a number"
        return &msg
    }
    if len(value.(string)) >= 100 {
        msg := "Password's length must be lesser than 100 characters"
        return &msg
    }
    alphaCheck, err := regexp.Match(`^.*[A-Za-z]+.*$`, []byte(value.(string)))
    if err != nil || !alphaCheck {
        msg := "Password must contain at least one alphabet"
        return &msg
    }
    numCheck, err := regexp.Match(`^.*[0-9]+.*$`, []byte(value.(string)))
    if err != nil || !numCheck {
        msg := "Password must contain at least one number"
        return &msg
    }
    return nil
}

caution

If you have declared custom password validation policies please add the policies to the passwordValidator function defined in the code snippet above. The UpdateEmailOrPassword function will not apply custom password validation policies.

from re import fullmatch
from typing import Union

from supertokens_python.recipe.session.framework.flask import verify_session
from supertokens_python.recipe.session import SessionContainer
from supertokens_python.recipe.thirdpartyemailpassword.syncio import get_user_by_id, emailpassword_sign_in, update_email_or_password
from supertokens_python.recipe.thirdpartyemailpassword.interfaces import EmailPasswordSignInWrongCredentialsError
from flask import g

@app.route('/change-password', methods=['POST']) 
@verify_session()
def change_password():

    session: SessionContainer = g.supertokens 
    
    # get the userId from the session object
    user_id = session.get_user_id()

    # get the signed in user's email from the getUserById function
    users_info = get_user_by_id(user_id)

    if users_info is None:
        raise Exception("Should never come here")

    # call signin to check that the input password is correct
    isPasswordValid = emailpassword_sign_in(users_info.email, request.json["oldPassword"]) 

    if isinstance(isPasswordValid, EmailPasswordSignInWrongCredentialsError):
        # TODO: handle incorrect password error
        return

    # validate the new password
    password_validation_response = password_validator(request.json["newPassword"]) 
    
    if password_validation_response is not None:
        # TODO: handle invalid password error
        return
    
    # update the users password
    update_email_or_password(user_id, password=request.json["newPassword"]) 

    # TODO: send successful password update response

def password_validator(value: str) -> Union[str, None]:
    # length >= 8 && < 100
    # must have a number and a character
    # as per
    # https://github.com/supertokens/supertokens-auth-react/issues/5#issuecomment-709512438
    if len(value) < 8:
        return "Password must contain at least 8 characters, including a number"

    if len(value) >= 100:
        return "Password's length must be lesser than 100 characters"

    if fullmatch(r"^.*[A-Za-z]+.*$", value) is None:
        return "Password must contain at least one alphabet"

    if fullmatch(r"^.*[0-9]+.*$", value) is None:
        return "Password must contain at least one number"

    return None

caution

If you have declared custom password validation policies please add the policies to the password_validator function defined in the code snippet above. The update_email_or_password function will not apply custom password validation policies.

Step 3: Revoke all sessions associated with the user (optional)#

Revoking all sessions associated with the user will force them to reauthenticate with their new password.

NodeJS
GoLang
Python

// the following example uses express
import ThirdPartyEmailPassword from "supertokens-node/recipe/thirdpartyemailpassword";
import Session from "supertokens-node/recipe/session";
import { verifySession } from "supertokens-node/recipe/session/framework/express";
import { SessionRequest } from "supertokens-node/framework/express"
import express from "express";

let app = express();

app.post("/change-password", verifySession(), async (req: SessionRequest, res: express.Response) => {

   let userId = req.session!.getUserId();

    /**
     * 
     * ...
     * see previous step
     * ...
     * 
     *  */

    // revoke all sessions for the user
    await Session.revokeAllSessionsForUser(userId)

    // revoke the current user's session, we do this to remove the auth cookies, logging out the user on the frontend.
    await req.session!.revokeSession()

    // TODO: send successful password update response

})

import (
    "net/http"

    "github.com/supertokens/supertokens-golang/recipe/session"
)

func main() {
    _ = http.HandlerFunc(func(rw http.ResponseWriter, r *http.Request) {
        // Wrap the API handler in session.VerifySession
        session.VerifySession(nil, changePasswordAPI).ServeHTTP(rw, r)
    })
}

type ResponseBody struct {
    OldPassword string
    NewPassword string
}

func changePasswordAPI(w http.ResponseWriter, r *http.Request) {

    // retrieve the session object as shown below
    sessionContainer := session.GetSessionFromRequestContext(r.Context())
    userID := sessionContainer.GetUserID()

    /**
     *
     * ...
     * see previous step
     * ...
     *
     *  */


    // revoke all sessions for the user
    _, err := session.RevokeAllSessionsForUser(userID)
    if err != nil {
        // TODO: Handle error
    }

    // revoke the user's current session, we do this to remove the auth cookies, logging out the user on the frontend
    err = sessionContainer.RevokeSession()
    if err != nil {
        // TODO: Handle error
    }


    // TODO: send successful password update response
}

from supertokens_python.recipe.session.framework.flask import verify_session
from supertokens_python.recipe.session.syncio import revoke_all_sessions_for_user
from flask import Flask
from supertokens_python.recipe.session import SessionContainer

app = Flask(__name__)
@app.route('/change-password', methods=['POST']) 
@verify_session()
def change_password():
    
    session: SessionContainer = g.supertokens 
    
    # get the userId from the session object
    user_id = session.get_user_id()

    # TODO: see previous step...

    # revoke all sessions for the user
    revoke_all_sessions_for_user(user_id)
    
    # revoke the user's current session, we do this to remove the auth cookies, logging out the user on the frontend
    session.sync_revoke_session()

    # TODO: send successful password update response

Auth Methods

Add ons

Allow users to change their passwords

caution

Step 1: Creating the `/change-password` route#

Step 2: Validate and update the user's password#

caution

caution

caution

Step 3: Revoke all sessions associated with the user (optional)#

caution

Step 1: Creating the /change-password route#

Step 2: Validate and update the user's password#

caution

caution

caution

Step 3: Revoke all sessions associated with the user (optional)#

Step 1: Creating the `/change-password` route#