To implement SAML in PAS for OpenEdge, you need to perform two tasks:
  • Set up a PAS for OpenEdge client application.
  • Configure SAML properties in a PAS for OpenEdge web application.

Setting up a PAS for OpenEdge client application

Since a PAS for OpenEdge web application does not act as a direct-login service provider, you need to develop a PAS for OpenEdge client application that can communicate with end users and work with identity providers.

The common use case is to develop a client application (for example, a Kendo UI Builder application) that provides HTML pages that end users access via a browser. When the end user clicks a link or URL that requires a protected OpenEdge resource, the PAS for OpenEdge client initiates a SAML workflow. This resource could be, for example, an ABL business entity wrapped in a Data Object Service, in which case you would want your PAS client to call a URL such as http://host:port/OpenEdgeApplication/rest/DataObjService/ABLBusinessEntity.

To implement this use case, you must develop your PAS client application and set it up to work with an identity provider of your choice. The important thing to remember is that the PAS client application must send the SAML assertion that it receives from an identity provider to the PAS for OpenEdge web application.

Note:

To obtain a protected resource from PAS for OpenEdge, the client application must send a valid SAML assertion to the PAS for OpenEdge web application. This assertion must be sent in the Authorization header of the HTTP request with the prefix SAML.

Also, the HTTP method that your PAS client uses to send SAML assertions must match the samlToken.httpBinding.allowedMethods property set in the oeablSecurity.properties file. It must also match a method defined for the resource URL in the oeablSecurity.csv file.

In addition, you need to generate a metadata file for your PAS client application. This task is performed either by an application developer or a system administrator. There are tools available online (such as this one) that can help generate this metadata. The metadata is useful not only when you are configuring the identity provider to communicate with your PAS for OpenEdge client application, but also when you are configuring SAML properties in the PAS for OpenEdge web application.

Configuring SAML properties in a PAS for OpenEdge web application

After you have set up your client application, configure the following properties in your PAS for OpenEdge web application's oeablSecurity.properties file located in the WEB-INF folder.
Note: Before you configure these properties you should download the metadata file of the client application as well as the identity provider and store them in a location that is accessible to your PAS for OpenEdge web application.

Client login model

Set the value of the client.login.model property to saml.

client.login.model=saml

Metadata

Set the path to the PAS client application's (service provider's) metadata.

samlToken.metadata.spMetaDataFileLocation=<path to PAS client application's metadata>

Set the path to the identity provider's metadata.

 samlToken.metadata.idpMetaDataFileLocation=<path to IdP's metadata>

HTTP Method Validation

Set the allowed HTTP methods for incoming HTTP requests that contain the SAML assertion. If the only allowed method is GET, and the SAML assertion is part of a POST message, PAS for OpenEdge rejects the request.

samlToken.httpBinding.allowMethods=GET,POST,PUT,DELETE

ACS URL Validation

The Audience restriction URL, a field in the SAML assertion that Identity Provider returns, must match the location value of the AssertionConsumerService URL in the Service Provider’s metadata file. If not, the Service Provider rejects the SAML response from the Identity Provider. This property is optional and the URL matching can be skipped. However, if you need to check ACS endpoint, set this property to true.

samlToken.webSSOProcessingFilter.checkForACSEndpointUrl={false|true}

Validity period

PAS for OpenEdge rejects a request if the SAML assertion's NotOnOrAfter timestamp has passed. However, you can set the following property to extend the duration of the assertion's validity period.

samlToken.webSSOProcessingFilter.responseSkew=<time in seconds>

Roles

If the incoming SAML assertion's attribute statements define user roles, you can set the attribute names as comma-separated values in the following property. This enables PAS for OpenEdge to populate the ROLES attribute when creating the Client-Principal object.

samlToken.UserDetails.roleAttrName=Attribute1,Attribute2

Note that PAS for OpenEdge authorizes a user to access a resource only if the role values in the SAML assertion's attributes map to roles defined for resource URLs in the oeablSecurity.csv file. By default, these roles have a ROLE_ prefix. If the incoming role values do not contain the prefix, you an use the following property to add it:

samlToken.UserDetails.rolePrefix=ROLE_

Domains

If the NameID passed in the SAML assertion is an email address (for example johndoe@hisdomain.com), PAS for OpenEdge extracts the domain name using the '@' separator and assigns it to the DOMAIN-NAME attribute of the Client-Principal object that it creates. However, if the NameID is not an email address, you can use the following property to set a default domain name:

samlToken.UserDetails.userDomain=Domain_Name

You may want to specify a domain name that has minimal access rights to your ABL application.

Note: If saml is set as the client login model, this property overrides the OEClientPrincipalFilter.domain property.

To create a sealed Client-Principal object, PAS for OpenEdge requires a domain access code that corresponds to the domain name. Typically, a CSV file is created containing a list of key-value pairs (for example, domain, domain-access-code) and then encrypted into a Java keystore file. To specify this keystore file, use the following property:

samlToken.UserDetails.registryFile=keystore_file
Note: If saml is set as the client login model, this property overrides the OEClientPrincipalFilter.registryFile property. To learn more about creating registry files, see Configuring multiple domains.