Connectors

For custom or internal apps, your organization can build an API connector in order to allow Opal to manage access to the app.

To learn how this works, read on!

Architecture Overview

Opal side

• Opal server - The opal server will respond to user-initiated requests from the web or Slack interface to add or remove users from resources. These will be propagated to your custom app via signed requests to the API connector.
• Opal consistency checker - On a periodic interval Opal will run a consistency checker to retrieve the up to date user lists of your resources in the custom app via signed requests to the API connector.

Your company

• API connector - This is the interface that enables the integration. This connector should expose the set of API endpoints outlined in the API spec section of this document
• Custom app - The custom app that you want to integrate against

How to build the API connector

In order to support the use cases outlined above, an API connector web service needs to be build that exposes the following endpoints:

• List all users: GET /users
  • This endpoint is important because it tells Opal how to match users in resources and groups with the users in Opal.
• List resources: GET /resources
  • List all the resources in the remote, paginated.
• Get resource: GET /resources/{resource_id}
  • Get details about a specific resource by the resource ID provided by the connector.
• Get resource access levels: GET /resources/{resource_id}/access_levels
  • Get all the available access levels for a resource given its ID.
• List users of a resource: GET /resources/{resource_id}/users
  • List all the users that have access to a resource and their access levels.
• Add user to resource: POST /resources/{resource_id}/users
• Remove user from resource: DELETE /resources/{resource_id}/users/{user_id}
• List groups: GET /groups
  • List all the resources in the remote, paginated.
• Get group: GET /groups/{group_id}
  • Get details about a specific group by the group ID provided by the connector.
• List users of a group: GET /groups/{group_id}/users
  • List all the users that have access to a resource
• Add user to group: POST /groups/{group_id}/users
• Remove user from group: DELETE /groups/{group_id}/users/{user_id}
• List resources belonging to a group: GET /groups/{group_id}/resources
• Add resource to a group: POST /groups/{group_id}/resources
• Remove resource from a group: POST /groups/{group_id}/resources/{resource_id}
• Status: GET /status
  • This endpoint is mainly used while setting up the connection in Opal and used as test to validate that the header signature is valid. Refer to API Spec for all the details.

The API Spec below will go into more detail of how each one of these API endpoints will work.