SMTP Open Authentication

• SMTP - Open Authentication

Provider Setup

Users must complete the provider-specific setup (Google Cloud Portal or Office 365 Portal) to obtain the necessary credentials before proceeding with IBM Navigator for i configuration.

Navigator Configuration

IBM Navigator for i provides an intuitive interface for OAuth configuration:

1. Navigate to Network > TCP/IP Servers > SMTP > Properties
2. Select the OAuth tab
3. Upload credentials file or specify IFS path
4. Enable OAuth authentication

The Navigator interface handles the execution of the CHGSMTPA command with appropriate parameters.

CHGSMTPA Command Extension

The existing CHGSMTPA command has been extended to support OAuth configuration through the OAUTH parameter.

Command Syntax

CHGSMTPA OAUTH(Credentials_path Action)

OAUTH Parameter Structure

The OAUTH parameter is a compound parameter consisting of two elements that configure OAuth authentication for the SMTP client when sending outbound mail to a mail provider.

Element 1: Credentials File Path

Values: IFS path, *SAME, *NONE
Default: *SAME

Description:

• Specifies the path to the JSON credentials file obtained from the mail provider's portal
• The file contains provider-specific OAuth 2.0 authentication information in JSON format
• Used to import credentials into the SMTP client

Value Details:

• IFS path (e.g., /tmp/google.json or /tmp/office365.json):
  • Imports OAuth credentials from the specified file
  • Stores credentials internally for use by the SMTP client
  • Replaces any existing OAuth credentials
• *SAME:
  • No change is made to the current OAuth credentials configuration
  • If no OAuth credentials are configured, no configuration is created
• *NONE:
  • Indicates that no credentials file is being supplied
  • Used when disabling or deleting OAuth
  • Does not, by itself, delete stored credentials

Element 2: Action

Values: *SAME, *ENABLE, *DELETE
Default: *SAME

Description:
Controls how OAuth authentication is handled by the SMTP client.

Value Details:

• *ENABLE:
  • Enables OAuth authentication for the SMTP client
  • If OAuth credentials are already stored, they are reused
  • If no credentials are stored, the command fails
• *DELETE:
  • Removes all stored OAuth configuration data for the SMTP client
  • Deletes credentials and associated settings
  • This operation is irreversible
• *SAME:
  • No change is made to the current OAuth usage state

Usage Notes

1. Credential Import: OAuth credentials are imported once and stored internally; the credentials file path is not required for subsequent enable operations
2. Credential Persistence: Disabling OAuth does not remove stored credentials
3. Credential Deletion: Stored credentials are removed only when Action(*DELETE) is specified
4. Validation: Invalid combinations of credentials path and action values are rejected with an error to prevent ambiguous or accidental configuration changes

Valid OAUTH Parameter Combinations

Only the combinations listed below are valid. All other combinations are rejected with an error.

Command Examples

Example 1: Configure OAuth Credentials and Enable Authentication
Imports the credentials file and enables OAuth authentication for the SMTP client in a single step.
CHGSMTPA OAUTH('/tmp/google.json' *ENABLE)
Note: This is the only way to enable OAuth.

Example 2: Delete All OAuth Credentials and Configuration
Explicitly removes all stored OAuth credentials and configuration for the SMTP client.
CHGSMTPA OAUTH(*NONE *DELETE)
WARNING: This operation is irreversible.

Example 3: Preserve Current OAuth Configuration
Makes no changes to OAuth configuration, credentials, or usage.
CHGSMTPA OAUTH(*SAME *SAME)

Security Considerations

Master Encryption Key Requirement

OAuth credentials are encrypted using IBM i master encryption key 1. If master key 1 is not set, users will be prompted to load and set it before configuring OAuth.

Authority Requirements

Users must have *IOSYSCFG special authority to configure OAuth settings for SMTP.

Credential Storage

• Credentials are stored securely using IBM i encryption
• Credentials are not stored in plain text
• Credentials persist across system restarts
• Credentials can only be deleted using the *DELETE action

User Prototype Results / Scenarios

The OAuth configuration workflow in IBM Navigator for i follows these scenarios:

1. Initial Setup: User with *IOSYSCFG authority accesses SMTP properties and navigates to OAuth tab
2. Master Key Check: System verifies master key 1 is set; prompts user if not configured
3. Credentials Upload: User uploads JSON credentials file from local system or specifies IFS path
4. OAuth Enable: User enables OAuth authentication
5. Validation: System validates credentials and configuration
6. Activation: OAuth authentication is activated for SMTP client

GUI Design

IBM Navigator for i provides functionality for SMTP properties under Network > TCP/IP Servers > SMTP > Configure OAUTH

This is only available when user has *IOSYSCFG special authority.

Figure 1: Enabling OAUTH when user has *IOSYSCFG special authority

• Navigator will require master key 1.  If not already set, users will be prompted.
• When setting the Master Key is required, the Load and Set button will show enabled.
• When the Master Key is already set, the Load and Set button will show disabled.

Figure 2: Credential file path parameter options

Figure 3: Click on Browse button prompted to File browser dialog to select path of JSON file from IFS (or) to upload from user local system

Figure 4: Upload dialog when clicking on Upload to button

Figure 5: The selected files are listed after uploading from the user local system

Figure 6: Select credentials path from IFS (or) upload from the user local system

Figure 7: Action Provider field options