Overview

Ambari ships with REST APIs that allow users to interact with the Ambari server for cluster operations such as partitioning a cluster, installing and removing services, checking service status, monitoring system status, etc.

Ambari REST APIs enforce HTTP basic access authentication. Upon a successful user login, Ambari also creates a session identified by a uuid value, the AMBARISESSIONID.

From a REST client point of view, the client must include user and password in the HTTP Authorization header in the initial REST API call. The client then has the option to either continue to submit the user and password via the HTTP Authorization header which creates new sessions in the process, or to reuse the current login session.

When an Ambari cluster has Kerberos enabled, Ambari REST APIs also require Kerberos admin principle credentials to be associated with the session.

In this post, we describe the Ambari session design and how to run Ambari REST API calls on a Kerberos-enabled cluster with the help of an Ambari session. We will use cURL as the example REST client in this post.

Ambari Session

Once Ambari server successfully authenticates the user submitted by the REST client, it associates a session with the login and uses AMBARISESSIONID to identify the session. Ambari server includes AMBARISESSIONID in the Set-Cookie header as part of the HTTP response to the REST client. Future REST calls can then switch to use the AMBARISESSIONID to reuse the current Ambari session.

For example, a REST API call to get the AMBARI clusters:

cURL Command

curl -v  -u admin:admin -H 'X-Requested-By: test' -X GET 'http://myhost.mydomain:8080/api/v1/clusters'

The server response includes the following HTTP Set-Cookie header:

Set-Cookie: AMBARISESSIONID=1lq2y0hun32hz1i3lzy5wnl0i7;Path=/;HttpOnly

Each successful login results in one unique AMBARISESSIONID (a uuid value), even when the REST client uses the same user and password for each login attempt. When examining the Set-Cookie value, the AMBARISESSIONID is the uuid right before ;Path=/;HttpOnly

Reuse AMBARISESSIONID

To reuse the current login session, you need to add AMBARISESSIONID to the Cookie header in all subsequent REST API calls.

To do this in cURL, you need to include -H 'Cookie: AMBARISESSIONID=[UUID]' as part of the cURL command as shown below.

In the cURL command, notice the -H 'Cookie: AMBARISESSIONID=1lq2y0hun32hz1i3lzy5wnl0i7' part where we include the AMBARISESSIONID in the REST API request header.

curl -i -X GET 'http://myhost.mydomain:8080/api/v1/stacks' -H 'X-Requested-By: test' -H 'Cookie: AMBARISESSIONID=1lq2y0hun32hz1i3lzy5wnl0i7'

In the HTTP Response headers returned by the Ambari server, notice there is no Set-Cookie anymore.

HTTP/1.1 200 OK  Date: Thu, 02 Jun 2016 17:57:21 GMT  X-Frame-Options: DENY  X-XSS-Protection: 1; mode=block  User: admin  Content-Type: text/plain  Content-Length: 197  Server: Jetty(9.2.11.v20150529)

Use AMBARISESSIONID on a Kerberos cluster

On a Kerberos cluster, Ambari server requires Kerberos admin principal user and password to be in the current Ambari session. So that Kerberos related operations will have the Kerberos admin principal user and password available.

Depending on whether you already have the AMBARISESSIONID, you may choose to add Kerberos admin credentials or simply initiate an Ambari session with Kerberos admin credentials included.

The following two sections describe the two approaches respectively.

Include Kerberos Admin Credentials to an Ambari Session

If you already have an AMBARISESSIONID, you can check if the corresponding Ambari session already contains Kerberos principal user and password. You do this by submitting an HTTP GET request against the following Kerberos validation REST API. Make sure to include the AMBARISESSIONID in the Cookie header instead of providing the user and password.

REST API Syntax

/api/v1/clusters/[cluster_name]/services/KERBEROS?fields=Services/attributes/kdc_validation_result,Services/attributes/kdc_validation_failure_details

cURL Command

curl -H 'X-Requested-By: test' -H 'Cookie: AMBARISESSIONID=h74ob2la266h76lr1ae3328d' -X GET http://myhost.mydomain:8080/api/v1/clusters/mycluster/services/KERBEROS?fields=Services/attributes/kdc_validation_result,Services/attributes/kdc_validation_failure_details -v

Ambari Server Response

