PAS for OpenEdge's support for OAuth2 allows your ABL business application/data service to act as a Resource Server that accepts either a OAuth2 Self-contained Access Tokens (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-Princpal that is usable in your ABL business application to set an OpenEdge database connection's user ( and therefore tenancy and audit trail ). Only those two types of tokens contain sufficient identity information to create a Client-Principal.
Note: The OAuth2 Random Access Token type is not supported because OpenEdge does not embed or interface with an external Authorization Server that is capable of sharing an OAuth2 Self-contained Access Token with PAS for OpenEdge
As an OAuth2 Resource Server PAS for OpenEdge will execute this process on each HTTP request:
1. Obtain the Authorization header's Bearer token
2. Validate the Bearer token type as either a JWT or OAuth2 Self-contained Access Token ( aka a form of JWT )
3. Validate the JWT's signature using the JWT header's algorithm type and the PAS for OpenEdge configured encryption key
4. Validate the JWT's required payload claims
5. If the Bearer token type is a JWT or OAuth2 Self-contained Access Token, validate its required payload claims
6. Authorize the token's user to the PAS for OpenEdge data services using the granted JWT scope claim
7. Create an equivalent OpenEdge Client-Principal that will be delivered to the ABL business application with each request
PAS for OpenEdge’s OAuth2 support 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-Principals 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 provide 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 and are the default values if they are not found in the oeabl web application's configuration. OpenEdge provides may default property values that will not require changing, however not all properties can contain a useful value and must be configured for each installation.
PAS for OpenEdge will support most OAuth2 or JWT compliant authentication/authorization services. However, there are limitations. An OAuth2 Access Token/JWT must meet this criteria to be usable by PAS for OpenEdge's OAuth2 support:
1. The Access Token/JWT must be received in an Authorization HTTP header with the authorization-scheme equal 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 (aud) claim that indicates that it may be used by the only those oeabl web application whose resource identity is configured to be of that type
5. An OAuth2 Access Token must contain a client id claim (client_id) that indicates it was issued to a Client type the oeabl web application is configured to support
6. The Access Token/JWT must be received in an Authorization HTTP header with the authorization-scheme equal to "Bearer"
7. The token's signature algorithm must be one of the JWS HMAC or RSA types
8. The encryption key to validate the token's signature field must be available from the issuer of the token and configured
9. If the token issuer adds an expiration claim (exp) then the token must pass the date-time expiration test
The following sections will provide details for configuring a PAS for OpenEdge's OAuth2 support, and is divided into distinct parts:
1. Where to find the configuration files and properties
2. Enabling PAS for OpenEdge's JWT/OAuth2 support
3. Configuring a PAS for OpenEdge Resource Server
4. Configuring JWT Token validation
5. Configuring OAuth2 Token validation
6. Configuring JWT to Client-Principal conversions
Note: Do not proceed without first understanding basic OAuth2, JWT, and OpenEdge Client-Principal terms and functionality.
