This document describes how to use the industry standard OAuth2 protocol with the Logic4 API.
Application access with OAuth2 (client credentials grant) is the de-facto method for securing APIs. In short, the client requests an access token (JWT) from an Identity Provider (IdP) and uses that token to access an API. The token has a signature that both client and server can verify and is valid for a limited period. A token contains trusted claims that provide information that both the client and the server can use.
The advantages of OAuth2 client are:
Currently, a caller of the Logic4 API must generate a token from a COMPANYKEY, PUBLICKEY, SECRETKEY, and ADMINISTRATION, supplied by Logic4. Many API functions require a secured User Id for which a UserBearer (encrypted username and password) must be supplied as well. The API verifies that both token and UserBearer are valid.
When using OAuth2, the client first requests a token (JWT, see RFC 7519) from the Logic4 Identity Provider (IdP). The UserBearer is no longer used. The token is valid for an hour and can be used for multiple requests to the API. Details of a token request are explained below (Token requests).
The IdP is a service for requesting and validating tokens. It is similar to Azure Active Directory (AAD) or IdPs of Google, AWT etc.. The Logic4 IdP supports the client credentials grant only and can only be used to get access to the Logic4 API.
Requested tokens must be reused for multiple API requests. It is not allowed to request a new token for each API request, unless the token has expired or almost expired (after one hour).
The IdP can be accessed with the following URLs:
Tip: install a Json viewer in your browser and navigate to one of these URLs.
A JWT can be requested with any language, such as C# (see below), Java, Python, or with a tool such as Postman or cUrl:
curl --location --request POST 'https://idp.logic4server.nl/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=PUBLICKEY COMPANYKEY USERNAME' \
--data-urlencode 'client_secret=SECRETKEY PASSWORD' \
--data-urlencode 'scope=api administration.ADMINISTRATION' \
--data-urlencode 'grant_type=client_credentials'
Explanation of the parameters:
client_id = PUBLICKEY, COMPANYKEY and USERNAME, separated by a space
client_secret = SECRETKEY and PASSWORD, separated by a space
scope = api administration.ADMINISTRATION where api is mandatory and ADMINISTRATION is either the name or the Id of the administration (there could be more than one)
grant_type = client_credentials (fixed)
You should have received the values of PUBLICKEY, COMPANYKEY, USERNAME, SECRETKEY, PASSWORD and ADMININISTRATION Id from Logic4. To use the ADMINISTRATION name instead of the Id, please check in de Logic4 BackOffice under 'Administrations'.
Since some parameters consist of multiple elements, encoding of spaces is necessary. A space in an element must be encoded with an underscore. An underscore in an element is encoded with two underscores. All parameters except the grant_type must be encoded. Example:
my key (unencoded) -> my_key (encoded)my_key (unencoded) -> my__key (encoded)In code, this is easily accomplished with (C#):
encoded = unencoded.Replace("_", "__").Replace(" ", "_");
Once you have a token you can paste it into https://jwt.ms or https://jwt.io and inspect all claims.
The resulting JWT contains claims that are secured by a digital signature. Some of the claims are mandatory as defined in the client credential grant specification RFC 7519. The Logic4 IdP returns JWTs containing the following claims, some of which are not of interest for clients:
https://api.logic4.nlUnless a client wants to use one or more of the claims, the JWT does not need to be parsed. For extra security, clients may validate the JWT with the IdP. How to do this is out of the scope of this documentation. Microsoft provides easy to use libraries for .NET for validating JWTs. For educational purposes, you can paste a JWT into https://jwt.ms or https://jwt.io and inspect all claims.