Use Azure Active Directory (AD) SAML authentication with PASOE
This page describes setting up PASOE to use Azure AD for authentication, using SAML as the SSO (single sign-on) 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 SAML request.
This page describes the identity provider (Azure AD) and service provider (PASOE) configuration. It does NOT describe the client application.
This configuration was tested with OpenEdge 12.5.x
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. The ROOT webapp is fine too. In this page we are using a webapp named SamlSSO .
An application URL. In this page, we are using http://localhost:8810/SamlSSO/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 an Enterprise Application
Create an Enterprise application.
Select the “Create your own application” option, and give it a name. For this example we are using cw-pas-demo .
Keep default values for the other toggles/fields.
Once the application is added, you are taken to the Overview page
Assign users
Add users from the tenant to the application
Select the users and then the Select and Assign buttons.
Setup SSO
From the Select a single sign-on method dioalog, choose the SAML option.
Select the Edit link in group 1
You must add an identifier (Add identifier link) and a Reply URL (Add reply URL link).
For the Identifier use http://localhost:8810/SamlSSO/saml2/metadata/cw-pas-demo
For the Reply URL use http://localhost:8810/SamlSSO/saml2/metadata
Click the Save link.
You should be asked if you want to test SSO; say No at this point.
Information needed by PASOE
PASOE needs certain information from AD for its configuration.
The Certificate (Raw) is needed for the SP metadata file. Download this file.
The Federation Metadata XML is the IdP (Identity Provider) metadata. Download this file, and save it into the webapp’s WEB-INF/metadata folder. In this example, $CATALINA_BASE/webapps/SamlSSO/WEB-INF/metadata/idp.xml . The name used does not matter.
The Login URL and Azure AD Identifier URLs are used for configuring the oeablSecurity.properties file in the webapp.
Generate the Service Provider (SP) metadata XML file
A SP metadata file can be generated with a tool like https://www.samltool.com/sp_metadata.php .
For the EntityId use the value used for the Identifier (Entity ID) in the Azure SSO configuration .
For the Attribute Consume Service Endpoint , use the application URL.
For the SP X.509 cert value, open the downloaded certificate and copy the complete content into the field.
Scroll down and press the BUILD SP METADATA button. An XML document should be generated, similar to the below. Copy the contents - excluding the <?xml ?> element - and save in a file - for example sp.xml . Save/copy this file into the webapp’s WEB-INF/metadata folder. In this example, $CATALINA_BASE/webapps/SamlSSO/WEB-INF/metadata/sp.xml . The name used does not matter.
PASOE configuration
Generate a domain keystore
PASOE/Spring needs to know the domain access code/key with which to seal the client-principal passed into the AVM. This uses the standard Progress tooling (gendomreg).
Create a CSV file with the domain used by Azure and a password. This can have any name, saved in any location.
consultingwerkrnd.onmicrosoft.com,z3kr1t
For this page, it is saved to $CATALINA_BASE/webapps/SamlSSO/WEB-INF/domains.csv .
The CSV file should not be stored in the instance, or in any publicly-accessible location, since it holds clear-text passwords.
Generate the domain keystore from ProEnv, using the gendomreg command. This saves the (encrypted) keystore into the webapp’s WEB-INF folder.
proenv>cd $CATALINA_BASE\webapps\SamlSSO\WEB-INF
proenv>gendomreg domains.csv domains.keystoreSee Progress Documentation: gendomreg for details on the tool.
Update security properties
The webapps/SamlSSO/WEB-INF/oeablSecurity.properties file contains the majority of the configuration information for security the SamlSSO wbapp using SAML.
The properties listed below need to be changed (or saved as a file overwriting webapps/SamlSSO/WEB-INF/oeablSecurity.properties ).
client.login.model=saml
########## 'saml' Authention Manager properties ############################
# Matches this instance and this webapp
samlToken.serviceProvider.baseUrl=http://localhost:8810/SamlSSO
# Generated SP metadata
samlToken.metadata.spMetaDataFileLocation=classpath:../metadata/sp.xml
# IdP metadata downloaded from Azure
samlToken.metadata.idpMetaDataFileLocation=classpath:../metadata/idp.xml
# comma separated list of audiences
samlToken.validation.validAudiences=${samlToken.serviceProvider.baseUrl}/saml2/metadata/${samlToken.serviceProvider.registrationId}
# Service provider registration ID
# If the ABL application has the same name as the application in Azure, then use the below
#samlToken.serviceProvider.registrationId=${oeabl.ablapp.name}
samlToken.serviceProvider.registrationId=cw-pas-demo
# Service provider entity ID
samlToken.serviceProvider.entityId=${samlToken.serviceProvider.baseUrl}/saml2/metadata/${samlToken.serviceProvider.registrationId}
# Service provider authentication filter URL
# The value of the Login URL in the Azure SSO settings (section 4)
samlToken.serviceProvider.authenticationUrl=https://login.microsoftonline.com/e896bb4e-7352-43dc-9ee1-01307ccae86d/saml2
# Service provider assertion URL
samlToken.serviceProvider.assertionConsumerServiceLocation=${samlToken.serviceProvider.baseUrl}/saml2/metadata/${samlToken.serviceProvider.registrationId}
## Required location of the OE Domain encrypted Access-code file used to seal
## Client-Principal tokens
samlToken.UserDetails.registryFile=${catalina.base}/webapps/SamlSSO/WEB-INF/domains.keystore
Configure “echo” webhandler
The request echo webhandler is a webhandler that returns information about the request as a JSON payload (similar to what 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 metadata XML files, errors will be reported in the instance’s session manager (“dated”) log.
Testing
Due to the fact that there is no client application in this setup, testing requires using some developer tools in the browser to determine the SAML request. Once the SAML request data is obtained, it will be added to a request to the PAS instance as a header.
Getting the SAML request data
To obtain the SAML request from the Azure AD admin pages, clink on the Test link
Testing with the current user is fine to validate. Click Test sign in .
A new page/tab will open in the browser. You may see messages like the below; simply click the Skip for now … link
If the login succeeds, you should see a plain white page with a title of Working … .
This page is seen because Azure sends the SAML data to the PAS instance as a form field, and not as the expected header.
To get the value of the SAML data, enable developer tools in the browser (right-click > Inspect ) and select the Network tab. Refresh the page. You should see response data like the below - in the payload there’s a SAMLResponse form field. Copy the value of that field. It will be quite long.
Using the SAML 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 SAML <saml-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 SAML data and constructing the appropriate HTTP request to the application is typically the responsibility of the client application.
Additional configuration
The list of properties set in the client-principal are the claims specified in section 2 of the SSO configuration in Azure.
Troubleshooting / debugging
If the domain keystore is not generated/accessible a redirect to the Azure login page is done, which errors since there’s already a SAML token attached to the request. Check for this in the session manager (“dated”) log
The SAML data is sent as base64-encoded XML. You can use a site like https://www.base64decode.org/ to decode the value and inspect the XML that’s sent from Azure.
To enable debug logging for SAML, see Progress Documentation: Debug logging for SAML . The doc may be wrong about the file to edit - it is (in later versions) ablapps/oepas1/conf/logging-ablapp.xml , where the ABL app name will depend on your configuration.