Password Authentication

This authentication guide is meant for developers that are NOT using Descope to design login screens and authentication flows. If you’d like to use Descope Flows, Quick Start should be your starting point.

Introduction

The Passwords Authentication Method lets you authenticate end users using a secret string of characters known only to the user.

Descope recommends using an email address as the user identifier; this allows you to utilize passwordless methods like Magic Link in addition to passwords. These methods could be used for authentication when users forget their password or need to reset it easily.

Use Cases

New user signup: The following actions must be completed, first User Sign-Up this returns a jwt for the user.
Existing user signin: The following actions must be completed, first User Sign-In this returns a jwt for the user.

Install SDK

NodeJSPythonGoJava

npm i --save @descope/node-sdk

pip3 install descope

go get github.com/descope/go-sdk

// Include the following in your `pom.xml` (Maven)
<dependency>
    <artifactId>java-sdk</artifactId>
    <groupId>com.descope</groupId>
    <version>sdk-version</version> // Check https://github.com/descope/descope-java/releases for the latest versions
</dependency>

Import and initialize SDK

NodeJSPythonGoJava

import DescopeClient from '@descope/node-sdk';
try{
    //  baseUrl="<URL>" // When initializing the Descope clientyou can also configure the baseUrl ex: https://auth.company.com  - this is useful when you utilize CNAME within your Descope project.
    const descopeClient = DescopeClient({ projectId: '__ProjectID__' });
} catch (error) {
    // handle the error
    console.log("failed to initialize: " + error)
}

// Note that you can handle async operation failures and capture specific errors to customize errors.
//     An example can be found here: https://github.com/descope/node-sdk?tab=readme-ov-file#error-handling

from descope import (
    REFRESH_SESSION_TOKEN_NAME,
    SESSION_TOKEN_NAME,
    AuthException,
    DeliveryMethod,
    DescopeClient,
    AssociatedTenant,
    RoleMapping,
    AttributeMapping,
    LoginOptions
)
try:
    # You can configure the baseURL by setting the env variable Ex: export DESCOPE_BASE_URI="https://auth.company.com  - this is useful when you utilize CNAME within your Descope project."
    descope_client = DescopeClient(project_id='__ProjectID__')
except Exception as error:
    # handle the error
    print ("failed to initialize. Error:")
    print (error)

import "github.com/descope/go-sdk/descope"
import "github.com/descope/go-sdk/descope/client"

// Utilizing the context package allows for the transmission of context capabilities like cancellation
//      signals during the function call. In cases where context is absent, the context.Background()
//      function serves as a viable alternative.
//      Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
import (
	"context"
)

// DescopeBaseURL // within the client.Config, you can also configure the baseUrl ex: https://auth.company.com  - this is useful when you utilize CNAME within your Descope project.

descopeClient, err := client.NewWithConfig(&client.Config{ProjectID:"__ProjectID__"})
if err != nil {
    // handle the error
    log.Println("failed to initialize: " + err.Error())
}

import com.descope.client.Config;
import com.descope.client.DescopeClient;

var descopeClient = new DescopeClient(Config.builder().projectId("__ProjectID__").build());

User Sign-Up

For registering a new user, your application client should accept user information, including an email or phone number used for verification. The application client should then send this information to your application server. Signing up via password returns the user's JWT.

NodeJSPythonGoJava

// Args:
//    loginId (str): The login ID of the user being signed up
const loginId = "email@company.com"
//    password (str): The new user's password
const password = "xxxxxx"
//    user (dict) optional: Preserve additional user metadata in the form of
const user = { "name": "Joe Person", "phone": "+15555555555", "email": "email@company.com"}

const resp = await descopeClient.password.signUp(loginId, password, user);
if (!resp.ok) {
  console.log("Failed to sign up via password")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully signed up via password")
  console.log(resp);
}

# Args:
#    login_id (str): The login ID of the user being signed up
login_id = "email@company.com"
#    password (str): The new user's password
password = "xxxxxx"
#    user (dict) optional: Preserve additional user metadata in the form of
user = { "name": "Joe Person", "phone": "+15555555555", "email": "email@company.com"}

