This Confluence has been LDAP enabled, if you are an ASF Committer, please use your LDAP Credentials to login. Any problems file an INFRA jira ticket please.

Child pages
  • Ambari via KnoxSSO and Default IDP
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

Form-based Authentication for Existing Hadoop Web Applications


Apache Knox with default KnoxSSO IDP enables the use of form based authentication as a SSO solution for accessing and developing KnoxSSO enabled applications including, Ambari, Ranger, Hadoop UIs and custom built applications that utilize REST APIs through Knox. These capabilities will be available in the Knox 0.9.0 release.

This paper illustrates the use of the default IDP for form based authentication in Apache Knox. The same sort of flow that is described below would be available for Ranger, Hadoop UIs or any KnoxSSO participating application.

Form-based Authentication (Default IDP)

Available in Apache Knox 0.9.0 is the new ability to host web applications. This capability will be leveraged to deliver applications out of the box with Apache Knox and can be leveraged to deploy custom by customers and integrators. The first application to be delivered along with Apache Knox is a default IDP for KnoxSSO that provides form-based authentication for particpating applications. This allows applications that are in KnoxSSO to easily integrate a form-based authentication using the application called knoxauth and LDAP or Active Directory.

Form-based Authentication with the KnoxSSO application - knoxauth.



This paper illustrates the use of Okta’s SSO with SAML option for an existing Hadoop ecosystem application called Apache Ambari. The following figure shows how Ambari only ever needs to be aware of KnoxSSO. The underlying authentication mechanism is isolated from the participating application. In this case, KnoxSSO negotiates an authentication with Okta via the SAML 2 protocol.

Note that the above figure includes 3.b for Hadoop UIs. This option is not covered in this paper and requires each of the UIs to be configured properly for SSO as well. Again, each of them only need to be configured for KnoxSSO and the underlying authentication mechanism is isolated from them.


  1. Follow the Ambari Vagrant Quick Start guide ( to create a three node cluster with Centos 6.4 using Ambari 2.2 or greater

  2. Unzip the Apache Knox v0.9.0 release candidate to the {AMBARI_VAGRANT_HOME}/centos-6.4 directory which is a shared volume inside the vagrant machine /vagrant

  3. vagrant ssh into c6401

  4. Stop the Apache Knox instance that is already running (if there is one)

  5. Deploy the knoxsso.xml topology file from the doc into your local knox instance.  You can do this by copying the contents of the sample knoxsso.xml in this document into a new {GATEWAY_HOME}/conf/topologies/knoxsso.xml file.

  6. Change the param in knoxsso.xml to false. Ambari does not have SSL enabled by default and if we set the cookie to secure only it will not be presented to Ambari by the browser.  NOTE: THIS IS INSECURE AND ONLY USED FOR TESTING

  7. Start your v0.9.0 version of Knox via:  /usr/jdk64/jdk1.8.0_60/bin/java -jar bin/gateway.jar

  8. Configure Ambari for SSO with KnoxSSO through the SSO Wizard via the ambari-server CLI

    1. Get the gateway-identity public key from Apache Knox {GATEWAY_HOME}/data/security/keystores/gateway.jks via keytool or portecle (see Extracting Knox Public Key for SAML section for details)

    2. Get the SSO provider URL for the KnoxSSO websso endpoint

    3. su to root {pw: vagrant}

    4. start the sso wizard:

[root@c6401 knox-0.8.0]# ambari-server setup-sso
Using python  /usr/bin/python2
Setting up SSO authentication properties...
Do you want to configure SSO authentication [y/n] (y)?y
Provider URL [URL]:
Public Certificate pem (stored) (empty line to finish input):
Do you want to configure advanced properties [y/n] (n) ?n
Ambari Server 'setup-sso' completed successfully.
  1. Restart Ambari server:

[root@c6401 knox-0.8.0]# ambari-server restart

Extracting Knox Public Key for SAML IdP Configuration

There are multiple ways that you can do this.

The following will use keytool and openssl to first extract a der encoded cert and then to convert DER to PEM encoding:

 [vagrant@c6401 knox-0.8.0]$ keytool -export -keystore data/security/keystores/gateway.jks -alias gateway-identity -file gateway.cer
Enter keystore password:{master secret}
Certificate stored in file <gateway.cer>

Now convert the cer file into pem encoding via openssl:
[vagrant@c6401 knox-0.8.0]$ openssl x509 -inform der -in gateway.cer -out gateway.pem


For the Ambari SSO wizard the content between


must be provided when requested. This is by the Ambari KnoxSSO integration point for verification of the SSO tokens issued by KnoxSSO.


The free Portecle tool is great for extracting PEM encoded certs when the process doesn’t need to be automated. It may also be used when the keytool doesn’t allow passwords that are shorter than 6 chars to be used. Even when the keystore actually exists with shorter passwords <sigh>.


Apache Ambari

To demonstrate the integration between KnoxSSO and Okta for existing KnoxSSO aware Hadoop applications, Ambari will be used. This demonstrates Ambari’s ability to acquire and validate KnoxSSO tokens/cookies as a means to authenticate to its management capabilities and custom views.

Once logged in through KnoxSSO the resulting hadoop-jwt cookie is used to create an Ambari session. Apache Ambari only knows that it is relying on KnoxSSO and nothing about the underlying SSO provider (in this case Okta).

Test Integration with Okta

1. Open Apache Ambari in a broser at - you will initially be presented the Ambari login page but quickly redirected to the Okta login.

2. When presented with a login form, fill it out with these credentials (guest/Gu3stp@assword) and submit it to the Okta server. This will result in a SAML protocol POST to the callback URL for KnoxSSO.  The SAML assertion will be processed via the pac4j provider and the authenticated identity normalized into a Java Subject. The successful authentication continues the processing through the provider's chain and the identity assertion provider must use appropriate principal mapping to establish the effective username. The effective username is what the KnoxSSO service will put into the JWT token to be presented as a Cookie to all participating applications.

4. After a brief signing in page you should be redirected back to Ambari.  If you are interested you may find the hadoop-jwt cookie using Chrome’s developer tools - since the cookie is configured to not be secure only. It should be a session cookie set as HttpOnly and (normally) Secure.  The service parameter for the KnoxSSO service in the knoxsso.xml topology controls the secure only setting of the cookie.

Note how Ambari accepts successful authentication even when they are not existing users. The user is added to the Ambari database and they are assigned minimum privileges. As you can see above the authentication of guest was successful and they have been granted rights to their custom views - of which there are none.

An existing user with normal privileges would now have access to all of the Ambari capabilities and views for which they are permitted.


The contents of these topology files can be copied into your {GATEWAY_HOME}/conf/topologies directory.


The knoxsso.xml topology describes the manner in which a client acquires a KnoxSSO websso cookie/token. The pac4j federation provider allows the integration of a number of authentication solutions. In this case, the openid connect capability is being leveraged to integration the cloud based Privakey identity service.

  • No labels