This page describes setting up PASOE to use Azure AD for authentication, using OAUTH2 authentication mechanism. It is important to remember that PASOE itself does not act as a client application and so cannot perform a login itself; this means that another application (the client application, Azure itself) must provide the OAUTH2 bearer token.

This page describes the identity provider (Azure AD) and service provider (PASOE) configuration. It does NOT describe the client application.

Documentation links

Documentation links
https://docs.progress.com/bundle/openedge-pasoe-saml-quickstart/page/Configure-PAS-for-OpenEdge-to-use-SAML.html
https://community.progress.com/s/article/How-to-configure-SAML-authentication-with-PASOE

This configuration was tested with OpenEdge 11.7.15 (should work 11.7.2+).

The configuration has changed between 11.7 , 12.0 and 12.5 . See the Progress doc for details

Prerequisites

Before setting up Azure Active directory you will need to know some information about the PASOE instance and webapp(s) that will use Azure for authentication.

The instance’s host and port. This can be localhost and/or inside the firewall. In this page we are using http://localhost:8810 or https://localhost:8811 .
The webapp that needs to be setup to use SAML SSO. In this page we are using the ROOT webapp.
An application URL. In this page, we are using http://localhost:8810/web/hello . This page is configured to simply “echo” the request using a particular webhandler.

Set up Azure Active Directory (AD)

You need to have administrative access to the AD tenant. This example uses a domain on the free tier of Office365, called consultingwerkrnd.onmicrosoft.com .

Users

Ensure you have some users in the domain / AD tenant.

Set up a Registered Application

From the Dashboard, select Enterprise Applications. Register a new applicaiton by clicking the application registrations link

Create a new registered application

Select the New Registration link

Give the application a name and make sure to specify a redirect URI. This should point to the preruisite URL

Click the Register button at the botton of the screen. This creates a new Enterprise Application and a registered app and takes you to the App Registration overview. Important here are the Endpoints link, and the Application (client) ID information.

Update the Authentication data

Select the Authentication link in the Manage group.

The platform configuration has defaulted to “Web”due to the addition of the redirect URI earlier.

Select (at least) the ID tokens checkbox. These are the only token types supported by PASOE in 11.7.

Click Save .

Upload a public key certificate

Create a public key certificate (self-signed). See https://learn.microsoft.com/en-us/azure/application-gateway/self-signed-certificates for instructions.

Upload it to the app, using the Certificates & secrets link.

Gathering information required for PASOE

The PASOE configuration needs 2 main pieces of information: the JWK keystore location, and the application id .

Keystore location URL

The keystore URL is available as part of the OpenID Connect metadata. The application-specific URL for that document is available from the Overview > Endpoints link.

Get that URL (in a browser or other tool). The URL returns JSON data,

{
	"token_endpoint": "https://login.microsoftonline.com/e896bb4e-7352-43dc-9ee1-01307ccae86d/oauth2/v2.0/token",
	"token_endpoint_auth_methods_supported": [
		"client_secret_post",
		"private_key_jwt",
		"client_secret_basic"
	],
	"jwks_uri": "https://login.microsoftonline.com/e896bb4e-7352-43dc-9ee1-01307ccae86d/discovery/v2.0/keys",
	"response_modes_supported": [
		"query",
		"fragment",
		"form_post"
	],
	"subject_types_supported": [
		"pairwise"
	],
	"id_token_signing_alg_values_supported": [
		"RS256"
	],
	"response_types_supported": [
		"code",
		"id_token",
		"code id_token",
		"id_token token"
	],
	"scopes_supported": [
		"openid",
		"profile",
		"email",
		"offline_access"
	],
	"issuer": "https://login.microsoftonline.com/e896bb4e-7352-43dc-9ee1-01307ccae86d/v2.0",
	"request_uri_parameter_supported": false,
	"userinfo_endpoint": "https://graph.microsoft.com/oidc/userinfo",
	"authorization_endpoint": "https://login.microsoftonline.com/e896bb4e-7352-43dc-9ee1-01307ccae86d/oauth2/v2.0/authorize",
	"device_authorization_endpoint": "https://login.microsoftonline.com/e896bb4e-7352-43dc-9ee1-01307ccae86d/oauth2/v2.0/devicecode",
	"http_logout_supported": true,
	"frontchannel_logout_supported": true,
	"end_session_endpoint": "https://login.microsoftonline.com/e896bb4e-7352-43dc-9ee1-01307ccae86d/oauth2/v2.0/logout",
	"claims_supported": [
		"sub",
		"iss",
		"cloud_instance_name",
		"cloud_instance_host_name",
		"cloud_graph_host_name",
		"msgraph_host",
		"aud",
		"exp",
		"iat",
		"auth_time",
		"acr",
		"nonce",
		"preferred_username",
		"name",
		"tid",
		"ver",
		"at_hash",
		"c_hash",
		"email"
	],
	"kerberos_endpoint": "https://login.microsoftonline.com/e896bb4e-7352-43dc-9ee1-01307ccae86d/kerberos",
	"tenant_region_scope": "EU",
	"cloud_instance_name": "microsoftonline.com",
	"cloud_graph_host_name": "graph.windows.net",
	"msgraph_host": "graph.microsoft.com",
	"rbac_url": "https://pas.windows.net"
}

