Tomorrow's (11-22-2022) 8.1.24-SNAPSHOT early access build includes a couple of exciting new additions to the product: OAuth2 Clients and OAuth2 SMTP Email Profiles.
Background
Email providers such as Gmail and Microsoft 365 expose SMTP services in order for products such as Ignition to connect to them for the purposes of sending email. Access control to these services are usually enforced through basic authentication and authorization. The authentication piece entails verification of a username and a password at the time of sending the email (built into the SMTP protocol). If the credentials are valid, the user is authorized to send email, otherwise they are unauthorized.
Although simple to set up and use, Basic Authentication makes it easier for attackers armed with today’s tools and methods to capture users’ credentials and increases the chance of credential re-use against other endpoints or services. Because of this, email providers have introduced a more modern and secure technique for authentication and authorization built on top of OAuth 2.0, an open web-based delegated authorization framework. Email providers which have introduced support for OAuth2 have begun pushing their clients to adopt this auth method and have even begun turning off outdated methods of auth such as Basic Auth (example #1: Microsoft; example #2: Google).
The software engineering team at IA has paid attention to these Email Providers' policy changes, and has listened to the community's feedback and concern in this forum. We determined it is in the best interest of Ignition and its users to introduce support for OAuth2 in order to position them for the future of secure email. But as you'll see below, secure email is just the beginning. We've architected these new features in a way which should open up opportunities to securely access almost any service which requires OAuth2-based authorization in a first-class way. I encourage you to read this post in its entirety to understand how we've done this.
OAuth2 Clients
You may configure and manage your OAuth2 clients by navigating to the new page located at Gateway Web Interface > Config Page > Security > OAuth2 Clients:
Creating (or editing) an OAuth2 client will require settings you will likely be familiar with if you have experience working with OAuth 2.0:
The settings will also seem familiar to those of you who have configured an Open ID Connect (OIDC) IdP in Ignition, since OIDC 1.0 is built on top of OAuth 2.0.
We also added a couple of "Test" tools which resemble the IdP Test Login tool.
Test Authorization
The first test tool is named "Test Authorization". It will be visible if your OAuth2 client is configured with a valid Authorization URL. The purpose of this tool is to test the integration between your OAuth2 client configuration in Ignition and the OAuth2 authorization server's authorization endpoint.
You first begin the authorization test by helping Ignition craft an Authorization Request tailored to whatever resource you'd like to request access to:
In the screen shot above, I am setting up Ignition to request access to send emails using Google's SMTP server on behalf of whatever user I choose to log into Google as (see supporting Google documentation #1 and #2 for more info).
Clicking the primary "Test Authorization" action button will redirect your web browser to the OAuth2 server's authorization endpoint configured in the OAuth2 client settings (in my example, it's Google):
Complete the login process over at your Authorization Server (enter credentials, complete optional 2FA, and optionally grant consent for Ignition to send emails on behalf of the user you are logging in as):
Once you complete the login process at the Authorization Server, you will be redirected back to the redirect URL for the OAuth2 client configured in Ignition. Ignition will parse the Authorization Response and show the results on the next page, which should help troubleshoot the integration and your configuration settings.
Test Token
The second test tool is named "Test Token". The purpose of this tool is to test the integration between your OAuth2 client configuration in Ignition and the OAuth2 authorization server's token endpoint.
You first begin the token test by helping Ignition craft an Access Token Request tailored to whatever resource you'd like to request access to:
In the screen shot above, I am testing an Access Token Request with Grant Type of "Authorization Code". The supported Grant Types in Ignition are:
Clicking the primary "Test Token" action button will open up a modal within the same page and show details of the Access Token Exchange, which will include:
- The Access Token Request sent from the Gateway's OAuth2 client to the Authorization Server's token endpoint (configured using the OAuth2 client's token URL setting in Ignition)
- The parsed Access Token Response, which might be successful (including an access token, optional refresh token, expiration time, etc) or erroneous (including info to hopefully help diagnose the error)
One special note about testing the Authorization Code Grant Type: since the Access Token Request for this grant type requires an authorization code and redirect URL which is part of an interactive Authorization Exchange, we added a button on the "Test Authorization" results page to jump to the "Test Token" page with the auth code and redirect URL values pre-filled from the Authorization Exchange you completed on the "Test Authorization" tool.
You may also start on the "Test Token" tool and click the "Test Authorization" link underneath the Auth Code and Redirect URL form fields in order to run through an Authorization Exchange and derive these values.
OAuth2 SMTP Email Profiles
We refactored SMTP Profiles into "Email Profiles". All existing SMTP Profiles configured at Gateway Web Interface > Config Page > Networking > Email Settings will be upgraded to a "Classic SMTP Email Profile" type. These profiles should continue to behave as they did before upgrade. They are limited to Basic Authentication support.
Taking advantage of this new Email Profile extension point, we added a new "OAuth2 SMTP Email Profile" type which supports the more advanced OAuth2-based authentication mechanism.
You may configure and manage your OAuth2 SMTP Email Profiles by navigating to the new page located at Gateway Web Interface > Config Page > Networking > Email Settings:
Select the "OAuth2 SMTP Email Profile" type:
2
Creating (or editing) an OAuth2 SMTP Email Profile will require settings you will likely be familiar with if you have experience working with SMTP Profiles in Ignition and OAuth 2.0 in general:
Notice the "OAuth2 Settings" section. You provide a username, just as you do for the Classic SMTP Email Profile type, but instead of a password, you must instruct the OAuth2 SMTP Email Profile how to obtain valid access tokens which will be used instead of a fixed password. You do this by configuring the following settings:
- Select an
OAuth2 Clientto use for granting access tokens for your target SMTP server - Enable or disable the
Interactivecheckbox based on whether or not your Authorization Server requires the "3-legged" authorization code grant type or the "2-legged" client credentials grant type - Add the OAuth2 scopes required to grant access tokens with privileges to send emails to the SMTP server
There are also a collection of "Advanced Settings":
These advanced settings allow you to control additional behavior beyond the default behavior, such as additional authorization or access token request parameters, timeouts, TLS versions, etc.
Interactive Mode Enabled
If user interaction is required to grant an access token to Ignition, you must enable the "Interactive" checkbox. When Interactive mode is enabled, access tokens are granted through the "3-legged OAuth Flow" using the "Authorization Code" grant type. If enabled, you must grant the initial access token (and optional refresh token) to Ignition manually by navigating to Gateway Web Interface > Config > Networking > Email Settings and clicking the More dropdown button and selecting Manage Token next to the target OAuth2 SMTP Email Profile.
When you first set up your OAuth2 SMTP Email Profile, the "Manage Token" page will look like this:
Click the "Grant New Token" primary action button to initiate an Authorization Request. You will be redirected to the Authorization Server's authorization URL configured on the OAuth2 Client in order to login and grant an access token with the configured scopes for Ignition. After logging in and granting consent for Ignition, the Authorization Server will redirect you back to Ignition, which will redirect you back to the "Manage Token" page. In the background, Ignition will send an Access Token Request of grant type "Authorization Code" to the Authorization Server's token URL configured on the OAuth2 Client settings (using the authorization code that the authorization server encoded on the redirect URL back to Ignition after logging in). The status of the access token will reflect on the "Manage Token" page and can be viewed any time to check in on its status (ideally it should be in a valid state such as the below):
If your authorization request parameters and/or scopes are configured according to your authorization server's guidelines, your authorization server may grant a refresh token in the Access Token Response. Ignition will use this refresh token to obtain a new access token in the background every time the current access token expires. As long as this refresh token is valid, Ignition will be able to continually obtain valid access tokens in the background without any user interaction required. As soon as Ignition is unable to obtain an access token on its own, user interaction will again be required by following the steps above to manually grant Ignition a new access token (and optional refresh token).
Interactive Mode Disabled
Disable the "Interactive" checkbox if you'd like to use the "2-legged OAuth Flow" using the "Client Credentials" grant type. As long as your OAuth2 Client and OAuth2 SMTP Email Profile settings are configured appropriately as per your authorization server's requirements, Ignition should be able to automatically grant itself access tokens in the background without any user interaction. It does this by sending Access Token Requests of grant type "Client Credentials" to the authorization server's token endpoint every time its current access token is about to expire (or is invalid for some other reason).
Note: you may grant new access tokens (in the case of interactive mode = enabled) any time you want, even if the current token is valid. You may also refresh the current token any time you want if interactive mode = enabled and Ignition has a valid refresh token, or if interactive mode = disabled.
Test Email Tool
The "Test Email" tool is still available with all SMTP Email Profile types, just as it was with SMTP Profiles.
Navigate to Gateway Web Interface > Config Page > Networking > Email Settings. Next to the Email Profile you wish to test, click on the More drop down button and click on the test sub-action-button.
This will bring you to the familiar "Test Email" tool's page where you can fire off a test email message to see if your configuration and integration is working as expected:
Conclusion
In the first section of this post, I mentioned this:
We've architected these new features in a way which should open up opportunities to securely access almost any service which require OAuth2-based authorization in a first-class way.
If you've read through the entire post up to this point, by now you might begin to understand what I meant. Instead of simply creating an "OAuth2 SMTP Email Profile" and embedding all OAuth2 specific settings inside of it, we've abstracted out the concept of managed "OAuth2 Clients" which can be referenced by name anywhere in the Gateway. This means that any sub system which could benefit from OAuth2-based authorization could be made compatible with these OAuth2 clients in the future.
For now, the OAuth2 SMTP Email Profile is the only other sub system in Ignition which knows how to use these OAuth2 Clients, but in the future, we intend to expand adoption of these clients.
Some other notable future efforts we are tracking in our internal ticket management system:
- IGN-6575: add scripting support for OAuth2 Clients
- IGN-6576: support additional client authentication methods with the authorization server's token endpoint, including HTTP POST-based client credentials and JWT-based authentication
- IGN-6757: add PKCE support to the OAuth2 Clients
We are curious which other areas of Ignition and your own projects could benefit from these OAuth2 Clients. Please don't hesitate to share your thoughts and feedback on this forum or in our ideas portal, and stay tuned for more!