Mail server settings

You can configure SMTP mail server settings in ADSelfService Plus to send reports, notifications, and alerts via email.

• How it works

• Limitations

• Prerequisites

• Configuring a mail server

  
  
  • SMTP configuration
  • Basic Authentication
  • OAuth Authentication
  • API Integration

• Steps to find your Azure tenant ID, client ID, and client secret for SMTP configuration

• Steps to find your Google Workspace client ID and client secret for SMTP configuration

• Steps to find your Azure Tenant ID, Client ID, and Client Secret for API mail server configuration

• Steps to download JSON private key for API mail server configuration

  
  
  • Enable Gmail API service
  • Delegating domain-wide authority to the service account

• Tips

How it works

ADSelfService Plus supports two modes for sending emails: SMTP mail server configuration and API integration.

SMTP mail server configuration: Two authentication modes are available for configuring your organization's SMTP mail server:

• Basic authentication: Uses a username and password to authenticate with the SMTP server. When configured, ADSelfService Plus establishes a connection to the mail server using the provided credentials and sends emails through the SMTP protocol.
• OAuth authentication: Uses secure token-based authentication through Microsoft or Google identity providers. Instead of storing passwords, ADSelfService Plus obtains an OAuth access token by authenticating with Azure AD (for Microsoft) or Google Identity Platform (for Google). This token is used to authenticate with the mail server, and emails are sent using SMTP.

API integration: Instead of connecting through SMTP, ADSelfService Plus sends emails directly via your mail provider's API:

• Microsoft Graph API: ADSelfService Plus uses Azure AD application credentials (tenant ID, client ID, and client secret) to obtain an access token and make API calls to Microsoft Graph's Mail.Send endpoint, bypassing SMTP entirely.
• Gmail API: ADSelfService Plus uses a Google service account with domain-wide delegation and a JSON private key to authenticate and send emails through the Gmail API.

Limitations

• Client Secret expiration:For Microsoft OAuth/API configurations, client secrets have an expiration period that must be managed. When the secret expires, administrators must generate a new one and update the ADSelfService Plus configuration to maintain email functionality.
• JSON Private Key security: For Google API configuration, the JSON private key can only be downloaded once during creation. If lost, a new key must be generated, and there is no way to retrieve the original private key.

Prerequisites

1. Administrator access:You must log in to ADSelfService Plus with admin credentials to configure mail server settings.
2. SMTP server details: You need the mail server's hostname or IP address, port number, and authentication credentials (username/password for Basic Authentication, or OAuth credentials for OAuth Authentication).
3. HTTPS configuration (for OAuth/API): For OAuth and API authentication modes, ADSelfService Plus must run on HTTPS protocol with a valid SSL certificate, as both Microsoft Azure and Google Identity require non-localhost redirect URIs to use the HTTPS scheme.

Configuring a mail server

SMTP configuration

1. Log in to ADSelfService Plus with admin credentials and navigate to Admin > Product Settings > Mail / SMS Settings
2. Click the Mail Settings tab.
3. Enter your mail server's Server Name or IP and Port Number in the respective fields.
4. In the From Address field, enter the email address that will be used to send out notifications, reports, and alerts from ADSelfService Plus.
5. In the Admin Mail Address field, enter the email address(es) to receive notifications for the emails sent from ADSelfService Plus.
6. From the Secure Connection (SSL/TLS) drop-down, choose an option supported by the email server.
7. Next to Authentication Type, choose either Basic Authenticationn or OAuth Authentication.

Basic authentication



1. Enter the Username and Password to access the mail server.
2. If your mail server does not require authentication, leave the fields empty.

OAuth Authentication



Select your mail provider from the available options: Microsoft or Google.

If your mail provider is Microsoft, provide the Username, Tenant ID, Client ID, and Client Secret in the respective fields. In ADSelfService Plus, Azure Cloud is considered the default Azure environment. To modify the Azure environment setting, click the Azure Environment drop-down.

Note: To learn how to find your Azure Tenant ID, Client ID, and Client Secret, please refer to the Steps to find your Azure Tenant ID, Client ID, and Client Secret section below.

If your mail provider is Google, provide the Username, Client ID, and Client Secret in the respective fields.

Note: To learn how to find your Google Client ID and Client Secret, please refer to this section titled Steps to find your Google Workspace Client ID and Client Secret below.

8. Click Save Settings to save your mail server configuration.

Note: Once the mail server settings are successfully saved, a test email will be sent to the email address entered in the Admin Email Address field.

API integration

This method allows you to create and authenticate a mail server via your mail provider’s API.

1. In the Mode field, select API.
2. Select your Mail Provider from the available options: Microsoft or Google.
3. In the From Address field, enter the email address that will be used to send out notifications, alerts, etc., from ADSelfService Plus.
4. In the Admin Mail Address field, enter your email address if you wish to receive notifications for the emails sent from ADSelfService Plus.
5. If your mail provider is Microsoft, provide the Tenant ID, Client ID, and Client Secret in the respective fields. In ADSelfService Plus, the Azure Cloud is considered the default Azure environment. You can modify the Azure environment setting by clicking the Choose the appropriate Azure environment link.

Note: To learn how to find your Google Tenant ID, Client ID, and Client Secret, click here.

6. If your mail provider is Google, upload the JSON private key file.

Note: To learn how to get your JSON private key file, click here.

7. Click Save settings.

Steps to find your Azure Tenant ID, Client ID, and Client Secret for SMTP mail server configuration

