Enhanced HTTP Security for PB2017R3 – OAuth 2.0

PowerBuilder 2017 R2, released in January 2018, added TLS 1.2 support in the new HTTP Client and RESTful Client components. Both objects have a property named SecureProtocol that can be set to a value of five (5) to ensure only TLS 1.2 protocol is utilized. TLS 1.2 takes advantage of the use of the higher SHA-256 encryption standard and the client and server’s ability to specify the accepted hash and signature algorithms. TLS 1.2 also supports authenticated encryption, TLS extensions, and AES cipher suites.

PowerBuilder 2017 R3, released in July 2018, upgrades PowerBuilder to support the new OAuth 2.0 specification – often just commonly referred to as OAuth2. With the inclusion of OAuth2 features, application developers and their resulting applications can take advantage of the security features of OAuth2.  Before the average developer utilizes the new OAuth2 features of PowerBuilder, it helps if you understand the concepts behind the OAuth2 implementation.

OAuth2 is an authorization framework that enables applications to obtain limited access to user accounts on an HTTP service.  Many popular third-party HTTP services use OAuth2, such as GitHub, Google, Facebook, etc. – just to name a few.  OAuth2 works by delegating user authentication to the service that hosts the user account and authorizing third-party applications to access that user account. The OAuth2 system provides authorization flows for web, mobile and desktop applications. It does this by using four OAuth2 roles, which are: Resource Owner, Client, Resource Server and Authorization Server. The OAuth2 framework defines these roles as:

• Resource Owner is the user who authorizes an application to access their account.
• Resource Server is the server hosting protected data (for example Google hosting your profile and personal information).
• Client is any application requesting access to a resource server. Before it may do so though, it must be authorized by the user, and the authorization must be validated.
• Authorization Server is a server issuing access token to the client. This token will be used for the client to request the resource server. This server can be the same as the authorization server (same physical server and same application) as this is often the case.

High Level Flow

Here is a more detailed explanation of the steps in the diagram above:

1. The application requests authorization to access service resources from the user.
2. If the user authorized the request, the application receives an authorization grant.
3. The application requests an access token from the authorization server (API) by presenting authentication of its own identity and the authorization grant.
4. If the application identity is authenticated and the authorization grant is valid, the authorization server (API) issues an access token to the application and the authorization phase is complete.
5. The application then requests the resource from the resource server (API) and presents the access token for authentication.
6. If the access token is valid, the resource server (API) serves the resource to the application. 

Before using OAuth2 with your application, you must register your application with the service. This is done through a registration form via a developer "API" portion to the service's website, where you will provide the following information (and details about your application): Application Name, Application Website, Redirect URI (or Callback URL).

Once your application is registered, the service will issue "client credentials" in the form of a client identifier and a client secret. The Client ID is a publicly exposed string that is used by the service API to identify the application and is also used to build an Authorization URL(s) that are presented to users. The Client Secret is used to authenticate the identity of the application to the service API when the application requests to access a user's account, which must be kept private between the application and the API.

In the high-level OAuth2 flow presented above, the first four steps cover obtaining an authorization grant and access token. The authorization grant type depends on the method used by the application to request authorization, and the grant types that are supported by the OAuth2 API. The four grant types are: Authorization Code (server-side Apps), Implicit (Mobile or Web Apps), Resource Owner Password Credentials (trusted Apps), and Client Credentials (App API access). The authorization code grant type is the most commonly used because it is optimized for server-side applications, where the source code is not publicly exposed, and thus the Client Secret confidentiality can be maintained.

In PB2017 Revision #3, Appeon has added the following five (5) objects to the PowerBuilder System Class that support the oAuth2 architecture framework as described above, as follows:

• TokenRequest object that can get or set the properties for the access token request, including the address of the authorization server, the OAuth 2.0 authorization process, the scope of the access request, the secure protocol, the timeout value, etc.
• TokenResponse object that can get the information of the access token response returned by the authorization server, including the access token, the refresh token, the HTTP response header etc.
• OAuthClient object that provides interfaces for obtaining the access token and protected resources.
• OAuthRequest object that uses the access token to obtain each property of the HTTP request of the protected resource, including the server address, the request header, the secure protocol, the timeout value etc.
• ResourceResponse object that can obtain the response information of the protected resource request, including the HTTP response headers and the protected resource returned from the server.

With these new PowerBuilder entities, the PowerBuilder developer is ready to use the new oAuth2 framework with either the existing HTTPClient or RESTClient object classes that were added in the PB2017 Revision #2 release. Also note that oAut2 feature will also be available in the new “C# Web API” RESTful web service feature coming soon in the PB2018 release, so that you can use oAtuth2 when building your RESTful web services.