Edge for Private Cloud v4.18.01
This document explains how to integrate an external directory service into an existing Apigee Edge Private Cloud installation. This feature is designed to work with any directory service that supports LDAP, such as Active Directory, OpenLDAP, and others. All the steps are included here to get Apigee Edge working with your LDAP service.
An external LDAP solution allows system administrators to manage user credentials from a centralized directory management service, external to systems like Apigee Edge that use them. The feature described in this document supports both direct and indirect binding authentication.
This document assumes that you are an Apigee Edge for Private Cloud global system administrator and that you have an account the external directory service.
By default, Apigee Edge uses an internal OpenLDAP instance to store credentials that are used for user authentication. However, you can configure Edge to use an external authentication LDAP service instead of the internal one. The procedure for this external configuration is explained in this document.
Edge also stores role-based access authorization credentials in a separate, internal LDAP instance. Whether or not you configure an external authentication service, authorization credentials are always stored in this internal LDAP instance. The procedure for adding users that exist in the external LDAP system to the Edge authorization LDAP are explained in this document.
Note that authentication refers to validating a user's identity, while authorization refers to verifying the level of permission an authenticated user is granted to use Apigee Edge features.
What you need to know about Edge authentication and authorization
It's useful to understand the difference between authentication and authorization and how Apigee Edge manages these two activities.
Users who access Apigee Edge either through the UI or APIs must be authenticated. By default, Edge user credentials for authentication are stored in an internal OpenLDAP instance. Typically, users must register or be asked to register for an Apigee account, and at that time they supply their username, email address, password credentials, and other metadata. This information is stored in and managed by the authentication LDAP.
However, if you wish to use an external LDAP to manage user credentials on behalf of Edge, you can do so by configuring Edge to use the external LDAP system instead of the internal one. When an external LDAP is configured, user credentials are validated against that external store, as explained in this document.
Edge organization administrators can grant specific permissions to users to interact with Apigee Edge entities like API proxies, products, caches, deployments, and so on. Permissions are granted through the assignment of roles to users. Edge includes several built-in roles, and, if needed, org administrators can define custom roles. For example, a user can be granted authorization (through a role) to create and update API proxies, but not to deploy them to a production environment.
The key credential used by the Edge authorization system is the user's email address. This credential (along with some other metadata) is always stored in Edge's internal authorization LDAP. This LDAP is entirely separate from the authentication LDAP (whether internal or external).
Users who are authenticated through an external LDAP must also be manually provisioned into the authorization LDAP system. Details are explained in this document.
For more background on authorization and RBAC, see Managing organization users and Assigning roles.
For a deeper view, see also Understanding Edge authentication and authorization flows.
Understanding direct and indirect binding authentication
The external authorization feature supports both direct and indirect binding authentication through the external LDAP system.
Summary: Indirect binding authentication requires a search on the external LDAP for credentials that match the email address, username, or other ID supplied by the user at login. With direct binding authentication, no search is performed--credentials are sent to and validated by the LDAP service directly. Direct binding authentication is considered to be more efficient because there is no searching involved.
About indirect binding authentication
With indirect binding authentication, the user enters a credential, such as an email address, username, or some other attribute, and Edge searches authentication system for this credential/value. If the search result is successful, the system extracts the LDAP DN from the search results and uses it with a provided password to authenticate the user.
The key point to know is that indirect binding authentication requires the caller (e.g., Apigee Edge) to provide external LDAP admin credentials so that Edge can "log in" to the external LDAP and perform the search. You must provide these credentials in an Edge configuration file, which is described later in this document. Steps are also described for encrypting the password credential.
About direct binding authentication
With direct binding authentication, Edge sends credentials entered by a user directly to the external authentication system. In this case, no search is performed on the external system. Either the provided credentials succeed or they fail (e.g., if the user is not present in the external LDAP or if the password is incorrect, the login will fail).
Direct binding authentication does not require you to configure admin credentials for the external auth system in Apigee Edge (as with indirect binding authentication); however, there is a simple configuration step that you must perform, which is described later in this document.