Jeff Murray’s Programming Shop, Inc.

Last Updated: 11/09/2023

 

CAREWare now provides support for OAuth2 Backend connections as a secure way for third-party applications to make AJAX API calls on behalf of one or more users. This guide will provide assistance in setting up these backend applications for OAuth2 authentication.

If you are a developer new to the CAREWare API, we recommend you download the VB.NET solution with the source for the latest version of the CAREWare API Client (found here).

OAuth2 JWT Backend Connection Overview

CareWare OAuth2 Backend Connections use JSON Web Tokens (JWTs) to authenticate user sessions. This process is done by verifying the JWT’s signature, which should be encrypted by an RSA algorithm. This signature is checked by the business tier and is decrypted with a corresponding RSA public key. After a token is validated, an access token will be provided as long as the user and domain are valid. This differs from the CW API login method for which a password is needed in order to authenticate a user.

Accessing OAuth2 Backend Apps

OAuth2 Backend Apps can be accessed by Central level users from Administrative Options —> Advanced Security Options → OAuth2 Backend Apps

Enabling Keystore Encryption

Public Keys are essential for OAuth2’s authentication process. In order to protect this information, we recommend enabling Keystore Encryption, which allows a CAREWare server to use a secure password to encrypt private information. This information can only be decrypted using the password from the same CAREWare server. Enabling Keystore Encryption can be done in Administrative Options —> Advanced Security Options → Advanced Encryption Options → Keystore Encryption Mode.

Enabling Keystore Encryption will create a JSON file containing the encrypted password.

 

By default, this will be stored inside the installed directory of CAREWare’s business tier. This can be changed in the common storage setting: EZDPAPIFolder.

 

Adding OAuth2 Backend Applications

Adding OAuth2 Backend applications can be done by clicking on OAuth2 Backend Apps

→ Add

 

The Following Fields are present while configuring an OAuth 2 Application config:

 

 

Application Name: The name to be given to the application used for OAuth2 backend
support
Client ID: A randomly assigned GUID to be used when authenticating the client for
OAuth 2
RSA Public Key: The attached public key to be used for authentication for the OAuth2
Application. Once public key has been attached, the first two lines of the key will be
displayed.
OAuth Token/Auth Url: The url to be used when requesting the token and for
authentication

 

 

Date Created: Date and time of the created CAREWare OAuth2 Application

Public Key Last Updated: Date and time of the last update to the application’s public key

Last Used: Date and time of when the application was last used

Attaching an RSA Public Key

An RSA public key must be attached to every OAuth2 Application for it to be properly authenticated. Attaching a public key can be done in the OAuth2 backend application screen.

Setting up CIDR IP Rules

CIDR Internet rules allows network administrators to limit the range of IP addresses that can access any OAuth2 Backend Connection. A CIDR rule is required before using any OAuth2 Connection. Adding a CIDR IP rule can be done through the OAuth2 Applications Screen.

To allow any ipv4 range, configure the rule as shown below.

Allowing OAuth2 Backend User Authentication

In order for specific users to be authenticated through an OAuth2 Backend Connection, they must have the following permission: Allow OAuth2 Backend Connection. This is a provider level permission that can be found at Administrative Options → Provider User Manager → Manage Active Users → Manage Permissions.

Using the OAuth2 Backend Connection with the CW API

 

Once a public key has been attached to the Oauth2 application in CAREWare, the CW API can be used. Using the provided Client ID and the Oauth Token/Auth URL, we can plug these values in a Dictionary(Of String,JSONValue).

 

Each parameter is required and described below: pfxPass: The password of the provided PFX File pfxPath: Full Directory Path of PFX File

sub: Username or email address of the user attempting to login

iss: The provided ClientID of the Oauth2 application. This is found inside of CAREWare
Oauth2 applications.

aud: The provided Oauth2 auth url. This is found inside of CAREWare Oauth2

applications

domain: Name of domain to be accessed. User must belong to the domain in order to successfully authenticate.

tokenURL: The provided Oauth2 token url. This is found inside of CAREWare Oauth2 applications.

Once the parameter file has been created and set up, this can be used to create an Oauth2Client.

This Oauth2Client can be passed into a new CwApiSession and finally be used to make CW API calls.