XOAUTH2 Security Driver

The Uniface XOAUTH2 security drivers for POP and SMTP provide email server authentication using OAuth 2.0.

activate "UPOPMAIL".SetSecurity(DriverProperties, DriverParameters)

activate "UPOPMAIL".GetSecurity(DriverNumber, ServerType, RuntimeInfo)

Parameters

DriverProperties—Uniface list with the following syntax:
"ServerType=EntryPointFunction {;USE=MAND | OPT}".
- ServerType—one of POP or SMTP
- EntryPointFunction—function that implements a security driver; one of UAuthXOAUTH2POP or UAuthXOAUTH2SMTP.
  The entry point must match the ServerType:
  POP=UAuthXOAUTH2POP
  SMTP=UAuthXOAUTH2SMTP

DriverParameters—Uniface list containing driver-specific parameters that are used during authentication.

LOGIN Parameters
Keyword	Allowed Values	Description
`USER`	User	User name to use for the login. Mandatory. For Windows, this may need to be in the form Domain`\`User
`TOKEN`	AccessToken	Access token obtained by one of the flows defined by the OAUTH2 standard.

For GetSecurity :

DriverNumber—number of the driver in the security context; usually 1. IN parameter
DriverProperties—must contain the string "SMTP=" or "POP=" and returns the DriverProperties string as used in the SetSecurity operation.
RuntimeInfo—Uniface list containing information provided by Uniface. The XOAUTH2 driver does not provide extra runtime information.

Description

The SMTP and POP XOAUTH2 security drivers are provided in a shared library, each with its own entry point.

On Windows, the compiled library is uauthxoauth2 and is provided in the \common\bin of your Uniface installation.

On Unix, the compiled library is libuauthxoauth2 and is provided in the /common/lib directory of your Uniface installation.

To use both the SMTP and POP drivers, specify the library and entry points in the [USER_3G] section of the assignment file:

; Windows
[USER_3GL]
Location\uauthxoauth2(UAuthXOAUTH2POP, UAuthXOAUTH2SMTP)

; Unix
[USER_3GL]
Location\libuauthxoauth2(UAuthXOAUTH2SMTP,UAuthXOAUTH2POP)

If you are only using one of the drivers, you only need that one entry point.

The source files for the security driver are available in the Security Driver Sample on Rocket Community .

OAuth 2.0

OAuth 2.0 is an open standard for access delegation that is used to permit users to share information about their accounts with third party applications or websites.

The authentication flows of the OAuth 2.0 standard result in a token that can be used in a similar way to a password. SMTP and POP servers offer a means to use such a token through an authentication extension called XOAUTH2. See Obtaining and Using Tokens.

When connecting to the email server, the security driver interrogates the server about the functionality it supports to determine if the XOAUTH2 extension can be used.

POP3 Authentication

The default authentication mechanism for POP3 connections is to use the user name and password provided by the operation "UPOPMAIL".logonmail, after the security context has been established (by "UPOPMAIL".setsecurity). It is used in the following circumstances:

No security context established.
No security driver for POP3 is defined in the security context.
An authenticating driver for POP3 was defined as optional ( USE=OPT), and the POP3 server does not support its functionality.
No authenticating driver has been defined in the security context.

The UAUTHXOATH2POP driver provided by Uniface is an authenticating driver. This means that after the security context has been defined (using "UPOPMAIL".setsecurity), the driver does not use the user name and password provided by the operation "UPOPMAIL".logonmail.

If the driver is mandatory (USE=MAND) and if the POP3 server does not support it, an error is returned.

If the driver is optional (USE=OPT) and the POP3 server does not support it, the driver is not used, and authentication fall back to the default mechanism.

If you build your own POP3 security driver, you can use macros the USecSetAuthenticating(SecurityDriver), USecZeroAuthenticating(SecurityDriver) and USecIsAuthenticating(SecurityDriver) to set and check the authentication flag. For more information, see Security Driver Macros.

Obtaining and Using Tokens

To obtain and use tokens, you must register your application with the email provider. You then need to decide on the OAUTH authorization flow you want to use. For details, consult the provider's documentation.

To help you get started, our developers found the following links and tips helpful:

About OAuth 2.0

The OAuth 2.0 Authorization Framework (RFC 6749)
Obtaining authorization
Which OAuth 2.0 Flow Should I Use?—an independent software vendor's document that tries to answer the question

Microsoft

OAuth 2.0 and OpenID Connect protocols on Microsoft—Microsoft descriptions of the basic components of these flows
Application types for Microsoft identity platform
Register an application with Microsoft—describes how to register an application with Microsoft
OAuth 2.0 authorization code flow—describes the authorization code flow, which is recommended by Microsoft.
This flow normally requires interactive user participation to log on.
Tip: If you did not register your application as a public client, you will need to add a client secret (from your application registration) to your request to the token server, when exchanging the access code for the access token.
OAuth 2.0 resource owner password credentials flow—describes the resource owner flow. This flow is not recommended by Microsoft.
This flow is non-interactive so a user account defined with Multi-Factor Authentication cannot be used with this flow.

Tips:

When registering the application, you add permissions from Microsoft Graph to allow various types of access to SMTP and POP3 servers. For example, SMTP.Send and POP.AccessAsUser.All.
When constructing requests to the authorization or token servers, you refer to these permissions in the scope parameter of the URL. In the scope, the permissions need to be prefixed with https://outlook.office365.com. For example, before URL encoding:
```
&scope=https://outlook.office365.com/POP.AccessAsUser.All https://outlook.office365.com/SMTP.Send
```

Google

Using OAuth 2.0 to Access Google APIs—describes the process of obtaining and using OAuth 2.0 credentials, access tokens , and refresh tokens.
Installed application types
OAuth 2.0 Mechanism—describes Google's mechanism to allow the use of OAuth 2.0 Access Tokens to authenticate to a user's Gmail account.
OAuth 2.0 for TV and Limited-Input Device Applications—explains how to implement OAuth 2.0 authorization for applications running on devices that do not have access to a browser or have limited input capabilities.
This is useful if you are using curl commands to obtain tokens.
Choose Auth Scopes—describes the Auth scopes which express the permissions you request users to authorize for your app, such as the ability to read, write, and delete mail messages.

Tip:

For the Authorization Code Flow, when you construct your requests to the authorization or token servers, you need to specify the scope parameter as:

&scope=https://mail.google.com