Generic API Integration

Zilla includes a powerful module that can connect to any system that has API endpoints for accounts and permissions. This capability can be leveraged for both internal applications as well as SaaS applications.

Below are the steps to enable generic integration for applications with the configuration details.

1. Login to Zilla as admin.

2. Click Add application in the top right corner.

   

3. On the Add Application page search for the application you want to add to Zilla and click Add to Applications if found. Otherwise, add a custom application by going to the Custom Application tab.

   

Add details for the custom application and click Add to Applications.

4. You will be redirected to the application details page.

5. Click the Gear icon in the top right to the left of Sync now.

6. You will see the configuration dialogue, click Show Alternate Configuration Options.

7. Enable API Integration, you will see configuration entries to be filled in.

8. Enter the configuration based on the details given below:

• Frequency: to schedule integration. See Scheduling an automated sync for more details.

• Base URL: Base URL for an application API which we can be found in the developer documentation for the application. Example: For AHA it would be https://{org domain}/api/v1/.

• Authorization Header Name 1: Name of the header used to pass the token or API key. Many times this is Authorization. Example: For AHA it would be Authorization. If not required, leave blank.

• Authorization Header Value 1: The value for the authorization could be API key (Normal or base64 encoded) and the prefix for the API key could be Bearer or Basic followed by space and then API key. Example: For AHA the API key is a normal key with Bearer as a prefix so the header value will be Bearer APIkey. If not required, leave blank.

• Authorization Header Name 2: Name of the second header. If not required, leave blank.

• Authorization Header Value 2: The value for the second header. If not required, leave blank.

• Pagination strategy: Currently Zilla only supports limit-offset pagination for generic integration so the value must be limit-offset.

• Pagination Overrides: ({"limit": "limit", "offset": "skip"}).: The mapping of the pagination fields from the API response. For example: If the API has pagination support: limit=50&skip=0 then override would be {"limit": "limit", "offset": "skip"}.

• Accounts Endpoint: The endpoint for listing all the users or accounts for an application. Example: For AHA it is users.

• Accounts Response Property: The key value for the users' array IF the response from the API call contains JSON and the users' array is inside a field. Example: For AHA the JSON response of type has users inside users field so the value for this config would be .users. If not required, leave blank.

  {
    pagelen: number,
    size: number
    users: [
            {user1 object},
            {user1 object}
           ]
  }

• Accounts Property Overrides: The mapping for the response from the API to Zilla fields. Example: For AHA we get the following response for a single user:

  {
    userId: string,
    name: string,
    firstname: string,
    lastname: string,
    enabled: boolean,
    roles: string[],
    email: string,
    lastLoggedIn: Date,
    EID: string
    .
    .
    .
    so on
  }

So the mapping would be:

{
  "id": "userId",
  "username": "name",
  "firstName": "firstname",
  "lastName": "lastname",
  "status": "enabled",
  "email": "email",
  "roles": "roles",
  "lastLogin": "lastLoggedIn",
  "employeeId": "EID"
}

The left field denotes the Zilla fields and the right one denotes the fields from the API response.

• Required Fields

The following fields are required in the API Integration:

id: a unique identifier value assigned to an account. Example = 1234

username: a unique display name assigned to an account. Example = jsmith

email: a unique email addressed assigned to an account. Example = jsmith@yourcompany.com

status: a value that indicates if an account is Active or Inactive. Example = ‘Active’, ‘Inactive’, ‘Enabled’, ‘Disabled’

roles: the permissions associated with an account. Example = ‘Admin’, ‘Default’, ‘Standard’

• Account Active Statuses: The status (active or inactive status) response from the API. Value could be true, enabled, active, provisioned, etc. Examples: For AHA we get true as active status so the value for this config would be true and for Okta, we get PROVISIONED so the value for this config would be PROVISIONED. Values should be comma separated in case of multiple values.

Below configuration are for OAuth based generic application:

• Authorization URL: The endpoint for the authorization server, used to get the authorization code. Example: For Okta it is https://{orgdomain}/oauth2/v1/authorize. If you are going for Authorization code based OAuth generic application then you have to specify the authorization URL. Otherwise if your are going for Client Credential Based OAuth in that we can leave it blank.

• Token URL: The endpoint for the authentication server. This is used to exchange the authorization code for an access token. Example: For Okta it is https://{orgdomain}/oauth2/v1/token.

• Client Id: The client Id issued to the client during the application registration process.

• Client Secret: The client secret issued to the client during the application registration process.

• Space separated scopes: The scope of the access request. It may have multiple space-delimited values.

9. Click Next/Sync now to start the sync.

Please contact Support@zillasecurity.com for assistance.