Skip to main content

REST APIs for 24.2.20 and 24.2.10

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, which provide persistent authentication, and

  • Session credentials, which 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 be in effect on 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 you configure 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 that you configure three LDAP servers in this 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, 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 local certificate store on the PCE.

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 the steps to enable 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

See also: