AAA LDAP Configuration

Configure the LDAP servers used for authentication

Up to three LDAP servers can be configured, each with a unique priority from 1 to 3. On login the servers are contacted in priority order. The device binds to the server as the user, with the bind DN built as <user_dn>=<username>,<base_dn>, for example uid=jdoe,ou=people,dc=example,dc=com. After a successful bind the attributes of the user’s entry are compared with the priv_lvl_ref_table rules in their order; the first matching rule sets the role. If no rule matches, fallback_role is used, and with fallback_role set to none the login is refused. Whether LDAP is used at all, and when, is set on the AAA Configuration page.

API

• Data (LDAP_SERVER object):

  {
      "id": 1,
      "priority": 1,
      "hostname": "ldap.example.com",
      "port": 636,
      "timeout": 3,
      "base_dn": "ou=people,dc=example,dc=com",
      "user_dn": "uid",
      "version": 3,
      "tls_usage": "strict",
      "fallback_role": "none",
      "priv_lvl_ref_table": [
          {
              "attribute_name": "memberOf",
              "attribute_data_type": "str",
              "comparison_value": "^cn=admins,.*",
              "comparison_operator": "=~",
              "role": "admin"
          },
          {
              "attribute_name": "memberOf",
              "attribute_data_type": "str",
              "comparison_value": "^cn=operators,.*",
              "comparison_operator": "=~",
              "role": "user"
          }
      ]
  }

  • id - unsigned integer assigned by the device (read-only)
  • priority - 1 to 3, unique among the configured servers (mandatory)
  • hostname - hostname, IPv4 or IPv6 address (mandatory)
  • port - 1 to 65535, usually 389 for ldap:// and 636 for ldaps:// (mandatory)
  • timeout - seconds to wait for the server, 1 to 3 (mandatory)
  • base_dn - Base Distinguished Name, the subtree that holds the user entries (mandatory)
  • user_dn - name of the attribute that holds the login name, for example uid or cn; combined with the username and base_dn into the bind DN (mandatory)
  • version - LDAP protocol version, 3 (mandatory)
  • tls_usage - transport security (mandatory):
    • none - plain ldap:// connection
    • lenient - ldaps:// connection, the server certificate is not verified
    • strict - ldaps:// connection, the server certificate must be signed by a trusted CA (see CA Certificate)
  • fallback_role - role used when no rule matches: none, viewer, user (equal to operator) or admin; defaults to none
  • priv_lvl_ref_table - list of rules mapping attributes of the user’s entry to roles; may be empty. Multi-valued attributes such as memberOf are matched against every value.
    • attribute_name - LDAP attribute to inspect
    • attribute_data_type - str or int
    • comparison_value - value to compare with, always a string
    • comparison_operator:
      • <, <=, >, >= - integers only
      • =~ - regular expression match, strings only
      • ==, != - any type
    • role - viewer, user (equal to operator) or admin

  A field that violates its constraint is rejected with 422 (see Responses).

• Get all LDAP servers

  • Path: /api/aaa/ldap
  • Method: GET
  • Minimum user role: admin
  • Response on success (200 OK): array of LDAP_SERVER objects in data

• Get an LDAP server

  • Path: /api/aaa/ldap/{id}
  • Method: GET
  • Minimum user role: admin
  • Response on success (200 OK): LDAP_SERVER object in data
  • Response on failure (404 Not Found): no server with this id

• Add an LDAP server

  • Path: /api/aaa/ldap
  • Method: POST
  • Minimum user role: admin
  • Request body: LDAP_SERVER object without id; all fields marked mandatory above must be present, fallback_role and priv_lvl_ref_table may be omitted
  • Response on success (200 OK): message Successfully added the ldap_server., the created object in data
  • Response on failure: 412 Could not add ldap server: priority <n> already exists, 422 on a constraint violation

• Update an LDAP server

  • Path: /api/aaa/ldap/{id}
  • Method: PUT
  • Minimum user role: admin
  • Request body: LDAP_SERVER object; fields that are omitted keep their current value
  • Response on success (200 OK): message Successfully updated the ldap_server., the updated object in data
  • Response on failure: 404 if no such server, 412 if the new priority is already used by another server, 422 on a constraint violation

• Update all LDAP servers

  • Path: /api/aaa/ldap
  • Method: PUT
  • Minimum user role: admin
  • Request body: array of LDAP_SERVER objects with id set. The array must contain every configured server exactly once; servers cannot be added or removed with this call.
  • Response on success (200 OK): the stored array in data
  • Response on failure (400 Bad Request): Error, not all the entries are present in the request. or Error, not all the entries have unique priorities.; 422 on a constraint violation

• Delete an LDAP server

  • Path: /api/aaa/ldap/{id}
  • Method: DELETE
  • Minimum user role: admin
  • Response on success (200 OK): message Successfully deleted the ldap_server., the deleted object in data
  • Response on failure (404 Not Found): no server with this id

• Delete all LDAP servers

  • Path: /api/aaa/ldap
  • Method: DELETE
  • Minimum user role: admin
  • Response on success (200 OK): message Successfully removed all ldap servers; succeeds also when the list is already empty

Back to Index