Bridging the gap between classic desktop apps and modern cloud security.

Stop me if you've heard this one before: You have a rock-solid legacy application that has been sending emails via SMTP for decades. Suddenly, Microsoft or Google announces they are deprecating "Basic Authentication" (username/password) in favor of OAuth2. 😱

Panic? No. Refactor? Yes!

In this post, I’ll show you how to bridge the gap between a classic Uniface desktop application and modern cloud security standards using the SASL XOAUTH2 mechanism. Let’s dive into the configuration files that make the magic happen! 🚀

The Challenge 🛑

Classic protocols like POP3 and SMTP are great, but they weren't built with modern identity providers (IdP) in mind. To connect to Office 365 or Gmail today, your application needs to:

1. Open a browser for the user to sign in (MFA included! 📱).
2. Catch the authorization_code.
3. Exchange it for an access_token.
4. Pass that token to the mail server via the SASL XOAUTH2 command.

The Solution: Uniface Configuration 🛠️

We need two key configuration files (.asn) to set this up: one for the desktop client and one for a local web listener (to catch that redirect callback).

1. The Client Configuration (uoauth2_msoutlook.asn)

This file controls your main application. Here are the critical sections you need to know about:

Enable TLS/SSL 🔒

First, you cannot do OAuth2 over plain text. You need the Uniface TLS driver and a valid root certificate bundle (cacert.pem).

[DRIVER_SETTINGS]
SLE     U1.0
TLS     U1.0
USYS$TLS_PARAMS verify_server=1, ca_certificate=cacert.pem

The Secret Sauce: USER_3GL 🧪

Uniface needs a helper library to handle the specific handshake of injecting the OAuth token into the mail protocol. This is where uauthxoauth2 comes in.

[USER_3GL]
; Loads the library to handle SASL XOAUTH2 for POP3 and SMTP
<uniface>\common\bin\uauthxoauth2(UAuthXOAUTH2POP, UAuthXOAUTH2SMTP)

The Azure AD Setup (Logicals) ☁️

Instead of hardcoding credentials in your ProcScript, we define them as logicals. Note the MS_REDIR_URI pointing to localhost!

[LOGICALS]
MS_TENANT           your_tenant_id
MS_AUTH_URL         https://login.microsoftonline.com/{MS_TENANT_MARKER}/oauth2/v2.0/authorize
MS_TOKEN_URL        https://login.microsoftonline.com/{MS_TENANT_MARKER}/oauth2/v2.0/token
; Scopes are crucial! User.Read is for profile, but don’t forget SMTP/POP scopes!
MS_SCOPE            https://outlook.office365.com/User.Read
; Where does Microsoft send the user back to?
MS_REDIR_URI        http://localhost:8080/uniface/wrd/uoauth_redir
MS_CLIENT_ID        your_client_id
MS_CLIENT_SECRET    your_client_secret  ; ⚠️ Handle with care in production!

2. The Listener Configuration (wasv.asn)

Why do we need a second file? When the user logs in at Microsoft.com, the browser redirects them back to http://localhost:8080. We need a tiny Uniface Web Application Server (WASV) running locally to "catch" this request.

[SETTINGS]
$putmess_logfile    = .\project\logs\wasv.log
[LOGICALS]
; Provides a place to dump the authorization code so the main app can read it
FILE_CODE           .\project\results\code.txt

💡 Pro Tips for Developers

• Certificate Bundles: If you get TLS errors, your cacert.pem is likely outdated. Download a fresh bundle from the cURL project. 📜
• Redirect URIs: The MS_REDIR_URI in your code must match the "Redirect URI" in your Azure App Registration exactly. A trailing slash difference will break the login! 🚫
• Token Refresh: Access tokens usually expire in 60 minutes. Ensure your logic handles the refresh_token flow so your users don't have to log in every hour. ⏳

Conclusion

Modernizing legacy apps doesn't always mean a total rewrite. With the right driver settings and a bit of 3GL integration, Uniface can talk to the latest cloud APIs comfortably.

Happy Coding! 💻✨

Source & Credits:

This setup is based on the excellent community sample provided by Rocket Software. You can find the full source code and attachments here:

👉 Rocket Uniface Community Samples: Using OAUTH2 for MS Outlook and Gmail