Skip to content

You are viewing documentation for Immuta version 2022.5.

For the latest version, view our documentation for Immuta SaaS or the latest self-hosted version.

cancel

External User Info Endpoint

Audience: Application Admins

Content Summary: Immuta can consume user attributes from an external HTTP endpoint in an out-of-band fashion. This feature allows you to retrieve users' groups and authorizations from an additional resource, alongside the user attributes retrieved in the authentication flow. Such an external endpoint can be configured on any of the Identity Provider types that Immuta supports.

Implement the HTTP Service

The following section instructs how to implement the HTTP service.

Specifications

Authentication

The service can authenticate requests with both or either of the following methods:

  1. Basic username and password Authorization header
  2. SSL cert validation

For more information, please refer to Configuring an External User Info Endpoint.

Note: Immuta will expect non 200 error codes when the user info cannot be retrieved.

GET /user-info

The user info endpoint will be called each time Immuta needs to synchronize with a remote IAM on user groups and authorizations. Immuta will query the endpoint with the user ID specified in request's query.

Note: The endpoint's path does not necessarily have to be /user-info.

Parameters
Name Located in Description Required Schema
userid query The unique user identifier (username in Immuta) Yes string
Responses
Code Description
200 successful operation - user info retrieved successfully
Response Schema
Name Example
groups [{"name": "<group_name>"}]
authorizations {"<authorization_name>": ["<value>"]}

Below is an example value that could be returned by the endpoint:

{
  "groups": [{
    "name":  "Accountants",
  }, {
    "name":  "Controllers",
  }],
  "authorizations": {
    "EMEA": ["Sales", "Expenses"],
    "APAC": ["Sales"]
  }
}

Configure an External User Info Endpoint

  1. Click the App Settings icon in the left sidebar.

  2. If you are modifying an existing IAM, click the name of the IAM. If you are creating a new IAM, click Add IAM.

    Create or edit IAM

  3. At the very bottom of the IAM section, check the External Groups and Authorizations Endpoint checkbox.

  4. In the External User Info URI field, enter the full path to your customer HTTP endpoint.
  5. Optionally, check the Use Authentication checkbox and provide the username and password with which Immuta should authenticate when querying the user info endpoint. Immuta will subsequently send requests to the service with a Basic authorization header.
  6. Optionally, enable SSL by checking the Enable SSL checkbox.
  7. Optionally, if SSL is enabled, check the Require SSL Request Cert if your service requires SSL certificate validation. This step will require that you upload three files:
  8. The SSL key file (*.pem)
  9. The SSL cert file (*.pem)
  10. The SSL CA file (*.pem)

Configure external endpoint