try:
  resp = descope_client.password.sign_up(login_id=login_id, password=password, user=user)
  print ("Successfully signed up via password")
  print (resp)
except AuthException as error:
  print ("Failed to sign up via password")
  print ("Status Code: " + str(error.status_code))
  print ("Error: " + str(error.error_message))

// Args:
//    ctx: context.Context - Application context for the transmission of context capabilities like
//        cancellation signals during the function call. In cases where context is absent, the context.Background()
//        function serves as a viable alternative.
//        Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
ctx := context.Background()
//    loginID (str): The login ID of the user being signed up
loginID := "email@company.com"
//    user (descope.User): Optional user object to populate new user information.
user := &descope.User{
  Name: "Joe Person",
  Phone: "+15555555555",
  Email: loginID,
}
//    password (str): The new user's password
password := "xxxxxx"
//   w: ResponseWriter to update with correct session details. You can return this to your client for setting the cookies which are used for session validation. This code should go into your application server route handling the verification of code.

resp, err := descopeClient.Auth.Password().SignUp(ctx, loginID, user, password, w)
if (err != nil){
  fmt.Println("Failed to sign up via password: ", err)
} else {
  fmt.Println("Successfully signed up via password", resp)
}

// Every user must have a loginID. All other user information is optional
String loginId = "email@company.com";
User user = User.builder()
    .name("Joe Person")
    .phone("+15555555555")
    .email(loginId)
    .build();
String password = "qYlvi65KaX";

PasswordService ps = descopeClient.getAuthenticationServices().getPasswordService();

try {
  AuthenticationInfo info = ps.signUp(loginId, user, password);
} catch (DescopeException de) {
  // Handle the error
}

User Sign-In

For authenticating a user, your application client should accept the user's identity (typically an email address or phone number) and password. The application client should send this information to your application server. Signing in via password returns the user's JWT.

NodeJSPythonGoJava

// Args:
//    loginId (str): The login ID of the user being signed in
const loginId = "email@company.com"
//    password (str): The user's password
const password = "xxxxxx"

const resp = await descopeClient.password.signIn(loginId, password);
if (!resp.ok) {
  console.log("Failed to sign in via password")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully signed in via password")
  console.log(resp);
}

# Args:
#    login_id (str): The login ID of the user being signed in
login_id = "email@company.com"
#    password (str): The user's password
password = "xxxxxx"

try:
  resp = descope_client.password.sign_in(login_id=login_id, password=password)
  print ("Successfully signed in via password")
  print (resp)
except AuthException as error:
  print ("Failed to sign in via password")
  print ("Status Code: " + str(error.status_code))
  print ("Error: " + str(error.error_message))

// Args:
//    ctx: context.Context - Application context for the transmission of context capabilities like
//        cancellation signals during the function call. In cases where context is absent, the context.Background()
//        function serves as a viable alternative.
//        Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
ctx := context.Background()
//    loginID: The login ID of the user being signed in
loginID := "email@company.com"
//    password (str): The user's password
password := "xxxxxx"
//   w: ResponseWriter to update with correct session details. You can return this to your client for setting the cookies which are used for session validation. This code should go into your application server route handling the verification of code.

resp, err := descopeClient.Auth.Password().SignIn(ctx, loginID, password, w)
if (err != nil){
  fmt.Println("Failed to sign in via password: ", err)
} else {
  fmt.Println("Successfully signed in via password", resp)
}

// Every user must have a loginID. All other user information is optional
String loginId = "email@company.com";
User user = User.builder()
    .name("Joe Person")
    .phone("+15555555555")
    .email(loginId)
    .build();
String password = "qYlvi65KaX";

PasswordService ps = descopeClient.getAuthenticationServices().getPasswordService();

try {
  AuthenticationInfo info = ps.signIn(loginId, password);
} catch (DescopeException de) {
  // Handle the error
}

Update Password

Update a password for an existing logged in user using their refresh token.

NodeJSPythonGoJava

// Args:
//    loginId (str): The login ID of the user who's information is being updated
const loginId = "email@company.com"
//    newPassword (str): The new password to use
const newPassword = "xxxxxx"
//    token (str): The session's refresh token (used for verification)
const token = "xxxxxx"

