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.

Login to Zilla as admin.
Click Add application in the top right corner.
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.

Note: Name of the application can never be Generic, GenericOauth, generic, or generic oauth.

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.

Note: Applications like Google workspace, GCP, Gitlab can not be scheduled as the user has to give consent for these applications each time.

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.

Note: If the Zilla fields and the fields from the API response are the same then this configuration property can be left blank.

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.
Authorization Url: The endpoint for the authorization server, used to get the authorization code. Example: For Okta it is https://{orgdomain}/oauth2/v1/authorize.
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.

Notes:

It is recommended to refer to developer documentation before doing generic sync.
Authorization Url, Token Url, Client Id, Client Secret, and Space separated scopes are optional if the user syncs without oauth. Then the header name and value could be added which are also optional if the API does not support authentication.

Please contact Support@zillasecurity.com for assistance.