{    "href" : "http://myhost.mydomain:8080/api/v1/clusters/mycluster/services/KERBEROS?fields=Services/attributes/kdc_validation_result,Services/attributes/kdc_validation_failure_details",    "ServiceInfo" : {      "cluster_name" : "mycluster",      "service_name" : "KERBEROS"    },    "Services" : {      "attributes" : {        "kdc_validation_failure_details" : "Missing KDC administrator credentials.\nThe KDC administrator credentials must be set in session by updating the relevant Cluster resource.This may be done by issuing a PUT to the api/v1/clusters/(cluster name) API entry point with the following payload:\n{\n  \"session_attributes\" : {\n    \"kerberos_admin\" : {\"principal\" : \"(PRINCIPAL)\", \"password\" : \"(PASSWORD)\"}\n  }\n}",        "kdc_validation_result" : "MISSING_CREDENTIALS"      }    }

If the Kerberos validation REST API returns an error message saying Missing KDC administrator credentials., the Ambari session does not include the Kerberps admin principal user and password yet. You can add the Kerberos credentials to the Ambari session by submitting an HTTP PUT request against the following REST API. When you submit the REST API call, make sure to include the AMBARISESSIONID in the Cookie header so that Ambari server adds the Kerberos credentials to the correct session.

Once you added Kerberos credentials to the Ambari session associated with a particular AMBARISESSIONID, you must use AMBARISESSIONID for all subsequent REST API calls. This is because each successful login results in one unique AMBARISESSIONID value, regardless whether they are all based on the same user and password.

REST API Syntax

/api/v1/clusters/[cluster_name]

Data Submitted

'[{"session_attributes":{"kerberos_admin":{"principal":"[principal_user_name]","password":"[principal_user_password]"}}}]'

cURL Command

curl -H 'X-Requested-By: test' -H 'Cookie: AMBARISESSIONID=h74ob2la266h76lr1ae3328d' -X PUT 'http://myhost.mydomain:8080/api/v1/clusters/mycluster' -d '[{"session_attributes":{"kerberos_admin":{"principal":"my_kerberos_admin","password":"my_kerberos_password"}}}]'

In the Ambari Server Response, notice the response header should indicate that Ambari server returned HTTP/200 response code, while the response Body is empty.

HTTP/1.1 200 OK

You can then rerun the Kerberos validation REST API to verify if your Ambari session now contains Kerberos admin credentials. The same as before, you must use AMBARISESSIONID as the authentication token instead of passing in the user and password. Ambari server returns a response similar to the following example if the Kerberos validation is OK, meaning the Kerberos admin credentials are included in the session.

{    "href" : "http://myserver.mydomain:8080/api/v1/clusters/mycluster/services/KERBEROS?fields=Services/attributes/kdc_validation_result,Services/attributes/kdc_validation_failure_details",    "ServiceInfo" : {      "cluster_name" : "mycluster",      "service_name" : "KERBEROS"    },    "Services" : {      "attributes" : {        "kdc_validation_failure_details" : "",        "kdc_validation_result" : "OK"      }    }

Initiate an Ambari Session with Kerberos Admin Credentials

If you do not yet have an AMBARISESSIONID, you can initiate an Ambari session and include Kerberos admin credentials in one REST API call.

REST API Syntax

/api/v1/clusters/[cluster_name]

Data Submitted

'[{"session_attributes":{"kerberos_admin":{"principal":"[principal_user_name]","password":"[principal_user_password]"}}}]'

cURL Command

curl -u admin:admin -H 'X-Requested-By: test' -X PUT 'http://myhost.mydomain:8080/api/v1/clusters/mycluster' -d '[{"session_attributes":{"kerberos_admin":{"principal":"my_kerberos_admin","password":"my_kerberos_password"}}}]' -v

Ambari Server Response – Response Body is empty. Response header should indicate that Ambari server returned HTTP/200 response code

HTTP/1.1 200 OK

Just like in the previous section, you can verify whether the session has Kerberos admin credentials included by running the Kerberos validation REST API call. The call returns an OK response if the Kerberos credentials are included, or an error message if the current Ambari session does not have Kerberos credentials.

Summary

In this post, we first described what AMBARISESSIONID represents and how to use it for subsequent calls instead of resubmitting the user/password information. We then described two ways to associate the Kerberos admin credentials with an Ambari session for a Kerberos cluster. The information provided should help you understand how you can reuse an Ambari session denoted by AMBARISESSIONID in your Ambari REST API calls on both Kerberos cluster and non-Kerberos cluster.