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:
- Open a browser for the user to sign in (MFA included! 📱).
- Catch the
authorization_code. - Exchange it for an
access_token. - 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.pemis likely outdated. Download a fresh bundle from the cURL project. 📜 - Redirect URIs: The
MS_REDIR_URIin 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_tokenflow 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
Top comments (0)