Skip to content

Fix: Resolve contradictory Gmail configs and add missing SMTP link #3170 #6027

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
SaviruDesilva wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Fix: Resolve contradictory Gmail configs and add missing SMTP link #3170 #6027

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 19 additions & 17 deletions en/identity-server/5.10.0/docs/learn/configuring-email-otp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,8 @@ You can use WSO2 Identity Server as the email OTP provider or you can
configure Gmail or SendGrid as the email OTP provider using Gmail or
SendGrid APIs. Follow the instructions in **one** of **Option1** or
**Option2** to set up the email OTP provider.

!!! note
Before you begin, ensure that you have configured the email server. For instructions on how to do this using SMTP, see [Configuring the Email Sending Module](../../setup/configuring-email-sending/).
#### Option1: Configure WSO2 IS as the email OTP provider

??? abstract "Expand this section to follow the steps to configure WSO2 IS to send emails once the Email OTP is enabled."
Expand Down Expand Up @@ -401,22 +402,23 @@ SendGrid APIs. Follow the instructions in **one** of **Option1** or
!!! Note "Sample configuration when using Identity Server as Email OTP Provider"
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Mar 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Critical: Contradictory note placement.

The note states "Sample configuration when using Identity Server as Email OTP Provider", but this configuration snippet is located inside Option2: Configure Gmail as the email OTP provider (line 267). Option1 is for using Identity Server as the provider. This contradiction will confuse users about which configuration to use.

📝 Proposed fix

Either:

  1. Move this configuration to Option1 if it's meant for Identity Server as the OTP provider, or
  2. Update the note to reflect Gmail configuration:
-!!! Note "Sample configuration when using Identity Server as Email OTP Provider"
+!!! Note "Sample configuration when using Gmail as Email OTP Provider"

However, note that the configuration is also missing required Gmail-specific parameters (see separate comment).

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
!!! Note "Sample configuration when using Identity Server as Email OTP Provider"
!!! Note "Sample configuration when using Gmail as Email OTP Provider"
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@en/identity-server/5.10.0/docs/learn/configuring-email-otp.md` at line 402,
The note "Sample configuration when using Identity Server as Email OTP Provider"
is misplaced under the "Option2: Configure Gmail as the email OTP provider"
section; either move that configuration snippet into the "Option1: Configure
Identity Server as the email OTP provider" section (so the snippet matches the
note), or change the note text to reflect Gmail (e.g., "Sample configuration
when using Gmail as the Email OTP Provider") and update the snippet to include
Gmail-specific parameters; locate the note by the exact string "Sample
configuration when using Identity Server as Email OTP Provider" and the two
headings "Option1: Configure Identity Server as the email OTP provider" and
"Option2: Configure Gmail as the email OTP provider" when making the change.

``` toml
[authentication.authenticator.email_otp]
name = "EmailOTP"
enable= true
[authentication.authenticator.email_otp.parameters]
EMAILOTPAuthenticationEndpointURL = "https://localhost:9443/emailotpauthenticationendpoint/emailotp.jsp"
EmailOTPAuthenticationEndpointErrorPage = "https://localhost:9443/emailotpauthenticationendpoint/emailotpError.jsp"
EmailAddressRequestPage = "https://localhost:9443/emailotpauthenticationendpoint/emailAddress.jsp"
usecase = "association"
secondaryUserstore = "primary"
EMAILOTPMandatory = false
sendOTPToFederatedEmailAttribute = false
federatedEmailAttributeKey = "email"
EmailOTPEnableByUserClaim = true
CaptureAndUpdateEmailAddress = true
showEmailAddressInUI = true
useEventHandlerBasedEmailSender = true
emailAddressRegex = '(?<=.{1}).(?=.*@)'
name = "EmailOTP"
enable = true

[[authentication.authenticator.email_otp.parameters]]
name = "EmailOTPAuthenticationEndpointURL"
value = "https://localhost:9443/emailotpauthenticationendpoint/emailotp.jsp"

[[authentication.authenticator.email_otp.parameters]]
name = "EmailOTPAuthenticationEndpointErrorPage"
value = "https://localhost:9443/emailotpauthenticationendpoint/emailotpError.jsp"

[[authentication.authenticator.email_otp.parameters]]
name = "EmailAddressRequestPage"
value = "https://localhost:9443/emailotpauthenticationendpoint/emailAddress.jsp"
Comment on lines 404 to +418
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Mar 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion | 🟠 Major

Major: Inconsistent configuration format between Option1 and Option2.

Option1 (lines 51-70) uses the flat-style format with [authentication.authenticator.email_otp.parameters] and direct key-value pairs, while Option2 now uses the array-style format with [[authentication.authenticator.email_otp.parameters]] and name/value pairs.

This inconsistency creates confusion about which format to use and may suggest different configuration requirements when there shouldn't be any. Both options should use the same configuration format for consistency unless there's a technical reason for the difference.

Consider standardizing on the flat-style format used in Option1, as shown in the previous comment's recommended fix. This matches the format used elsewhere in the WSO2 Identity Server 5.10.0 documentation (see context snippet from passwordless-authentication-using-emailotp.md).

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@en/identity-server/5.10.0/docs/learn/configuring-email-otp.md` around lines
404 - 418, The configuration uses inconsistent parameter formats: replace the
array-style parameter blocks
([[authentication.authenticator.email_otp.parameters]]) with the flat-style
single blocks ([authentication.authenticator.email_otp.parameters]) and convert
each name/value pair into direct key-value entries (e.g.,
EmailOTPAuthenticationEndpointURL, EmailOTPAuthenticationEndpointErrorPage,
EmailAddressRequestPage) under the
[authentication.authenticator.email_otp.parameters] section so the EmailOTP
authenticator configuration matches the flat-style used elsewhere (as in Option1
and passwordless-authentication-using-emailotp.md).


[output_event_adapter.email]
default_from_address = "your_email@gmail.com"
```
Comment on lines 404 to 422
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Mar 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Search for output adapter email configuration patterns in documentation and config files

