API Gateway is the middle layer between external Systems and Evolve application. It manages security of exposed APIs to be accessed by third party systems. For example, a third party system can start a Form Process by calling the Process extension API. To make this call successfully, third party system must fulfill security requirements of API Gateway.
API Gateway Security Details
API Gateway provides options to register a third-party client in the application. A new client can be registered from Administration site by navigating through Settings → Authentication → Third Party Clients → Register Client. API gateway supports three security options Client Secret, Secure Token and Certificate.
Winshuttle recommends Secure Token security option as preferred option to be used by third party system.
Client Secret
This is the http header security option. In order to register a new Client, user has to click on Register Client, provide a Client Name and select Client Secret from the Security type drop down. On registering a new client, application generates a Client ID and a Secret Code. To copy the Secret Code select any client and then click on View → Show Secret. Third party applications must send the registered Client ID and the Secret Code in HTTP Request header as follows:
-
Request header Name: ”c1” should have valid registered Client ID.
-
Request header Name : ”ck” should have secret code.
Secure Token
This is the JWT token security option. In order to register a new Client, user has to click on Register Client, provide a Client Name and select SecureToken from the Security type drop down. On registering a new client, application generates a Client ID and a Secret Code. To copy the Secret Code select a client and then click on View → Show Secret . Third party client should create a JWT token and also sign it with the secret code. This signed JWT token must be sent in API request. API must have below request headers:
-
Request header: Name: ”c1” should have valid registered Client ID
-
Request header: Name : ”ck” should have JWT Token.
The JWT token should have below details :
-
Token must have a claim ClientID and it should have registered Client ID (the Client ID that is shown while registering client). It should be same as the value in request header “c1”.
-
Token must have a claim ClientName and it should have registered Client Name (the Client Name that is provided while registering client).
-
Token’s default expiry time should not be more than 5 minutes from token issue time. If user wants to extend this time a key can be added to System → Infrastructure → Advance Settings with Category: System, Config key:ExtAPITokenExpiryMinutes and Value should be time in minutes.
Certificate
This is the certificate based security where both Third party application and Evolve Server share a certificate and this certificate is used to authenticate the call. This is also called mutual certificate authentication and is only supported when Evolve is setup on HTTPS. In order to register a new Client, user has to click on Register Client, provide a Client Name and select Certificate from the Security type drop down. On registering a new client, application generates a Client ID. The generated Client ID along with the client certificate is used to make API call. Evolve application should be configured to enable Certificate based authentication as per below details:
-
Need a Root CA certificate and Client certificates. Client certificates should be issued by Root CA certificate.
-
Install Root certificate in Trusted Root Certification Authorities location on Local machine of Evolve server.
-
Install Client certificate on client machine and send this client certificate while making call to process extension API.
User can check/uncheck the Validate the client machine name, if checked then client certificate name should be same as client's machine name.
To resolve an error "RequestEntityTooLarge" with External API while launching with Certificate Authentication:
-
Select the site under Default Web Site.
-
Select Configuration Editor.
-
Within Section drop-down, select "system.webServer/serverRuntime".
-
Enter a higher value for "uploadReadAheadSize" such as 1048576 bytes. Default is 49152 bytes.