const resp = await descopeClient.password.update(loginId, newPassword, token);
if (!resp.ok) {
  console.log("Failed to update password")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully updated password")
}

# Args:
#    login_id (str): The login ID of the user who's information is being updated
login_id = "email@company.com"
#    new_password (str): The new password to use
new_password = "xxxxxx"
#    refresh_token (str): The session's refresh token (used for verification)
refresh_token = "xxxxxx"

try:
  descope_client.password.update(login_id=login_id, new_password=new_password, refresh_token=refresh_token)
  print ("Successfully updated password")
except AuthException as error:
  print ("Failed to update password")
  print ("Status Code: " + str(error.status_code))
  print ("Error: " + str(error.error_message))

// Args:
//    ctx: context.Context - Application context for the transmission of context capabilities like
//        cancellation signals during the function call. In cases where context is absent, the context.Background()
//        function serves as a viable alternative.
//        Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
ctx := context.Background()
//    loginID: The login ID of the user who's information is being updated
loginID := "email@company.com"
//    newPassword (str): The new password to use
newPassword := "xxxxxx"
//    r: HttpRequest for the update call. This request should contain refresh token for the authenticated user.

err := descopeClient.Auth.Password().UpdateUserPassword(ctx, loginID, newPassword, r)
if (err != nil){
  fmt.Println("Failed to update password: ", err)
} else {
  fmt.Println("Successfully updated password")
}

// Every user must have a loginID. All other user information is optional
String loginId = "email@company.com";
String refreshToken = "xxxxx";
String newPassword = "qYlvi65KaXwegsd";

PasswordService ps = descopeClient.getAuthenticationServices().getPasswordService();

try {
  AuthenticationInfo info = ps.updateUserPassword(loginId, newPassword, r);
} catch (DescopeException de) {
  // Handle the error
}

Replace Password

Replace a password with a new one. The old password is used to authenticate the user before replacing the password. If the user cannot be authenticated, this operation will fail.

NodeJSPythonGoJava

// Args:
//    loginId (str): The login ID of the user who's information is being replaced
const loginId = "email@company.com"
//    oldPassword (str): The user's current active password
const oldPassword = "xxxxxx"
//    newPassword (str): The new password to use
const newPassword = "xxxxxx"

const resp = await descopeClient.password.replace(loginId, oldPassword, newPassword);
if (!resp.ok) {
  console.log("Failed to replace password")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully replaced password")
}

# Args:
#    login_id (str): The login ID of the user who's information is being replaced
login_id = "email@company.com"
#    old_password (str): The user's current active password
old_password = "xxxxxx"
#    new_password (str): The new password to use
new_password = "xxxxxx"

try:
  resp = descope_client.password.replace(login_id=login_id, old_password=old_password, new_password=new_password)
  print ("Successfully replaced password")
except AuthException as error:
  print ("Failed to replace password")
  print ("Status Code: " + str(error.status_code))
  print ("Error: " + str(error.error_message))

// Args:
//    ctx: context.Context - Application context for the transmission of context capabilities like
//        cancellation signals during the function call. In cases where context is absent, the context.Background()
//        function serves as a viable alternative.
//        Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
ctx := context.Background()
//    loginID: The login ID of the user who's information is being replaced
loginID := "email@company.com"
//    oldPassword (str): The user's current active password
oldPassword := "xxxxxx"
//    newPassword (str): The new password to use
newPassword := "xxxxxx"

err := descopeClient.Auth.Password().ReplaceUserPassword(ctx, loginID, oldPassword, newPassword)
if (err != nil){
  fmt.Println("Failed to replace password: ", err)
} else {
  fmt.Println("Successfully replaced password")
}

// Every user must have a loginID. All other user information is optional
String loginId = "email@company.com";
String password = "qYlvi65KaX";
String newPassword = "sdgoh90"
PasswordService ps = descopeClient.getAuthenticationServices().getPasswordService();

try {
  AuthenticationInfo info = ps.replaceUserPassword(loginId, password, newPassword);
} catch (DescopeException de) {
  // Handle the error
}

Reset Password

Sends a password reset prompt to the user with the given login id according to the password settings defined in the Descope console. NOTE: The user's email must be verified in order for the password reset method to complete.

