PAS for OpenEdge support for OAuth2 allows your ABL business application or data service to act as a resource server that accepts either a OAuth2 self-contained access token (in JWT format) or a simple JWT token. The support for JWT and OAuth2 self-contained access tokens relies on having access to the user's identity information in order to generate a CLIENT-PRINCIPAL object that is usable in your ABL business application for setting the user of an OpenEdge database connection (and therefore tenancy and audit trail). Only those two types of tokens contain sufficient identity information to create a CLIENT-PRINCIPAL object.

Note: The OAuth2 random access token type is not supported because OpenEdge does not embed or interoperate with an external authorization server that is capable of sharing an OAuth2 self-contained access token with PAS for OpenEdge

Main steps for the HTTP request process

As an OAuth2 resource server, PAS for OpenEdge does the following on each HTTP request:

  1. Obtains the authorization header's bearer token
  2. Validates the bearer token type as either a JWT or OAuth2 self-contained access token (also known as a form of JWT)
  3. Validates the JWT's signature using the JWT header's algorithm type and the PAS for OpenEdge configured encryption key
  4. Validates the JWT's required payload claims
  5. If the bearer token type is a JWT or OAuth2 self-contained access token, validates the required payload claims
  6. Authorizes the token's user to the PAS for OpenEdge data services using the granted JWT scope claim
  7. Creates an equivalent OpenEdge CLIENT-PRINCIPAL object that is delivered to the ABL business application with each request

PAS for OpenEdge support for OAuth2 is supplied by Spring Security. PAS for OpenEdge extends the core Spring Security OAuth2 project implementation to blend it into the same customer ABL application environment as it does for all other Spring Security authentication and URL data authorization services. That OpenEdge integration includes the formatting of error responses and the creation of CLIENT-PRINCIPAL objects that are passed to the ABL business application.

The OAuth2 and JWT standards offer implementation vendors many design and run-time use-cases that result in many configuration properties. The oeableSecurity.properties file found in the OEABL web application's WEB-INF/ directory contains a common subset of those properties and gives you the ability to configure each OEABL web application independently. The full set of configuration properties is found in the PAS for OpenEdge instance's conf/oeablSecurity.properties file, which compose the default values if they are not found in the OEABL web application's configuration. OpenEdge provides many default property values that do not require changing. However, not all properties can contain useful values and must be configured for each installation.

PAS for OpenEdge supports most OAuth2- or JWT-compliant authentication and authorization services. However, there are limitations. An OAuth2 access token or JWT must meet the following criteria to be usable by the OAuth2 support in PAS for OpenEdge:

  1. The access token, or JWT, must be received in an authorization HTTP header with the authorization-scheme set to to bearer.
  2. The token must contain a user identity (sub) claim to populate the CLIENT-PRINCIPAL User-ID field.
  3. The token must contain a scope (scope) claim that can be used by Spring Security to authorize access to the application URLs.
  4. The token must contain a resource ID claim that corresponds to a resource ID that is configured in the OEABL web application's security.
  5. An OAuth2 access token must contain a client ID claim (client_id) that indicates that it was issued to a client type that the OEABL web application is configured to support.
  6. The token's signature algorithm must be one of the JWS, HMAC, or RSA types.
  7. The encryption key to validate the token's signature field must be available from the issuer of the token and configured.
  8. If the token issuer adds an expiration claim (exp), then the token must pass the date-time expiration test.

The following topics provide details about configuring PAS for OpenEdge's OAuth2 support:

Note: Do not proceed without first understanding basic OAuth2, JWT, and OpenEdge CLIENT-PRINCIPAL terms and functionality, as explained in the following topics: