Skip to main content

Illumio REST APIs 25.4

LDAP Authentication

This Public Experimental API provides user authentication with the PCE using LDAP with OpenLDAP and Active Directory.

LDAP authentication comes in addition to the two previously available methods:

  • API keys provide persistent authentication

  • Session credentials provide temporary authentication.

Prerequisites and Limitations

Before configuring LDAP for authentication with the PCE, it is important to provide the required prerequisites and review any limitations.

Determine Your User Base DN

Before you map your LDAP settings to PCE settings, determine your user base Distinguished Name (DN). The DN is the location in the directory where authentication information is stored.

If you don't have this information, contact your LDAP administrator for assistance.

When configuring the PCE to work with LDAP, be aware of the following:

  • PCE uses LDAP protocol version 3 ("v3").

  • Supported LDAP distributions include OpenLDAP 2.4 and Active Directory.

  • Supported LDAP protocols include LDAP, LDAPS, or LDAP with STARTTLS.

Limitations

These are the current limitations for LDAP authentication:

  • Any locally created user has precedence over an LDAP user of the same name. For example, if the LDAP server has a user with a username attribute (such as cn or uid) of johndoe and the default PCE user of the same name is present, the PCE user takes precedence. Only the local password is accepted. The roles mapped to the local user will take effect upon login. To work around this limitation, you must delete the specific local user.

  • LDAP and SAML single sign-on authentication methods cannot be used together. In this release of the PCE, an organization can either use LDAP or SAML single sign-on to authenticate external users.

  • This release enables LDAP configuration via REST APIs only.

LDAP Authentication for the PCE

The PCE supports user and role configuration for LDAP users and groups. You can configure up to three LDAP servers and map users and user groups from your LDAP servers to PCE roles.

Before configuring LDAP, review the 'LDAP Prerequisites and Considerations' topic in this document.

Authentication Precedence

PCE local authentication takes precedence over any external systems. The PCE authenticates a user in the following order:

  1. The PCE first attempts local authentication. If the account expires or fails, the PCE will not try to log in using LDAP authentication.

  2. If the local user does not exist, the PCE attempts to log in to LDAP (if enabled).

Configuration Steps

To configure the PCE to work with LDAP, perform these steps:

  1. Enable the PCE to use LDAP authentication. See Enable LDAP Authentication.

  2. Set up an LDAP configuration.

    When searching for LDAP users, the PCE follows the order in which the servers were configured. By default, the configurable request timeout is 5 seconds. Once the request time expires, the PCE attempts to connect to the next server in the configuration.

    For example, assume you configure three LDAP servers in the following order: A, B, and C. The PCE will search the servers in that same order. If it finds a user on server A, it stops even if the same user also exists on servers B and C. The PCE will try to use A's credentials for that user, but if it fails to connect to A, it searches the remaining servers: first B, and the search proceeds following the expiration of the connection timeout.

  3. Map your LDAP groups to one or more PCE roles.

Set up the PCE for LDAP Authentication

The PCE supports LDAPS and LDAP with STARTTLS. To use the PCE with secure LDAP with SSL/TLS certificates, add the certificate chain to the PCE's local certificate store.

Using REST APIs for LDAP Configuration in the PCE

The following table provides an overview of the REST APIs available to configure the PCE for LDAP Authentication. For information about the parameters for these REST APIs, see LDAP Authentication Reference.

APIs for LDAP Configuration

PCE APIs

HTTP | URI

Retrieve the PCE authentication settings.

GET [api_version]/authentication_settings

Update the PCE authentication settings.

PUT [api_version]/authentication_settings

Retrieve the LDAP configuration.

GET [api_version]/authentication_settings/ldap_configs

Get instance

GET [api_version]/authentication_settings/ldap_configs/:uuid

Create an LDAP configuration.

POST [api_version]/authentication_settings/ldap_configs

Update an LDAP configuration.

PUT [api_version]/authentication_settings/ldap_configs/:uuid

Delete an LDAP configuration.

DELETE [api_version]/authentication_settings/ldap_configs/:uuid

Verify the connection to the LDAP server.

POST [api_version]/authentication_settings/ldap_configs/:uuid/verify_connection

Enable LDAP Authentication

