🔐 Okta Password Reset Configuration
From Custom Templates to Multi‑Site Reuse

1. Introduction: Why a Custom Okta Password Reset Flow Matters

Modern identity architectures rarely operate in isolation. When an enterprise manages customer identities through Okta while running a digital experience on Salesforce Experience Cloud, the password reset journey becomes a cross‑system orchestration. The Digital Trade Platform (DTP) requirements explicitly ask Okta to send a branded password reset email that directs users to a Salesforce‑hosted reset page, supports multiple sites (e.g., distributors, growers, resellers), and adheres to strict security, localization, and accessibility standards. In this guide we unpack every technical decision, configuration step, API endpoint, and design pattern required to implement what the client calls “Option A.”

Whether you are the Okta administrator, a Salesforce architect, or an APIGEE integration engineer, understanding the interplay between custom email templates, the Authn API, relayState, and Okta password policies is essential. We also cover how to make the reset flow WCAG 2.2 AA compliant, how to add languages beyond the built‑in 27, and how to lock down the redirect to prevent open‑redirect abuse. For foundational knowledge, you can explore our article on Authentication Policies in Okta, which sets the stage for password security and policy design.

2. Understanding the Two Options (A vs B)

The client’s requirements document leaves a decision open: should Okta send the password reset email (Option A) or should Salesforce trigger it (Option B)? Option A mandates that Okta sends the reset‑related email with a customized template and also sends a post‑reset success notification. This aligns with the requirement that the user receives an email directly from Okta, containing a link that lands on a Salesforce page. Option B would shift responsibility to Salesforce, which would then need to integrate with Okta’s API to create the recovery token — adding complexity and contradicting the stated “OKTA must send” requirements.

We strongly recommend Option A. It is a supported Okta pattern (custom password recovery) and elegantly solves multi‑site reuse through the relayState parameter. Throughout the guide we assume Option A. If the client still wishes to explore Option B, they must rewrite the requirement statements; otherwise, the Okta team should proceed with Option A.

3. Architectural Overview of Option A

The flow involves four actors:

• End User: Forgets password, requests reset from Salesforce login page or directly.
• APIGEE (API Gateway): Acts as the secure middleware that calls Okta’s recovery endpoint on behalf of the Salesforce front end.
• Okta: Receives the API call, generates a one‑time password (OTP) and recovery token, embeds them in a customized email, and sends it to the user.
• Salesforce Experience Cloud: Hosts the custom reset page that receives the OTP and relayState, verifies them, and completes the password change via Okta API.

APIGEE calls POST /api/v1/authn/recovery/password with the user’s email, factorType=EMAIL, and a relayState that identifies which Salesforce site should handle the reset. Okta’s email template has been modified so that the “Reset Password” link points to a generic endpoint that forwards to the correct Salesforce domain using the relayState value. This is far more maintainable than hard‑coding multiple templates. For APIGEE integration patterns, our Okta SSO Setup with Salesforce guide provides a complete SAML‑based parallel.

4. Step‑by‑Step Configuration in Okta

4.1 Email Template Customization (Forgot Password)

Navigate to Customizations > Emails (or Customizations > Brands > [your brand] > Emails in multi‑brand setups). Under the Password category, select Forgot Password. You must edit the default‑language version before translations become available.

Locate the anchor tag that contains id="reset-password-link" href="${resetPasswordLink}". Replace the href with your own endpoint, for example:

href="https://api.yoursite.com/reset/callback?otp=${oneTimePassword}&state=${request.relayState}"

Critical constraint: Okta’s template validator requires the literal ${resetPasswordLink} to appear somewhere in the HTML. Many teams keep it as a hidden attribute (e.g., data-legacy="${resetPasswordLink}") to satisfy validation while the real link uses the custom URL. This is a well‑known workaround in the Okta SSO community.

After saving, the template is live. Test immediately by triggering a reset via API to confirm the link points to your redirect endpoint and carries the correct relayState.

4.2 Setting Up APIGEE’s Service App and Trusted Origin

In Applications > Applications, create an app of type API Services. This Service App will use OAuth 2.0 client credentials to authenticate against Okta. Grant it the necessary scopes (the /authn/recovery/password endpoint is unauthenticated, but your app may need a token for other calls). Under Security > API > Trusted Origins, add APIGEE’s domain/origin to allow CORS and redirect callbacks. Without this, the API gateway’s requests will be blocked.

4.3 Triggering the Reset Email via API

APIGEE will call:

POST https://{yourOktaDomain}/api/v1/authn/recovery/password
Content-Type: application/json

{
    "username": "user@example.com",
    "factorType": "EMAIL",
    "relayState": "agroenlace"
}

The relayState should be a site identifier (e.g., “agroenlace”, “distributor‑us”) rather than a raw URL. Your callback endpoint then does a secure lookup to map the identifier to the actual Salesforce reset page URL. This prevents open redirects. For deeper API tracing, our SAML Tracer Deep Dive explains how to capture and decode the tokens involved.

4.4 Enabling Post‑Reset Success Notification

Go to Security > General > Security Notification Emails (brand‑scoped if multi‑brand) and turn on the “Report a password change” toggle. This built‑in notification fires after any password reset and can be customized just like the Forgot Password template. If branding consistency is needed, edit that template as well.

4.5 Localization: Beyond the 27 Default Languages

