LWS Authentication Exits

This is preview documentation and is subject to change.

The LightWave Server Authentication Exits feature allows customers to verify custom authentication tokens retrieved from the HTTP headers or queryParams in a REST request. AuthExits are performed if an AuthExit Rule is defined in an Access Control Policy assigned to the Service associated with the REST request.

• The AuthExit rule’s properties are configured much like other Access Control Policy rules, on the Console Access Control page. An AuthExit rule can be added to a new or an existing ACP.

• A Service is configured to use a new or existing ACP that has an AuthExit rule.

• The SERVER/SWORKER process uses the Token Set Configuration defined by the AuthExit Rule to retrieve information about a single named or unnamed token set. A token set is one or more tokens to be used to verify each RESET request. A named token set has a customer provided name.

• The SERVER/SWORKER process manages retrieving token set information, verifying REST request content using the token set information, caching the token set information and verified tokens, and fetching new token set information when the cached token set information expires. When cached verified tokens expire, the tokens from the next REST request are used in a new verification request and, if verified, cached.

• Any token that can be supplied as an HTTP header or query param, such as OAuth bearer tokens and JSON Web Tokens (JWT), may be in a token set.

How it Works

When the SERVER/SWORKER process receives a REST request, if cached token set information is available. If not, SERVER/SWORKER queues the request and sends a token set information request to the customer’s token server to get new token set information.

• If an error occurs retrieving the token set information, the SERVER/SWORKER process will retry the request up to the limit defined in the AuthExit rule.

• If the token set information is retrieved successfully, the information will be used to retrieve token values from headers and/or queryParams in the REST request. Token vales retrieved from the request are optionally reformatted and base64 decoded before being added to the token verification request.

• For example, a header or queryParam value could be the string “Bearer dGhpcyBpcyB0aGUgdG9rZW4=”. The token set info could specify a format string of “Bearer %s” to extract the actual token from the string, and then optionally base64 decode the string “dGhpcyBpcyB0aGUgdG9rZW4=” to 32 bytes of binary data. The resulting data is copied to the token verification request.

• After retrieving token values, as defined by the token set information, from the REST request, and cached verified token values are not available, the SERVER/SWORKER process sends a token verification request to the customer’s token server. If cached verified token values are available, the SERVER/SWORKER process compares the verified values in cache with the request’s token values.

• If tokens are verified, the REST request is processed as normally. If the token values are not verified, then the REST request is denied.

Components

• REST client: requests services.

• LWS: An instance of LightWave Server with the Auth Exits feature enabled.

• Token serverclass: A Pathway serverclass that implements the auth exit server.

• Token Verifier: The entity that verifies the tokens extracted from the request by LWS.

• Application: The backend application providing the service.

Note: The Token serverclass & Token Verifier could be the same entity or a hybrid of serverclass and 3rd party authentication services.

Process Flow

1. A LWS REST API request is sent to LWS by a REST client. The request may contain one or more token values that must be verified before being sent to the Application.

2. LWS checks its token cache to determine if the token(s) are present for the request. If so, LWS moves on to step 6. Otherwise, it sends a Token Info IPM to the Token serverclass.

3. A Token Info request is sent to the Token serverclass when LWS must retrieve information about one or more tokens that could be present in a request.

4. The Token Info response returned by the Token Verifier contains the information required for LWS to extract the tokens from the request.

5. LWS uses the information in the Token Info response IPM to extract the tokens from the message in preparation for token verification.

6. LWS sends a Token Verify IPM to the Token serverclass containing the extracted tokens.

7. The Token Verify request is sent to the Token Verifier.

8. The Token Verifier returns the results of the verification in a Token Verify response.

9. LWS receives the Token Verify response IPM from the Token serverclass. If the response contains an error, a denial is returned to the REST Client.

10. If tokens are verified, LWS sends the Service request IPM to the Application.

11. The Application returns the Service response IPM to LWS.

12. The LWS REST API response is returned to the REST Client.

Error Handling

When the SERVER/SWORKER process encounters an error, either when communicating with the token server, or an error is returned by the token server itself, it will retry the request using the retry interval and max count supplied in the AuthExit rule of the Service’s ACP. If the error condition persists, the error will be logged, and the REST request will be denied with HTTP status 403.