External User Info Endpoint

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 Configure 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.

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:

   • The SSL key file (*.pem)

   • The SSL cert file (*.pem)

   • The SSL CA file (*.pem)