NodeJSPythonGoJava

// Args:
//    loginId (str): The login ID of the user who's password is being reset
const loginId = "email@company.com"
//    redirectURL (str): Optional parameter that is used by Magic Link.
const redirectURL = "http://auth.company.com/api/verify_magiclink"
//    templateOptions (TemplateOptions): Password reset email template options
const templateOptions = {"option": "Value1"}

const resp = await descopeClient.password.sendReset(loginId, redirectURL, templateOptions);
if (!resp.ok) {
  console.log("Failed to send password reset")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully sent password reset")
}

# Args:
#     login_id (str): The login ID of the user who's password is being reset
login_id = "email@company.com"
#     redirect_url (str): Optional parameter that is used by Magic Link.
redirect_url = "http://auth.company.com/api/verify_magiclink"
#   template_options (dict): email template options
template_options = {"option": "Value1"}

try:
  resp = descope_client.password.send_reset(login_id=login_id, redirect_url=redirect_url, template_options=template_options)
  print ("Successfully sent password reset")
  print (resp)
except AuthException as error:
  print ("Failed to send password reset")
  print ("Status Code: " + str(error.status_code))
  print ("Error: " + str(error.error_message))

// Args:
//    ctx: context.Context - Application context for the transmission of context capabilities like
//        cancellation signals during the function call. In cases where context is absent, the context.Background()
//        function serves as a viable alternative.
//        Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
ctx := context.Background()
//    loginID: The login ID of the user who's password is being reset
loginID := "email@company.com"
//    redirectURL (str): Optional parameter that is used by Magic Link.
redirectURL := "http://auth.company.com/api/verify_magiclink"
//    templateOptions (TemplateOptions): Password reset email template options
templateOptions := map[string]any{"option": "Value1"}

err := descopeClient.Auth.Password().SendPasswordReset(ctx, loginID, redirectURL)
if (err != nil){
  fmt.Println("Failed to send password reset: ", err)
} else {
  fmt.Println("Successfully sent password reset")
}

// Every user must have a loginID. All other user information is optional
String loginId = "email@company.com";
String redirectUrl = "<redirect_url>";
PasswordService ps = descopeClient.getAuthenticationServices().getPasswordService();

try {
  AuthenticationInfo info = ps.sendPasswordReset(loginId, redirectUrl);
} catch (DescopeException de) {
  // Handle the error
}

Get Password Policy

Get the configured password policy for the project.

NodeJSPythonGoJava

// Args:
//     None

const resp = await descopeClient.password.policy();
if (!resp.ok) {
  console.log("Successfully returned password policy")
  console.log("Status Code: " + resp.code)
  console.log("Error Code: " + resp.error.errorCode)
  console.log("Error Description: " + resp.error.errorDescription)
  console.log("Error Message: " + resp.error.errorMessage)
}
else {
  console.log("Successfully sent password reset")
  console.log(resp)
}

# Args:
#     None

try:
  resp = descope_client.password.get_policy()
  print ("Successfully returned password policy")
  print (resp)
except AuthException as error:
  print ("Failed to return password policy")
  print ("Status Code: " + str(error.status_code))
  print ("Error: " + str(error.error_message))

// Args:
//    ctx: context.Context - Application context for the transmission of context capabilities like
//        cancellation signals during the function call. In cases where context is absent, the context.Background()
//        function serves as a viable alternative.
//        Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
ctx := context.Background()

resp, err := descopeClient.Auth.Password().GetPasswordPolicy(ctx)
if (err != nil){
  fmt.Println("Failed to return password policy: ", err)
} else {
  fmt.Println("Successfully returned password policy", resp)
}

PasswordService ps = descopeClient.getAuthenticationServices().getPasswordService();

try {
  AuthenticationInfo info = ps.getPasswordPolicy();
} catch (DescopeException de) {
  // Handle the error
}

Session Validation

The final step of completing the authentication with Descope is to validate the user session. Descope provides rich session management capabilities, including configurable session timeouts and logout functions. You can find the details and sample code for backend session validation here.

Checkpoint: Your application is now integrated with Descope. Please test with sign-up or sign-in use case.

Application is working Need Help?

Was this article helpful?Yes No