Okta ships with 27 system languages. To add a translation for a supported language, use Add Translation in the email editor. For languages outside the default list (e.g., Catalan, Thai), you must use the Brands API: POST /api/v1/brands/{brandId}/templates/email/{templateName}/customizations with a BCP 47 locale code. Once created, the new language appears in the Admin Console alongside the built‑in ones. This is essential because the DTP may require regional dialects that Okta doesn’t offer by default.

4.6 Accessibility: WCAG 2.2 AA Compliance

Okta’s third‑generation Sign‑In Widget already adheres to WCAG 2.2 AA, and the password reset flow is included. Check your widget version under Customizations > Sign‑in > Sign‑in widget version. If you’re on the Classic Engine, consider upgrading. For Universal Login, an Early Access toggle enables the WCAG 2.2 AA‑compliant mode. This ensures that screen‑readers, keyboard navigation, and focus indicators work correctly during the reset process.

5. Deep Dive: The Authn API vs IDX API Decision

The DTP requirements include an open decision on which Okta API APIGEE should use. Okta offers two families:

• Authn API (/api/v1/authn): Simple, redirect‑heavy, ideal for linear flows without MFA branching.
• IDX API: Modern, supports passwordless, biometrics, and adaptive MFA via a single pipeline. Okta recommends it for new applications.

Given that the current reset flow does not involve MFA and uses a straightforward email‑OTP mechanism, the Authn API is sufficient and easier to implement. However, if the client plans to introduce multi‑factor authentication later, switching to IDX now would avoid a costly migration. Our suggestion: implement with Authn API for immediate delivery, but design the integration layer in APIGEE with an abstraction that allows swapping to IDX later without disrupting the Salesforce UI. This echoes the advice in our Okta Workflows and Automations article, where we discuss maintaining future‑proof integration layers.

6. Password Policy and Security Considerations

The client’s requirements document contains placeholders for token expiry, password policy, and lockout thresholds. The Okta team must fill these before finalizing the design:

• Token expiry (reset link lifespan): Default is 1 hour. This is configurable per password policy using tokenLifetimeMinutes. For external users (distributors/growers), 1 hour is usually acceptable, but if they face delays, it can be extended up to 24 hours in hour increments.
• Password policy for external users: Propose a group‑scoped policy with: minimum 12 characters, at least one uppercase, one lowercase, one digit, and one special character. Enforce password history of 4, and lockout after 5 consecutive failed attempts. This protects against brute‑force while remaining user‑friendly.
• Abuse protection: Enable CAPTCHA on password reset to block automated attacks. Also turn on user enumeration prevention (Security > General) so the system never reveals whether an account exists.
• relayState security: Never pass raw Salesforce URLs in the relayState. Instead, pass a short site identifier and map it server‑side to a whitelisted URL. This eliminates open‑redirect vulnerabilities.

7. Multi‑Site Reuse: One Template, Many Destinations

The DTP will serve multiple digital trade sites (e.g., agroenlace.com, regional portals). Hard‑coding a Salesforce URL in the email template would require duplicating the template per site, multiplying translation effort. The solution is a single generic redirect endpoint that reads the relayState parameter. For example, APIGEE passes "relayState": "site=agroenlace". The callback URL is https://api.yoursite.com/reset/forward. The server decodes the site identifier and issues a 302 redirect to the appropriate Salesforce page. Okta’s template only contains:

href="https://api.yoursite.com/reset/forward?otp=${oneTimePassword}&state=${request.relayState}"

This approach also simplifies maintenance: adding a new site is just a mapping entry, not a template change. For PowerShell automation examples related to such forwarding logic, see our PowerShell Network Troubleshooting guide, which includes HTTP redirect testing scripts.

8. End‑to‑End Testing Strategy

Before handing off to the Salesforce/APIGEE team, run through these tests:

1. API smoke test: Use Postman or cURL to call the recovery endpoint and verify a 200 OK response and email delivery.
2. Link analysis: Inspect the received email; the reset link must contain the OTP and relayState in the query string, and clicking it must land on the correct Salesforce page.
3. Password change: Complete the reset on Salesforce and confirm the success notification email is received.
4. Localization: Switch user locale in Okta (profile) or use a test user with a different language to verify the email template renders in the correct language.
5. Accessibility audit: Use Lighthouse or aXe to check the Salesforce reset page and the Okta email for WCAG 2.2 AA compliance.
6. Security check: Attempt to manipulate relayState to redirect to an external domain; the callback must reject non‑whitelisted identifiers.

Our SAML Tracer blog post explains how to capture the SAML assertion if you later extend the flow to include SAML‑based authentication.

9. Localization Details & BCP 47 Codes

The Brands API expects locale codes following BCP 47, e.g., en‑US, es‑MX, pt‑BR. When you create a custom locale via API, the email template content must be provided as a JSON payload with the full HTML. This is also the method to update translations programmatically in a CI/CD pipeline. Remember that once a template is customized, Okta stops sending the default version for that locale; you become fully responsible for translations. Plan for a translation management process, possibly using a term‑base shared with the Salesforce UI translations.

10. Documentation and Handoff to Client

Along with the configured Okta tenant, the Okta team should provide the client with:

• A configuration summary detailing the email template changes, relayState mapping table, trusted origins, and service app credentials.
• API documentation showing the exact endpoints APIGEE must call, with sample request/response pairs (including error codes).
• Localization matrix listing supported languages and which ones have been translated.
• Security whitepaper outlining how relayState whitelisting, CAPTCHA, and enumeration prevention satisfy the abuse‑protection requirement.

For a broader perspective on identity provisioning and security, the Entra ID Provisioning article and Device Management in Entra ID offer relevant comparisons.