Getting and Updating Breached Password Detection Settings

Learn how to retrieve and update breached password detection settings using Auth0 API.

We'll cover the following

In this lesson, we'll see how we can get breached password detection settings and update breached password detection settings using an API call. We'll use the https://{{DOMAIN}}/api/v2/attack-protection/breached-password-detection endpoint to achieve these tasks. Getting breached password detection settings is a GET request, while updating the breach password detection settings is a PATCH request.

Press + to interact
Updating and getting breached password detection settings
Updating and getting breached password detection settings

Getting breached password detection settings

The Auth0 /breached-password-detection endpoint allows us to retrieve the breach detection settings, including the method for checking breached passwords, the action to take if a breach is found, and the frequency of checks. This helps maintain the security of users' passwords and prevent unauthorized access to the application.

Request parameters

There are no request parameters required for this particular endpoint.

Click the “Run” button to retrieve the breached password detection settings.

Press + to interact
// Importing libraries here
const fetch = require('node-fetch');
const endpointUrl = new URL('https://{{DOMAIN}}/api/v2/attack-protection/breached-password-detection');
const headerParameters = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{ACCESS_TOKEN}}',
}
const options = {
  method: 'GET',
  headers: headerParameters,
};
async function getBreachPasswordDetection() {
  try {
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
getBreachPasswordDetection();

Let's look at the highlighted lines from the code shown above:

  • Line 4: We define the endpoint URL to retrieve the breach password detection settings.

  • Line 18: We make a GET request using the fetch function.

  • Line 25: We invoke the getBreachPasswordDetection function.

Response fields

The successful execution of the above code will retrieve the breach password detection settings and return details.

Name

Description

enabled

Defines whether the breached password detection settings should be enabled or not.

shields

Contains the details about which process will be used in case any password breach is detected. We can use the following values for the shields parameter: block, user_notification, and admin_notification.

admin_notification_frequency

Contains the details about the admin email notification frequency.

method

Defines the method that will be used to detect the password breach.

Updating breached password detection settings

After getting the current breached password detection settings, it’s time for us to update them. The Auth0 /breached-password-detection endpoint allows us to update breach detection settings. This allows us to proactively enhance the security of users’ passwords and fortify the application against potential unauthorized access.

Request parameters

To invoke this endpoint, we will use a PATCH request. We have a list of parameters that can be passed as body parameters. Let's have a look at some important ones in the table below:

Parameter Name

Type

Category

Description

enabled

Boolean

Optional

Defines whether the breached password detection settings should be enabled or not.

shields

Array

Optional

Defines the process that should be done in case any password breach is detected. The values that can be used are block, user_notification, and admin_notification.

admin_notification_frequency

Array

Optional

Defines the admin email notification frequency. The values that can be used for this parameter are immediately, daily, weekly, and monthly.

method

String

Optional

Defines the method used to detect the password breach. The values that can be used for this parameter are standard and enhanced.

Next, let's update the breached password detection settings. Click the “Run” button to update the settings.

Press + to interact
// Importing libraries here
const fetch = require('node-fetch');
const endpointUrl = new URL('https://{{DOMAIN}}/api/v2/attack-protection/breached-password-detection');
const headerParameters = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{ACCESS_TOKEN}}',
}
const bodyParameters = JSON.stringify({
  "enabled": true,
  "shields": [
    "admin_notification",
  ],
  "admin_notification_frequency": [
    "daily"
  ],
  });
const options = {
  method: 'PATCH',
  headers: headerParameters,
  body: bodyParameters,
};
async function updateBreachPasswordDetection() {
  try {
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
updateBreachPasswordDetection();

Let's look at the highlighted lines from the code shown above:

  • Line 4: We define the endpoint URL for the API call.

  • Lines 11–19: We define the bodyParameters object.

    • Line 12: We define the enabled parameter and set its value to true, which will enable the breached password detection settings.

    • Lines 13–15: We define the shields parameter, and we set its value to admin_notification.

    • Lines 16–18: We define the admin_notification_frequency parameter and set its value to daily.

  • Line 29: We make a PATCH request using the fetch function.

  • Line 36: We invoke the updateBreachPasswordDetection function.

Response fields

The successful execution of the above code enables the breached password detection settings and returns the same details as the “Getting the breached password detection settings” code widget.

Note: To verify the updated settings, please execute the “Getting the breached password detection settings” code widget.