Enable Your Own Forgotten Password Page

This topic is required to set up Identity Cloud Service to include the Digital Customer Service Reset Password page URL link when a user requests a password reset.

For this functionality to work Identity Cloud Service requires a REST request to be made to the IDCS /Settings API by a tenant administrator to set allowedNotificationRedirectUrls to include the Digital Customer Service Reset Password page URL. This setting defines the allowed notification redirect URLs which can be specified as the value of notificationRedirectUrl in the POST .../admin/v1/MePasswordResetRequestor request payload, which is then included in the reset password email notification sent to a user as part of the forgot password and password reset flow.

If you need to create the App in IDCS, refer to Create the Application Client.

Note: You must have Identity Administrator role and the Client ID and Client Secret must be for an IDCS application which has either the Identity Domain Administrator or Security Administrator application role granted. This is required to successfully call the /Settings REST API.

Use the following Powershell script. If you're using a Mac or Linux computer, you'll need to install Powershell first to run the script. See Microsoft's website for details. Powershell is installed by default on Windows.

Save the following script in a file called passwordreset.ps1 and modify the '...' values in the script as appropriate for your environment.

• To run the script from a Command Prompt on Windows enter: powershell -File passwordreset.ps1

• To run the script on Mac or Linux enter: pwsh passwordreset.ps1

### MODIFY THE FOLLOWING VARIABLES FOR YOUR IDCS/ODCS ENVIRONMENT ###
 
# Set IDCS variables (modify for your IDCS instance)
$IdcsUrl           = '...' # e.g. 'https://idcs-xxx.identity.yyy.idcs-example.com'
$ClientId          = '...' # Client ID for privileged app in IDCS
$ClientSecret      = '...' # Client Secret for privileged app in IDCS
 
# Either set the first 3 variables below for your ODCS app or explictly define $ForgotPasswordUrl
$OdcsHost          = '...' # e.g. 'my-odcs-example.com'
$OdcsAppName       = '...' # e.g. 'my_odcs_app'
$OdcsVersion       = '...' # e.g. '1.1'
$ForgotPasswordUrl = "https://${OdcsHost}/ic/builder/rt/${OdcsAppName}/${OdcsVersion}/webApps/dcs/?page=shell&shell=forgot-password"
 
### DO NOT MODIFY THIS SCRIPT BELOW THIS LINE ###
 
# Generate an access token
$Credentials = [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("${ClientId}:${ClientSecret}"))
$Uri = "$IdcsUrl/oauth2/v1/token"
$Headers = @{
  Authorization = "Basic $Credentials"
}
$Parameters = @{
  grant_type    = 'client_credentials'
  scope         = 'urn:opc:idm:__myscopes__'
}
try {
  $Response = Invoke-RestMethod -Uri $Uri -Method POST -Headers $Headers -Body $Parameters
} catch {
  Write-Host ("Access token request POST to {0} failed with an error: {2}`nForm parameters: {1}`nException: {3}"  -f $Uri, ($Parameters | Out-String), $_.ErrorDetails, $_.Exception) -fore red
  exit
}
$AccessToken = $Response.access_token
 
Write-Debug "Access Token = $AccessToken"
 
# Check the 'allowedNotificationRedirectUrls' IDCS Setting value
$Uri = "$IdcsUrl/admin/v1/Settings/Settings/?attributes=allowedNotificationRedirectUrls"
$Headers = @{
  Authorization   = "Bearer $AccessToken"
  'Content-Type'  = 'application/scim+json'
}
try {
  $Response = Invoke-RestMethod -Uri $Uri -Method GET -Headers $Headers
} catch {
  Write-Host ("Request to GET {0} failed with an error: {1}. `nException: {2}"  -f $Uri, $_.ErrorDetails, $_.Exception) -fore red
  exit
}
$AllowedUrls = $Response.allowedNotificationRedirectUrls
 
Write-Debug "Allowed URLs from GET /admin/v1/Settings/Settings = $AllowedUrls"
 
# Add the forgot password URL to the Settings, if required (i.e. not already in $AllowedUrls)
if ($null -ne $AllowedUrls -And $AllowedUrls.Contains($ForgotPasswordUrl)) {
  Write-Output "URL ($ForgotPasswordUrl) is already registered"
} else {
  # Remove query parameter from /Settings URL, headers remain as for previous request
  $Uri = "$IdcsUrl/admin/v1/Settings/Settings/"
 
  # Add new URL and format the list for inclusion in the JSON payload (without powershell encoding)
  $AllowedUrls += $ForgotPasswordUrl;
  $AllowedUrls = '"{0}"' -f ($AllowedUrls -join '","')
  $Body = '{
    "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
    "Operations": [
      {
        "op": "replace",
        "path": "allowedNotificationRedirectUrls",
        "value": [' + $AllowedUrls + ']
      }
    ]
  }'
 
  try {
    $Response = Invoke-RestMethod -Uri $Uri -Method PATCH -Headers $Headers -Body $Body
  } catch {
    Write-Host ("Request to PUT {0} to {1} failed with an error: {2}. `nException:{3}" -f $Body, $Uri, $_.ErrorDetails, $_.Exception) -fore red
    exit
  }
 
  $AllowedUrls = $Response.allowedNotificationRedirectUrls
  Write-Output "Added new URL: $ForgotPasswordUrl"
}
 
Write-Output "`nAllowed Notification Redirect URLs:"
Write-Output $AllowedUrls