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

For SetSecurity:

  • 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

Microsoft

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

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

Related Topics