The URI is contained in the jwks_uri property.

The application ID is a GUID value, available in the Overview page.

PASOE configuration

Update security properties

The webapps/ROOT/WEB-INF/oeablSecurity.properties file contains the majority of the configuration information for securing the webapp using OAuth2.

The properties listed below need to be changed (or saved as a file overwriting webapps/ROOT/WEB-INF/oeablSecurity.properties ).

client.login.model=oauth2

## An encrypted value can be generated using 'genpassword'
OEClientPrincipalFilter.domain=azure
OEClientPrincipalFilter.key=azure-dac

jwtToken.keystore.type=jwk
# This value is taken from the jwks_uri property from the metadata
jwtToken.keystore.jwkurl=https://login.microsoftonline.com/e896bb4e-7352-43dc-9ee1-01307ccae86d/discovery/v2.0/keys

oauth2.resSvc.tokenServices=jwt
# The application (client) ID
oauth2.resSvc.audience=49b8af06-8920-44a7-b36c-6c00813a4a1f

The OEClientPrincipalFilter domain and key are used to seal the client-principal that’s sent to the PASOE agent. This domain is not the domain used by the Azure tenant.

Update authorization rules

There are no “scopes” defined for this app in Azure, so we need to allow remove all authorization. Edit the webapps/ROOT/WEB-INF/oeablSecurityJWT.csv file so that it either only includes the lines below, or that all other lines are commented out.


# Allow all for testing; not a good practice for production
"/**","*","permitAll()"

Configure “echo” webhandler

The request echo webhandler is a webhandler that returns information about the request as a JSON payload (similar to what http://httpbin.org does). It is publicly available at https://github.com/PeterJudgeZA/http_samples/blob/master/web_handler/request_echo/RequestEchoHandler.cls . If run with a ?debug query parameter, additional information is returned.

In this example, all /web requests are hanbdled by this webhandler, including /web/hello that's used as the application URL.

Start the instance

If there are format/syntax issues with the configuration, errors will be reported in the instance’s session manager (“dated”) log.

Testing

From a web browser, run the following request. The URL is the value of the OAuth 2.0 authorization endpoint (v2) field in the Endpoints screen.

Documentation on the URL is at https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow#request-an-id-token-as-well-or-hybrid-flow

The client_id value is the application ID taken from the Overview page.

The redirect_uri value is the same (must be) value from the initial setup; it must also be URL encoded.

The response_type must be id_token .

Paste the URL into the browser URL bar ; before hitting enter, make sure that you enable developer tools in the browser (right-click > Inspect ) and select the Network tab.

Now hit enter; you will be promted for your Azure credentials, and on successful authentication, be redirected to the /web/hello page configured as the redirect URI.

This returns an error, along the lines of.

In the response data, there’s an id_token field . Copy the value of that field.

You can validate that it’s a proper JWT at https://jwt.ms/ .

Once the id token data is obtained, it will be added to a request to the PAS instance as a header.

Using the OAuth2 token to request application data

A request can now be made to the PAS application. The SAML data must be sent as the Authorization header, with the value in the format Bearer <id-token> .

An example using curl is

A JSON response should be returned. Note the user property, which contains information about the Azure enterprise application user.

The receiving of the ID token and constructing the appropriate HTTP request to the application is typically the responsibility of the client application.

Additional configuration

More information can be added to the ID token, such as the user’s email address and client IP address.

To do so, select the Token configuration option. Add optional claims

In order to have this data returned, a profile scope needs to be added to the authorization request, as a space-delimited value, eg. &scope=openid profile . The email address is returned as a preferred_user property in the client-principal.

Troubleshooting / debugging

https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc for error codes on authentication / login

SmartComponent Library

Use Azure Active Directory (AD) OAUTH2 authentication with PASOE