# PxPlus Web Services

OAuth2 Clients Object |

## Usage

The OAuth2 clients object can be used to maintain OAuth2 clients programmatically and without the need for a user interface. The OAuth2 clients object can also be used to add OAuth2 security to any Web service built with PxPlus.

It is possible to implement your own OAuth2 access token server using the OAuth2 clients object if the one provided with PxPlus (/services/oauth2/token.pxp) does not meet an application's requirements. See Methods.

#### Important Note:
You must first set up Security Classifications and at least an ADMIN User prior to setting up OAuth2 clients.

(The OAuth2 Clients object was added in PxPlus 2021.)

Instantiating the OAuth2 Clients Object

To instantiate the OAuth2 clients object using the handle oauth2_clients (where oauth2_clients can be any numeric variable), enter the following command:

> oauth2_clients=new("*web/services/oauth2/clients", adminUsername$, adminPassword$)

The adminUsername$ and adminPassword$ arguments are optional and are only needed if you are using the DeleteClient, SaveClient and SaveNewClient$ methods so that the object can create/modify users.

To access any of the available methods, the OAuth2 clients object handle oauth2_clients is used, followed by an ' (apostrophe) and the method (with the desired parameters).

Examples:

NewClient$=oauth2_clients'SaveNewClient$(newClientName$,securityClass$)

if oauth2_clients'DeleteClient(oldClientName$)=0 \
then msgbox "Failed to delete client: "+oldClientName$

## Methods

The interface supports the following methods:

Method | Description
DeleteClient(clientName$) | Deletes the client with the given client name from the OAuth2 clients file and deletes associated OAuth2 client user. Returns 1 on success; otherwise, returns 0.
GetClient$(clientName$) | Given a client name, returns the client authorization information as a SEP delimited string. The following fields are returned in this order: Client ID Client Secret Access Token Key Security Class Returns an empty string if there was an error.
ListClients$( ) | Returns a list of all client names as a SEP delimited string. Returns an empty string if there was an error.
NewAccessToken$(clientId$, clientSecret$, expiry) | Generates a new OAuth2 access token with the given expiry for the client if the client ID and client secret are valid. Returns the new access token if successful; otherwise, returns an empty string.
NewClientSecret$( ) | Generates and returns a new client secret.
NewClientTokens$( ) | Generates new client tokens (client ID, client secret and access token key) and returns as a SEP delimited string. The following fields are returned in this order: Client ID Client Secret Access Token Key
SaveClient(clientName$, clientId$, clientSecret$, accessTokenKey$, securityClass$) | Saves client to the OAuth2 clients file and saves associated OAuth2 client user. Returns 1 on success; otherwise, returns 0.
SaveNewClient$(clientName$, securityClass$) | Saves a new client to the OAuth2 clients file and adds OAuth2 client user. Returns the new client authorization information as a SEP delimited string. The following fields are returned in this order: Client ID Client Secret Access Token Key Returns an empty string if there was an error.
ValidateAccessToken$(accessToken$) | Validates that the access token is a well-formed access token and is not expired. Then, logon using associated OAuth2 client user to allow access to secured resources. Returns the security class that the access token has been granted access for as a string if access token validated. Returns an empty string if the access token is not valid or there was an error.

## Example

Create a New OAuth2 Client:

> oauth2_clients=new("*web/services/oauth2/clients",adminUsername$,adminPassword$)
> read data from oauth2_clients'SaveNewClient$("ABC Shipping", "USER") to client_Id$,client_Secret$,access_Token_Key$

Revoke Access to Compromised Client by Changing Client Secret:

> oauth2_clients=new("*web/services/oauth2/clients",adminUsername$,adminPassword$)
> read data from oauth2_clients'GetClient$("ABC Shipping") to client_Id$,client_Secret$,access_Token_Key$,security_Class$
> oauth2_clients'SaveClient("ABC Shipping", client_Id$, oauth2_clients'NewClientSecret$() ,access_Token_Key$,security_Class$)

Add OAuth2 Security to PxPlus-built Web Service:

> !
> ! Allow access to secure query via OAuth2 authentication passed in the HTTP header as an authorization: bearer token
> if len(%http_authorization$)>=7 and lcs(mid(%http_authorization$,1,7))="bearer " \
> {
> !
> ! Parse BASE64 bearer token and convert it to get the access token
> base64AccessToken$=stp(mid(%http_authorization$,8,err=Return_auth_err),"B")
> accessToken$=cvs(base64AccessToken$,"BASE64URL:ASCII",0)
> !
> ! Validate the access token using the OAuth2 clients object, this will also do a logon as the client to allow access to secure resource
> oauth2clients=new("*web/services/oauth2/clients",err=Return_auth_err)
> if oauth2clients'ValidateAccessToken$(accessToken$)="" \
> then gotoReturn_auth_err
> drop object oauth2clients,err=*next
> }