• In progress
  • 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.

    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 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.

    1. 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 .

    2. 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 .

    3. 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.keystore

    See 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.

    [oepas1.SamlSSO.WEB] adapterEnabled=1 defaultCookieDomain= defaultCookiePath= defaultHandler=RequestEchoHandler srvrAppMode=development srvrDebug=1 wsRoot=/SamlSSO/static/webspeed

     

    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

    // Curl doc at https://curl.se/docs/manpage.html curl http://localhost:8810/SamlSSO/web/hello -H "Authorization: SAML <saml-data>"

     

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

    { "method": "GET", "uri": "http:\/\/localhost:8810\/SamlSSO\/web\/hello", "origin": "127.0.0.1", "pathParameters": { "TEMPLATE": "\/" }, "args": {}, "headers": { "COOKIE": "", "USER-AGENT": "curl\/7.83.1", "ACCEPT": "*\/*", "HOST": "localhost:8810", "REFERER": "", "PORT": "8810" }, "cookies": {}, "user": { "qualifiedUserId": "peter.judge@consultingwerkrnd.onmicrosoft.com", "domainType": "OEApplication", "loginState": "SSO", "sealAt": "2022-08-03T14:38:01.000-04:00", "expireAt": "2022-08-03T15:18:47.000-04:00", "sessionId": "_883cd0ae-6724-46ad-8fa8-40ed2dd85300", "roles": [ "ROLE_PSCUser" ], "properties": [ {"http:\/\/schemas.microsoft.com\/identity\/claims\/displayname": "Peter Judge"}, {"http:\/\/schemas.microsoft.com\/identity\/claims\/tenantid": "e896bb4e-7352-43dc-9ee1-01307ccae86d"}, {"http:\/\/schemas.microsoft.com\/identity\/claims\/identityprovider": "https:\/\/sts.windows.net\/e896bb4e-7352-43dc-9ee1-01307ccae86d\/"}, {"http:\/\/schemas.microsoft.com\/identity\/claims\/objectidentifier": "c661f958-4c82-4387-9d3e-6aa8654e2dc7"}, {"http:\/\/schemas.xmlsoap.org\/ws\/2005\/05\/identity\/claims\/givenname": "Peter"}, {"http:\/\/schemas.xmlsoap.org\/ws\/2005\/05\/identity\/claims\/name": "peter.judge@consultingwerkrnd.onmicrosoft.com"}, {"http:\/\/schemas.microsoft.com\/claims\/authnmethodsreferences": "http:\/\/schemas.microsoft.com\/ws\/2008\/06\/identity\/authenticationmethod\/password"}, {"http:\/\/schemas.xmlsoap.org\/ws\/2005\/05\/identity\/claims\/surname": "Judge"} ] }, "data": {} }

     

    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.