Overview of External Authentication
MarkLogic Server supports external authentication by means of LDAP, SAML, Kerberos, or certificate. When a user attempts to access a MarkLogic Server app server that is configured for external authentication, the requested app server sends the username and password to an LDAP or SAML server for authentication. (For Kerberos, only the username is sent.) Once authenticated, the LDAP, SAML, Kerberos, or certificate protocol is used to identify the user on MarkLogic Server. For details on how to configure an app server for external authentication, see Creating an External Authentication Configuration Object and Configuring an App Server for External Authentication.
Users can be authorized either internally by MarkLogic Server, externally by an LDAP or SAML server, or both internally and externally.
If the app server is configured for internal authorization, the user needs to exist in the MarkLogic Server Security database where his or her “external name” matches the external user identity registered with either LDAP, Kerberos or certificate, depending on the selected authentication protocol. For details on how to map a MarkLogic Server user to an LDAP Distinguished Name (DN) or a Kerberos User Principal, see Assigning an External Name to a User.
If the app server is configured for LDAP authorization, the user does not need to exist in MarkLogic Server. Instead, the external user is identified by a username with the LDAP server and the LDAP groups associated with the DN are mapped to MarkLogic Server roles. MarkLogic Server then creates a temporary user with a unique and deterministic id and those roles. For details on how to map a MarkLogic Server role to an LDAP group, see Assigning an External Name to a Role.
If the app server is configured for SAML authorization, the server issues a standard SAML attribute query to the identity provider to retrieve authorization information. The identity provider is uniquely identified by its ID, which is combined with an attribute name and value to form an external name with the necessary privileges.
If the app server is configured for both internal and external authorization, users that exist in the MarkLogic Server Security database are authorized internally by MarkLogic Server. If a user is not a registered MarkLogic Server user, then the user must be registered on the LDAP or SAML server.
Note
MarkLogic Server caches negative lookups to avoid overloading the external Kerberos or LDAP server. Successful logins are also cached. The cache can be cleared by calling sec:external-security-clear-cache().
This flowchart illustrates the logic used to determine how a MarkLogic Server user is authenticated and authorized:
This table shows the possible external authorization configurations for accessing MarkLogic Server:
Authentication Protocol |
Authentication Scheme |
Authorization Scheme |
Description |
|---|---|---|---|
|
|
|
The user is authenticated by a certificate and the user’s groups are mapped to the MarkLogic Server roles. The user does not need to exist on MarkLogic Server. Instead, the MarkLogic Server creates a temporary user with the correct roles to access MarkLogic Server. |
|
|
|
The user is authenticated by a certificate. User must exist in MarkLogic Server. |
|
|
|
The user is authenticated by Kerberos and a Kerberos session ticket is used to authenticate the user to access MarkLogic Server. The user must exist in MarkLogic Server, where the user’s “external name” matches the Kerberos User Principal. |
|
|
|
The user is authenticated by Kerberos and a Kerberos session ticket is used at a time determined by the app server to authenticate the user to access MarkLogic Server. The user must exist in MarkLogic Server, where the user’s “external name” matches the Kerberos User Principal. |
|
|
|
The user is authenticated by Kerberos. No ticket is exchanged between the client and the app server. Instead, the username and password are passed. This configuration is used when the client is not capable of ticket exchange and should only be used over SSL connections because the password is communicated as clear text. The user must exist in MarkLogic Server, where the user’s “external name” matches the Kerberos User Principal. |
|
|
|
The user is authenticated by Kerberos and a Kerberos session ticket is used to identify the user to MarkLogic Server. MarkLogic Server extracts the user ID from the ticket and sends it to the LDAP directory. MarkLogic Server uses the information returned by the LDAP directory to create a temporary user with the correct roles to access MarkLogic Server. The user does not need to exist on MarkLogic Server. |
|
|
|
The user is authenticated by LDAP. User must exist in MarkLogic Server, where the user’s “external name” matches the LDAP Distinguished Name (DN). |
|
|
|
The user is authenticated by LDAP or SAML and the user’s groups are mapped to the MarkLogic Server roles. The user does not need to exist on MarkLogic. Instead, the MarkLogic Server creates a temporary user with the correct roles to access MarkLogic Server. |
|
|
|
A SAML Identity Provider prompts the user to login, if necessary, and sends the authentication request back to MarkLogic Server. |
Note
When application-level authentication is enabled with Kerberos authentication, an application can use
xdmp:gss-server-negotiate()to obtain a username that can be passed toxdmp:login()to log into MarkLogic Server.If running MarkLogic Server on Windows and using LDAP authentication to authenticate users, the user name must include the domain name in this form:
userName@domainName.