echo "=== Searching for output adapter email config patterns ==="
rg -n "output.*adapter.*email" --type toml --type md -C2

echo ""
echo "=== Searching for specific section names ==="
rg -n "\[output_event_adapter\.email\]|\[output_adapter\.email\]" --type toml --type md -C2

Repository: wso2/docs-is

Length of output: 50370

🏁 Script executed:

cat -n en/identity-server/5.10.0/docs/learn/configuring-email-otp.md | sed -n '374-475p'

Repository: wso2/docs-is

Length of output: 107

🏁 Script executed:

cat -n en/identity-server/5.10.0/docs/learn/configuring-email-otp.md | sed -n '374,475p'

Repository: wso2/docs-is

Length of output: 6080

🏁 Script executed:

cat -n en/identity-server/5.10.0/docs/learn/configuring-email-otp.md | sed -n '1,403p' | tail -50

Repository: wso2/docs-is

Length of output: 2858

🏁 Script executed:

cat -n en/identity-server/5.10.0/docs/learn/configuring-email-otp.md | sed -n '270,330p'

Repository: wso2/docs-is

Length of output: 3426

🏁 Script executed:

cat -n en/identity-server/5.10.0/docs/learn/configuring-email-otp.md | sed -n '475,530p'

Repository: wso2/docs-is

Length of output: 2922

🏁 Script executed:

# Check the format used for email_otp.parameters in the file
cat -n en/identity-server/5.10.0/docs/learn/configuring-email-otp.md | sed -n '404,425p'

Repository: wso2/docs-is

Length of output: 1008

🏁 Script executed:

# Search for any other configuration examples in the file that include Gmail parameters
rg -n "GmailClientId|GmailClientSecret|GmailRefreshToken|GmailEmailEndpoint" en/identity-server/5.10.0/docs/learn/configuring-email-otp.md -A 2 -B 2

Repository: wso2/docs-is

Length of output: 1633

🏁 Script executed:

# Check what comes before line 402 to understand which Option this is for
cat -n en/identity-server/5.10.0/docs/learn/configuring-email-otp.md | sed -n '250,275p'

Repository: wso2/docs-is

Length of output: 1259

Fix incorrect section name and add missing Gmail authentication parameters to the configuration example.

The configuration at lines 404-422 has two critical issues:

  1. Incorrect section name at line 420: The section is named [output_event_adapter.email], but the correct name across the entire codebase is [output_adapter.email].

  2. Missing Gmail authentication parameters: The configuration snippet only shows endpoint parameters but omits the Gmail-specific credentials documented in the parameter table below (lines 448-495). When using Gmail as the OTP provider, the configuration must include:

    • GmailClientId
    • GmailClientSecret
    • GmailRefreshToken
    • GmailEmailEndpoint
    • accessTokenRequiredAPIs

Without these parameters, the Gmail integration will fail. The configuration example should be corrected to include all required Gmail authentication details.

Configuration format 
[authentication.authenticator.email_otp]
name = "EmailOTP"
enable = true

[[authentication.authenticator.email_otp.parameters]]
name = "EmailOTPAuthenticationEndpointURL"
value = "https://localhost:9443/emailotpauthenticationendpoint/emailotp.jsp"

[[authentication.authenticator.email_otp.parameters]]
name = "EmailOTPAuthenticationEndpointErrorPage"
value = "https://localhost:9443/emailotpauthenticationendpoint/emailotpError.jsp"

[[authentication.authenticator.email_otp.parameters]]
name = "EmailAddressRequestPage"
value = "https://localhost:9443/emailotpauthenticationendpoint/emailAddress.jsp"

[[authentication.authenticator.email_otp.parameters]]
name = "GmailClientId"
value = "<your_client_id>"

[[authentication.authenticator.email_otp.parameters]]
name = "GmailClientSecret"
value = "<your_client_secret>"

[[authentication.authenticator.email_otp.parameters]]
name = "GmailRefreshToken"
value = "<your_refresh_token>"

[[authentication.authenticator.email_otp.parameters]]
name = "GmailEmailEndpoint"
value = "https://www.googleapis.com/gmail/v1/users/<your_email@gmail.com>/messages/send"

[[authentication.authenticator.email_otp.parameters]]
name = "accessTokenRequiredAPIs"
value = "Gmail"

[output_adapter.email]
default_from_address = "your_email@gmail.com"
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@en/identity-server/5.10.0/docs/learn/configuring-email-otp.md` around lines
404 - 422, The TOML example under authentication.authenticator.email_otp has two
problems: replace the incorrect section name "[output_event_adapter.email]" with
"[output_adapter.email]" and add the missing Gmail authentication parameter
entries under [[authentication.authenticator.email_otp.parameters]] —
specifically add parameters named "GmailClientId", "GmailClientSecret",
"GmailRefreshToken", "GmailEmailEndpoint" (with the Gmail send URL) and
"accessTokenRequiredAPIs" (value "Gmail") so the Gmail OTP integration has
credentials and endpoint; keep the existing EmailOTPAuthenticationEndpointURL,
EmailOTPAuthenticationEndpointErrorPage, and EmailAddressRequestPage entries
intact.


??? Tip
Expand Down