|
Authenticating MarkLogic users with Kerberos
24 November 2016 09:27 AM
|
||||
IntroductionMarkLogic Server allows you to configure MarkLogic Server so that users are authenticated using an external authentication protocol, such as Lightweight Directory Access Protocol (LDAP) or Kerberos. These external agents serve as centralised points of authentication or repositories for user information from which authorisation decisions can be made. In this article you will see the steps required to authenticate a user using Kerberos. Authenticating MarkLogic users with KerberosKerberos is a ticket-based authentication protocol for trusted hosts on untrusted networks which provides users with encrypted tickets that can be used to request access to particular servers. Because Kerberos uses tickets, both the user and the server can verify each other's identity and user passwords do not have to pass through the network. This article will also show you how to configure MarkLogic Server to validate Kerberos user tickets and to map them to a MarkLogic database user on your cluster. Kerberos user principals are defined in the format username@REALM.NAME, for this article we will use the Kerberos principal ml1@MLKRB.LOCAL and the MarkLogic userid krbuser1. Configuring the MarkLogic clusterBefore MarkLogic can validate Kerberos user tickets the following requirements need to be met.
Configuring the Kerberos clientIn order to authenticate Kerberos users, MarkLogic needs to know which host domains it will be authenticating and which Kerberos realms to authenticate against. This information is held in the /etc/krb5.conf file in Unix or krb5.ini file in Windows (The location will be dependent on the Windows Kerberos implementation being used, i.e Active Directory or MIT Kerberos). In this example our the MarkLogic servers are installed on domains mwca.marklogic.com, mwcb.marklogic.com and mwcc.marklogic.com and the Kerberos Domain Controller (KDC) resides at kerberos.marklogic.com. The [domain_realm] section is a series of host domains and realms mappings, in this case all our example MarkLogic hosts are using the .marklogic.com domain and will be using the MLKRB.LOCAL realm. The [realms] section defines the realms that this client can access and the associated KDC that will be used. A sample krb5.conf file:[logging] [libdefaults] [realms] [domain_realm] Note: If the server is already configured to use Kerberos you should simply merge your new realm and domain settings. Creating a Kerberos KeytabThe Kerberos Domain Administrator must create a services.keytab file for each MarkLogic instance to permit it to authenticate Kerberos users. This is done by issuing the addprinc and ktpass commands on the kerberos Domain controller. Example[kadmin@kerberos ~]# kadmin.local kadmin.local: kadmin.local: Repeat the above steps for each MarkLogic host in the cluster and copy the resultant services.keytab file to the corresponding MarkLogic Server Data directory. Creating a MarkLogic External Security configurationOn the MarkLogic Server "Configure->Security->External Security" panel create a new Kerberos External Security configuration as below: Configuring the MarkLogic AppServerOn the MarkLogic Server "Configure->Groups->{group-name}->AppServers" panel configure the AppServer to user kerberos-ticket as the authentication method and specify the external security definition created in the previous step: Add the External Kerberos principal to the MarkLogic server useridOn the MarkLogic Server "Configure->Security->Users" panel add the external Kerberos principal name to the user: Verify everything is working as expectedFrom a Kerberos enabled client machine, create a new ticket for your Kerberos user principal using the kinit command: [martin@local1]# Password for ml1@MLKRB.LOCAL: Check the status of the ticket using the [martin@local1]# Ticket cache: KEYRING:persistent:0:0 Valid starting Expires Service principal Negotiate a user connection to the AppServer using Curl; specify the -u switch without a userid and password will use the Kerberos ticket created previously. [martin@local]# curl -v --negotiate -u : http://mwca.marklogic.com:8050 * About to connect() to mwca.marklogic.com port 8050 (#0) If MarkLogic is able to successfully authenticate the Kerberos user, you see an HTTP 200 code in response to the curl command and the MarkLogic AppServer logs should show the details of the external user mapping External User(ml1@MLKRB.LOCAL) is Mapped to User(krbuser1) 192.168.0.50 - - [25/Sep/2016:13:48:30 +0100] "GET / HTTP/1.1" 200 2103 - "curl/7.29.0" TroubleshootingThe following is a list of common problems encountered when authenticating with Kerberos. Unable to generate a Kerberos tokenCheck that the kdc parameter in krb5.conf file points to a valid Kerberos Domain Controller: [martin@local ~]# Unauthorised 401 response due to gss_init_sec_context() failed: : No Kerberos credentials available errorThis indicates that the Kerberos ticket is missing or invalid; use the klist command to check current ticket status and create a new ticket with kinit if required: [martin@local ~]# curl -v --negotiate -u : http://mwca.marklogic.com:8050 * About to connect() to mwca.marklogic.com port 8050 (#0) MarkLogic server not able to validate Kerberos ticketCheck the following:
[admin@mwca MarkLogic]# ls -al services.keytab -rw------- 1 daemon daemon 594 Sep 25 12:33 services.keytab Debugging Kerberos connections in MarkLogicOn the MarkLogic Server "Configure->Groups->{group-name}->Diagnostics" panel add Kerberos GSS Negotiate to the list of trace events: Further Reading | ||||
 (3 vote(s)) |
||||