This section explains how to use the API to enable the PCE for LDAP authentication. Before invoking this API, you must enable the LDAP preview feature in the PCE. For instructions on enabling this preview feature, see LDAP Authentication.

URI

PUT /api/v2/authentication_settings

Request Body

Property

Data Type

Required

Description

authentication_type

enum

Yes

The type of authentication

Enum Item

Purpose

Local

Local DB authentication

SAML

SAML authentication enabled

RADIUS

RADIUS authentication enabled

LDAP

LDAP authentication enabled

Example Payload to Configure LDAP Authentication

{
"authentication_type": "LDAP",
}

Response Code

The following response codes can be returned:

  • 200 indicates success

  • 403 indicates the user is not an org owner

  • 406 indicates invalid parameters

LDAP Configuration

This section explains how to configure an LDAP server.

Configure Secure LDAP

To configure an LDAP server in the PCE, you need to configure LDAP for SSL authentication.

You can secure LDAP with SSL/TLS Certificates using these three methods:

  • Use PCE Web UI to Configure Secure LDAP

  • Install LDAP TLS Certificates from the PCE Command-Line to the PCE System CA Store.

  • Configure LDAP for SSL authentication using REST APIs

Configure LDAP for SSL authentication

The following APIs are used to configure LDAP for SSL:

  • GET /authentication_settings/ldap_configs

  • GET /authentication_settings/ldap_configs/:uuid

  • POST /authentication_settings/ldap_configs

  • PUT /authentication_settings/ldap_configs/:uuid

The required property is tls_ca_bundle.

To manage TLS CA bundle for LDAP authentication, use these APIs:

  • GET /login_proxy_ldap_configs

  • POST /login_proxy_ldap_configs

  • PUT /login_proxy_ldap_configs/update

Update LDAP configuration

This section outlines how to update the LDAP server configuration in the PCE.

PUT /api/v2/authentication_settings/ldap_configs/:uuid

where uuid indicates the LDAP server configuration UUID.

Request body:

{
        "address" :  "ldap-1.mycompany.com" ,
        "bind_password" :  "qw3r!y123!!" ,
       "full_name_attribute" :  "displayName" ,
        "port" : 636,
        "insecure_disable_tls_certificate_verification": true
}

Response:

The following response codes can be returned:

  • 204: indicates success

  • 403: indicates the user is not an org owner

  • 404: indicates LDAP configuration not found or an attempt to update LDAP configuration in another domain

  • 406: indicates invalid parameters

Delete LDAP Server Configuration

This API deletes the configuration for an LDAP server in the PCE. For information about the request parameters, see LDAP Configuration Parameters Overview.

DELETE /api/v2/authentication_settings/ldap_configs/:uuid

where uuid indicates the LDAP server configuration uuid

Request body: none

Response:

The following response codes can be returned:

  • 204: indicates success

  • 403: indicates the user is not an org owner

  • 404: indicates LDAP configuration not found or an attempt to update LDAP configuration in another domain

  • 406: indicates invalid parameters

LDAP Use Cases and Testing

This section provides some LDAP use cases and testing procedures.

Configure LDAP for SSL authentication

Use case 1:

Retrieve all LDAP configurations for the domain.

  1. Request format:GET /api/v2/authentication_settings/ldap_configs

  2. Possible parameters (drawn from REST API conventions):

    • Required: none

  3. Request Body: none

  4. Response format: JSON

  5. Response Code: 200 success

Use case 2:

