Page Comparison

...

Shut down the server if it is running.

Open the <IS_HOME>/repository/conf/axis2/axis2.xml file, uncomment the transportSender name = "mailto" configurations, and update the following properties:

`mail.smtp.from`	Provide the email address of the SMTP account.
`mail.smtp.user`	Provide the username of the SMTP account.
`mail.smtp.password`	Provide the password of the SMTP account.

Code Block

<transportSender  name="mailto"
class="org.apache.axis2.transport.mail.MailTransportSender">
    <parameter  name="mail.smtp.from">{SENDER'S_EMAIL_ID}</parameter>
	<parameter  name="mail.smtp.user">{USERNAME}</parameter>
	<parameter  name="mail.smtp.password">{PASSWORD}</parameter>
	<parameter  name="mail.smtp.host">smtp.gmail.com</parameter>
    <parameter  name="mail.smtp.port">587</parameter>
    <parameter  name="mail.smtp.starttls.enable">true</parameter>
    <parameter  name="mail.smtp.auth">true</parameter>
</transportSender>

Comment out the <module ref="addressing"/> property to avoid syntax errors.
Code Block

Add the following email template to the <IS_HOME>/repository/conf/email/email-admin-config.xml.

Code Block

language	xml

<configuration type="EmailOTP" display="idleAccountReminder" locale="en_US" emailContentType="text/html">
   <targetEpr></targetEpr>
   <subject>WSO2 IS Email OTP</subject>
   <body>
      Hi,
      Please use this one time password {OTPCode} to sign in to your application.
   </body>
   <footer>
      Best Regards,
      WSO2 Identity Server Team
      http://www.wso2.com
   </footer>
   <redirectPath></redirectPath>
</configuration>

Configure the following properties in the <PRODUCT_HOME>/repository/conf/identity/identity-mgt.properties file to true.

Code Block

language	xml

Authentication.Policy.Enable=true
Authentication.Policy.Check.OneTime.Password=true

Add the following configuration to the application-authentication.xml file in the <IS_HOME>/repository/conf/identity directory.

Code Block

<AuthenticatorConfig name="EmailOTP" enabled="true"> 
	<Parameter name="EMAILOTPAuthenticationEndpointURL">https://localhost:9443/emailotpauthenticationendpoint/emailotp.jsp</Parameter>
	<Parameter name="EmailOTPAuthenticationEndpointErrorPage">https://localhost:9443/emailotpauthenticationendpoint/emailotpError.jsp</Parameter>
	<Parameter name="EmailAddressRequestPage">https://localhost:9443/emailotpauthenticationendpoint/emailAddress.jsp</Parameter>
	<Parameter name="usecase">association</Parameter> 
	<Parameter name="useEventHandlerBasedEmailSender">true</Parameter>
	<Parameter name="secondaryUserstore">primary</Parameter>
	<Parameter name="EMAILOTPMandatory">false</Parameter> 
	<Parameter name="sendOTPToFederatedEmailAttribute">false</Parameter> 
	<Parameter name="federatedEmailAttributeKey">email</Parameter> 
	<Parameter name="EmailOTPEnableByUserClaim">true</Parameter> 
	<Parameter name="useEventHandlerBasedEmailSender">true</Parameter>
	<Parameter name="CaptureAndUpdateEmailAddress">true</Parameter> 
	<Parameter name="showEmailAddressInUI">true</Parameter> 
</AuthenticatorConfig>

Expand

title	To view the parameter definitions, click here

ParameterDescriptionSample Valuesusecase

This parameter defines how the email ID will be retrieved. The default value is local.

Expand

title	Click here to view the value definitions

Value Definition

local This is the default value and is based on the federated username. You must set the federated username in the local userstore . The federated username must be the same as the local username.

association The federated username must be associated with the local account in advance in the end user dashboard. The local username is retrieved from the association. To associate the user, log into the end user dashboard and go to Associated Account by clicking View details .

subjectUri When configuring the federated authenticator, select the attribute in the subject identifier under the service provider section in UI, this is used as the username of the EmailOTP authenticator.

userAttribute

The name of the federatedauthenticator'suserattribute. That is the local username that is contained in a federated user's attribute. When using this, add the following parameter under the <AuthenticatorConfig name="EmailOTP" enabled="true"> section in the <IS_HOME>/repository/conf/identity/application-authentication.xml file and put the value, e.g., email and screen_name, id.

Code Block

language	xml

<Parameter name="userAttribute">email</Parameter>

If you use OpenID Connect supported authenticators such as LinkedIn and Foursquare or in the case of multiple social login options as the first step and EmailOTP assecondstep, you need to add similar configuration for the specific authenticator in the <IS_HOME>/repository/conf/identity/application-authentication.xml file under the <AuthenticatorConfigs> section.

Examples:

Fourquare

Code Block

language	xml

<AuthenticatorConfig name="Foursquare" enabled="true">
    <Parameter name="EmailOTP-userAttribute">http://wso2.org/foursquare/claims/email</Parameter>
    <Parameter name="federatedEmailAttributeKey">http://wso2.org/foursquare/claims/email</Parameter>
</AuthenticatorConfig>

Code Block

language	xml

<AuthenticatorConfig name="LinkedIn" enabled="true">
    <Parameter name="EmailOTP-userAttribute">http://wso2.org/linkedin/claims/emailAddress</Parameter>
    <Parameter name="federatedEmailAttributeKey">http://wso2.org/linkedin/claims/emailAddress</Parameter>
</AuthenticatorConfig>

Facebook

Code Block

language	xml

<AuthenticatorConfig name="FacebookAuthenticator" enabled="true">
	<Parameter name="EmailOTP-userAttribute">email</Parameter>
	<Parameter name="federatedEmailAttributeKey">email</Parameter>
</AuthenticatorConfig>

Likewise, you can add the Authenticator Config for Amazon, Google, Twitter, and Instagram with the relevant values.

local
association
userAttribute
subjectUri

secondaryUserstore

You can define multiple user stores per tenant as comma separated values.

Example:

Code Block
<Parameter name="secondaryUserstore">jdbc, abc, xyz</Parameter>

Info

The user store configurations are maintained per tenant:

If you use a super tenant, set all the parameter values into the <IS_HOME>/repository/conf/identity/application-authentication.xml file under the AuthenticatorConfigs section.

If you use a tenant,
- Upload the same XML file (application-authentication.xml) into a specific registry location (/_system/governance/EmailOTP).
- Create the collection named EmailOTP, add the resource and upload the application-authentication. xml file into the registry.
- While doing the authentication,thesysetmfirstcheckswhetherthereisanXML file uploaded to the registry. If that is so, it reads it from the registry but does not take the local file. If there is no file in the registry, then it only takes the property values from the local file.
- You can use the registry or local file to get the property values.

EMAILOTPMandatory

Thisparmeterdefineswhtherthe EmailOTP is enforced as the second step of the 2FA/MFA or not.

- If the user is not found in the active directory where the parameter is set to true, the OTP is directly sent to the email address defined in the claims set.
- If the user is not found in the active directory where the parameter is set to false , the authentication flow terminates at the first step of the 2FA/MFA.

true
false

sendOTPToFederatedEmailAttribute

When the EMAILOTPMandatory and this parameter are set to true and the user is not found in the active directory, the OTPissetn to the mail defined in the federated authenticator claim.

When the EMAILOTPMandatory is set to false, an error page gets displayed.

When the EMAILOTPMandatory is set to false and the user is not found in the active directory, the authentication mechanism terminates at the first step of the 2FA/MFA. This parameter is not required in such a scenario.

true
false

federatedEmailAttributeKey

This parameter identifies the email attribute of the federated authenticator, e.g. Foursquare. Set this parameter if the sendOTPToFederatedEmailAttribute is set to true. Example: http://wso2.org/foursquare/claims/email

EmailOTPEnableByUserClaim

This parameter enables the user to overidethefunctionalitydefinedattheEMAILOTPMandatory parameter.

- If this parameter and the EMAILOTPMandatory parameters are set to true, the user can either enable or disable the EmailOTP functionality.
- If this parameter is set to false where the EMAILOTPMandatory parameter is set to true, the user gets redirected to an error page.
- If this parameter and the EMAILOTPMandatory parameters are set to false, the authentication flow terminates at the first step of the 2FA/MFA.
- If the user is not available in the active directory

true
false

CaptureAndUpdateEmailAddress

This parameter enables the user to update the email address that is used to send the OTP, at the first login where the email address is not previously set.

true
false

EmailAddressRequestPage

This parameter enables to display a page that requests for an email address where

- The user has not registered an email address.
- Sending OTP is defined as the second step of 2FA/MFA.
- The CaptureAndUpdateEmailAddress parameter is set to true.

Example: https://localhost:9443/emailotpauthenticationendpoint/emailAddress.jsp

showEmailAddressInUI

This parameter enables to display the email address to which the OTP is sent to on the UI.

true
false

Start WSO2 IS.

Anchor
Configuring the EmailOTP provider
Configuring the EmailOTP provider
Configure the Email OTP provider

...

Create a Google account at https://gmail.com.
Got to https://console.developers.google.com and click ENABLE APIS AND SERVICES.
Search for Gmail API and click on it.
Click Enable to enable the Gmail APIs.
Info
title Why is this needed?
If you do not enable the Gmail APIs, you run in to a 401 error when trying out step13.
Click Credentials and click Create to create a new project.
Click Credentials and click the Create credentials drop-down.
Select OAuth client ID option.
Click Configure consent screen.
Enter the Product name that needs to be shown to users, enter values to any other fields you prefer to update, and click Save.
Select the Web application option.
Enter https://localhost:9443/commonauth as the Authorize redirect URIs text-box, and click Create.

Anchor
client-ID
client-ID
The client ID and the client secret are displayed.
Copy the client ID and secret and keep it in a safe place as you require it for the next step.
Anchor
copy-URL
copy-URL
Copy the URL below and replace the <ENTER_CLIENT_ID> tag with the generated Client ID. This is required to generate the authorization code.
Auitabs
direction horizontal
Auitabspage
title Format
Auitabspage
title Example
Paste the updated URL into your browser.
1. Select the preferred Gmail account with which you wish to proceed.
2. Click Allow.
3. Anchor
  Auth-code
  Auth-code
  Obtain the authorization code using a SAML tracer on your browser.
To generate the access token, copy the following cURL command and replace the following place holders:
1. <CLIENT-ID> : Replace this with the client ID obtained in Step 10 above.
2. <CLIENT_SECRET> : Replace this with the client secret obtained in Step 10 above.
3. <AUTHORIZATION_CODE> : Replace this with the authorization code obtained in Step 12 above.
  Anchor
  Refresh-token
  Refresh-token
Auitabs
direction horizontal
Auitabspage
title Format
Auitabspage
title Example
Auitabspage
title Sample Response
Paste the updated cURL command in your terminal to generate the OAuth2 access token, token validity period, and the refresh token.

Update the following configurations under the <AuthenticatorConfigs> section in the <IS_HOME>/repository/conf/identity/application-authentication.xml file.

Note

If you need to send the content in a payload, you can introduce a property in a format <API> Payload and define the value. Similarly, you can define the Form Data.FormdataforSendgridAPIisgivenasan example.
You can use <API> URLParams, <API>AuthTokenType, <API>Failure and <API>TokenEndpoint property formats to specify the URL parameters, Authorization token type, Message to identify failure and Endpoint to get access token from refresh token respectively.
Value of <API> URLParams should be like; api_user=<API_USER>&api_key=<API_KEY>&data=<DATA>&list<LIST>

Property	Description
`GmailClientId`	Enter the Client ID you got in step 10. Example: `501390351749-ftjrp3ld9da4ohd1rulogejscpln646s.apps.googleusercontent.com`
`GmailClientSecret`	Enter the client secret you got in step 10. Example: `dj4st7_m3AclenZR1weFNo1V`
`SendgridAPIKey`	This property is only required if you are using the Sengrid method. Since you are using Gmail APIs, keep the default value.
`GmailRefreshToken`	Enter the refresh token that you got as the response in step 12. Example: `1/YgNiepY107SyzJdgpynmf-eMYP4qYTPNG_L73MXfcbv`
`GmailEmailEndpoint`	Enter your username of your Gmail account in place of the `[userId]` place holder. Example: `https://www.googleapis.com/gmail/v1/users/alex@gmail.com/messages/send`
`SendgridEmailEndpoint`	This property is only required if you are using the Sengrid method. Since you are using Gmail APIs, keep the default value.
`accessTokenRequiredAPIs`	Use the default value.
`apiKeyHeaderRequiredAPIs`	This property is only required if you are using the Sengrid method. Since you are using Gmail APIs, keep the default value.
`SendgridFormData=to`	This property is only required if you are using the Sengrid method. Since you are using Gmail APIs, keep the default value.
`SendgridURLParams`	This property is only required if you are using the Sengrid method. Since you are using Gmail APIs, keep the default value.
`GmailAuthTokenType`	Use the default value.
`GmailTokenEndpoint`	Use the the deafult value.
`SendgridAuthTokenType`	This property is only required if you are using the Sengrid method. Since you are using Gmail APIs, keep the default value.

Expand

title	Click here to see a sample configuration

Code Block

<AuthenticatorConfig name="EmailOTP" enabled="true">
   <Parameter name="GmailClientId">501390351749-ftjrp3ld9da4ohd1rulogejscpln646s.apps.googleusercontent.com </Parameter>
   <Parameter name="GmailClientSecret">dj4st7_m3AclenZR1weFNo1V</Parameter>
   <Parameter name="SendgridAPIKey">sendgridAPIKeyValue</Parameter>
   <Parameter name="GmailRefreshToken">1/YgNiepY107SyzJdgpynmf-eMYP4qYTPNG_L73MXfcbv</Parameter>
   <Parameter name="GmailEmailEndpoint">https://www.googleapis.com/gmail/v1/users/alex@gmail.com/messages/send</Parameter>
   <Parameter name="SendgridEmailEndpoint">https://api.sendgrid.com/api/mail.send.json</Parameter>
   <Parameter name="accessTokenRequiredAPIs">Gmail</Parameter>
   <Parameter name="apiKeyHeaderRequiredAPIs">Sendgrid</Parameter>
   <Parameter name="SendgridFormData">sendgridFormDataValue</Parameter>
   <Parameter name="SendgridURLParams">sendgridURLParamsValue</Parameter>
   <Parameter name="GmailAuthTokenType">Bearer</Parameter>
   <Parameter name="GmailTokenEndpoint">https://www.googleapis.com/oauth2/v3/token</Parameter>
   <Parameter name="SendgridAuthTokenType">Bearer</Parameter>
   <Parameter name="redirectToMultiOptionPageOnFailure">false</Parameter>
   <Parameter name="usecase">association</Parameter> 
   <Parameter name="useEventHandlerBasedEmailSender">true</Parameter>	
</AuthenticatorConfig>

[Back to Top]

...

Versions Compared

Old Version 3

New Version Current

Key

Anchor
Configuring the EmailOTP provider
Configuring the EmailOTP provider
Configure the Email OTP provider

Page Comparison

Versions Compared

Old Version 3

New Version Current

Key

AnchorConfiguring the EmailOTP providerConfiguring the EmailOTP providerConfigure the Email OTP provider

Anchor
Configuring the EmailOTP provider
Configuring the EmailOTP provider
Configure the Email OTP provider