1. Log in to portal.azure.com.
2. Under Azure services, click App registrations > New registration.
3. Provide a Name of your choice and select Supported Account Types, leaving it in its default setting.
4. In the Redirect URI field, paste the redirect URI in the following syntax:
https://server_name:port_number/context_if_any/RestAPI/WC/OAuthSetting
For example: https://localhost:8082/RestAPI/WC/OAuthSetting.

Note: To ensure security, Microsoft Azure requires non-localhost redirect URIs to begin with the HTTPS scheme. This may require ADSelfService Plus to run on the HTTPS protocol. Please find the steps to enable HTTPS in this guide.

5. On the next page, you will find the application details. Copy the Client ID and Tenant ID.
6. From the left pane, click Certificates & secrets > New client secret.
7. Provide a Description for the client secret, and in the Expires field, choose the validity of the client secret and click Add.
8. The client secret will be generated. Copy the string displayed under Value.
9. Click Save Settings and complete the authorization prompt.

Steps to find your Google Workspace Client ID and Client Secret for SMTP mail server configuration

1. Log in to console.developers.google.com.
2. From the dashboard, click Create to create a new project if there is no existing project, or select any existing project and click New Project.
3. Enter the Project Name. In the Location field, click Browse and select the Parent Organization.
4. Click Create.
5. In the left pane of the displayed project details page, click APIs & Services > Library.
6. From the available list of APIs, select Gmail API and click Enable. You can use the search option to find the API quickly.
7. In the left pane, click OAuth consent screen and choose the User Type. If you don't have a Google workspace account, choose External User.
8. Provide the Application Name, Application Logo, and the Support Email of your help desk, Developer Information, and click Save & Continue.
9. Click Add or Remove Scopes, choose Gmail API (https://mail.google.com/), and click Update. Then click Save & Continue.
10. Add a test user and click Save & continue.
11. In the left pane, click Credentials > Create Credentials > OAuth Client ID.
12. Select the application type as Web Application. Provide a name of your choice.
13. In the Redirect URI field, paste the redirect URI in the following syntax:
https://server_name:port_number/context_if_any/RestAPI/WC/OAuthSetting
For example: https://localhost:8082/RestAPI/WC/OAuthSetting.

Note: To ensure security, Google Identity requires non-localhost redirect URIs to begin with the HTTPS scheme. This may require ADSelfService Plus to run on the HTTPS protocol. Please find the steps to enable HTTPS in this guide.

14. Click Save.
15. Click DOWNLOAD JSON to download the file containing the authorization server details. Copy the Client ID and Client Secret displayed on the screen.
16. Click Save Settings and complete the authorization prompt.

Steps to find your Azure Tenant ID, Client ID, and Client Secret for API mail server configuration

1. Log in to portal.azure.com.
2. Under Azure services, click App registrations > New registration.
3. Enter a Name of your choice and choose the Supported account types. (If you’re unsure about the supported account types, select Accounts in the organizational directory only).
4. In the left pane, click API Permission > Add a permission.
5. Click Microsoft Graph > Application permission.
6. Search for Mail and select the Microsoft Graph endpoint. Click Add Permission.
7. Click Grant admin consent.
8. Copy the Client ID & Tenant ID displayed.
9. In the left pane, click Certificates & secrets > New client secret.
10. Provide a Description for the client secret. In the Expires field, choose the validity of the client secret and click Add.
11. The client secret will be generated. Copy the string displayed under Value.

Steps to download JSON private key for API mail server configuration

1. Log in to console.developers.google.com.
2. Open the Service accounts page.
3. Click Create Project. Enter the project name, organization and location. Click Create.
4. Click + Create service account in the top row.
5. Under Service account details, type a Name, ID, and Description for the service account, then click Create and continue.
6. If required, you can also select the IAM roles to be granted to the service account using the Grant this service account access to project option.
7. Click Continue.
8. If required, you can add the users or groups that are allowed to use and manage the service account.
9. Click Done.
10. Click the email address for the service account you created.
11. Click the Keys tab.
12. In the Add key dropdown list, select Create new key.
13. Select key type as JSON.
14. Click Create.

Your new public/private key pair will be generated and downloaded to your machine. Please keep the private key safe as this will be the only copy, and you cannot generate the same private key again.
Once you have downloaded the JSON private key, you’ll have to enable the Gmail API service and provide domain-wide authority to the service account.

Enable Gmail API service

1. Login to console.cloud.google.com.
2. Select the project from the dropdown menu.
3. Click + Enable APIS and Services.
4. Select Gmail API and click Enable.

Delegating domain-wide authority to the service account

1. Log in to the Google Workspace domain's Admin console as a super administrator.
2. Navigate to Main menu > Security > Access and data control > API Controls.
3. In the Domain wide delegation pane, select Manage Domain Wide Delegation.
4. Click Add new.
5. In the Client ID field, enter the service account's Client ID. You can find your service account's client ID on the Service accounts page.
6. In the OAuth scopes (comma-delimited) field, enter the list of scopes that your application should be granted access to. For example, if your application needs domain-wide full access to the Google Mail API, enter: https://mail.google.com.
7. Click Authorize.

Your application now has the authority to make API calls as users in your domain (to "impersonate" users). When you prepare to make authorized API calls, specify the user to be impersonated.

Tips

• Plan for Client Secret expiration: When using Microsoft OAuth or API authentication, set calendar reminders before your client secret expires and establish a process for rotating secrets without service disruption—consider creating secrets with longer validity periods (e.g., 24 months) for production environments.
• Secure your credentials: Store Azure client secrets and Google JSON private keys securely. For Google API configurations, download and back up the JSON private key immediately after creation, as it cannot be retrieved later—store it in a secure password manager or secrets vault.