Create LDAP server configuration.

  1. Request format: POST /api/v2/authentication_settings/ldap_configs

  2. Possible parameters (drawn somewhat from REST API Conventions):

    • Required: none

    • Optional: none

  3. Request Body:

    Single-PCE

    {
        "name": "ldap 1",
        "address": "ldap-1.ilabs.io",
        "port": "10636",
        "authentication_method": "LDAPS",
        "request_timeout_seconds": 4,
        "bind_distinguished_name": 'CN=admin,CN=Users,DC=ilabs,DC=io',
        "bind_password": 'test1234',
        "user_base_distinguished_name": 'DC=ilabs,DC=io',
        "username_attribute": 'sAMAccountName',
        "full_name_attribute": 'cn',
        "user_memberof_attribute": 'memberof',
        "tls_ca_bundle": "
        -----BEGIN CERTIFICATE-----
        MIIDhTCCAm2gAwIBAgIQYx+dZzQPBLdN6e8uqW2ByDANBgkqhkiG9w0BAQ0FADBJ
        .................................................................
        -----END CERTIFICATE-----
        -----BEGIN CERTIFICATE-----
        MIIF7TCCBNWgAwIBAgITEgAAAEg0ToOKIywtOQAAAAAASDANBgkqhkiG9w0BAQ0F
        ....................................................................................
        -----END CERTIFICATE-----"
       }

    Supercluster

    {
        "pce_fqdn": "devmr01",
        "name": "ldap 1",
        "address": "ldap-1.ilabs.io",
        "port": "10636",
        "authentication_method": "LDAPS",
        "request_timeout_seconds": 4,
        "bind_distinguished_name": 'CN=admin,CN=Users,DC=ilabs,DC=io',
        "bind_password": 'test1234',
        "user_base_distinguished_name": 'DC=ilabs,DC=io',
        "username_attribute": 'sAMAccountName',
        "full_name_attribute": 'cn',
        "user_memberof_attribute": 'memberof',
        "tls_ca_bundle": "-----BEGIN CERTIFICATE-----
        MIIDhTCCAm2gAwIBAgIQYx+dZzQPBLdN6e8uqW2ByDANBgkqhkiG9w0BAQ0FADBJ
        -----END CERTIFICATE-----
        -----BEGIN CERTIFICATE-----
        MIIF7TCCBNWgAwIBAgITEgAAAEg0ToOKIywtOQAAAAAASDANBgkqhkiG9w0BAQ0F
        -----END CERTIFICATE-----"	
}

  4. Response format: JSON

  5. Response Code:

  • 204 success

  • 403 not an org owner

  • 406 invalid params

Use case 3:

Update LDAP server configuration:

  1. Request format: PUT /api/v2/authentication_settings/ldap_configs/:uuid

  2. Possible parameters (drawn somewhat from REST API Conventions):

    • Required: uuid - LDAP server configuration UUID

    • Optional: none

  3. Request Body:

    {
"tls_ca_bundle":" 
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE------
----END CERTIFICATE-----"
}

  4. Response format: JSON

  5. Response Codes:

  • 204 success

  • 403 not an org owner

  • 404 LDAP config not found, or attempt to update LDAP config in another domain

  • 406 invalid params

Test LDAP Server Connectivity

This section outlines how to use the API to verify the connectivity of a PCE-configured LDAP server.

POST /api/v2/authentication_settings/ldap_configs/:uuid/verify_connection

where uuid indicates the LDAP server configuration UUID.

Request body: none

Response body:

If a server connection is verified successfully:

{
	"verified" :  true
}

If the server connection verification fails:

{
	"verified" :  false ,
	"errors" : [
	{
	"token" :  "ldap_server_verification_failure" ,
	"message" :  "LDAP server verification failure:  LDAP server error message"
	}
]
Mapping Group Membership for LDAP

This section explains how to map group membership to user roles.

You must first configure the PCE to use LDAP authentication and then map PCE roles to that server's groups.

When a user attempts to log in, the PCE queries the server(s) to find that user. It grants the user permissions based on any roles associated with the LDAP groups to which the user belongs.

You have the following options for changing user permissions:

  • For a group of users, remap the LDAP group to a different PCE role.

  • For an individual user, move the user to an LDAP group mapped to a different PCE role using the LDAP server.

You can also perform these user management activities:

  • Add a user to a PCE role.

    On the PCE, map the PCE role to an LDAP group.

    On your LDAP server, add the user to that LDAP group.

  • Remove a user from a PCE role by removing it from the corresponding LDAP group on your LDAP server.

Users can have memberships in several roles, which give them access to all the capabilities available for each role.

For example, a user is a member of both the docs and eng groups, and the docs group is mapped to "Ruleset Manager" while the eng group is mapped to "Ruleset Provisioner." In this case, the user obtains all permissions assigned to the "Ruleset Manager" and "Ruleset Provisioner" roles.

Note

The PCE checks LDAP membership information when a user attempts to log in.

You do not need to reload the authentication configuration when adding or removing users.