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.

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 :

1. 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”.

2. Token must have a claim ClientName and it should have registered Client Name (the Client Name that is provided while registering client).

3. 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:

1. Select the site under Default Web Site.

2. Select Configuration Editor.

3. Within Section drop-down, select "system.webServer/serverRuntime".

4. Enter a higher value for "uploadReadAheadSize" such as 1048576 bytes. Default is 49152 bytes.

Application APIs secured with API Gateway

Digital Access API: Digital Access API allows third party systems to integrate with Evolve workflow system. These APIs are secured by application API Gateway. See Digital Access APIs for more details.

SAP Data API: SAP Data API allows to upload and download data from SAP. This API is secured by application API Gateway. See SAP Data API for more details.

The below APIs are secured with API Gateway and its supported authentication mechanism.

For three security options under API Gateway, there are following route prefixes that need be used to hit the API:

Client Secret : “<Evolve URL>/svr”

Secure Token : “<Evolve URL>/svr”

Certificate : “<Evolve URL>/svrc”