Configuring Apache Knox SSO
Also available as:
PDF

Enable Knox SSO Using the Ambari CLI

To enable Knox SSO (Single Sign-on) for your cluster, you must begin with the Ambari CLI wizard. It prompts you for SSO settings and propagates them across your cluster. The wizard then configures SSO for Atlas, Ambari, and Ranger UIs.

When you enable SSO, unauthenticated users who try to access a service (e.g., Ambari, Atlas, etc), are redirected to the Knox SSO login page for authentication. This makes signing into services faster and easier, with fewer credentials to remember.
The Ambari Server must be running and you must be logged in as root.
  1. From the command line, begin the SSO setup wizard: ambari-server setup-sso.
  2. When prompted, enter your Ambari Admin credentials.
  3. Depending on your configuration, choose a path:
    • If SSO is not configured, it prompts Do you want to configure SSO authentication.
      • Enter y to continue through the wizard.
      • Enter n to exit the wizard.
    • If SSO is already configured, it prompts Do you want to disable SSO authentication.
      • Enter y to disable SSO for Ambari and the services (if services were being managed). Then it exits the wizard.
      • Enter n to continue through the wizard.
  4. Enter the provider URL using the format: https://<hostname>:8443/gateway/knoxsso/api/v1/websso.
    https://dw-weekly.field.hortonworks.com:8443/gateway/knoxsso/api/v1/websso
  5. Populate the Public Certificate PEM:
    1. Export the Knox certificate: ./knoxcli.sh export-cert --type PEM
      [root@dw-weekly bin]# ./knoxcli.sh export-cert --type PEM
      Certificate gateway-identity has been successfully exported to: /usr/$REPO/$VERSION/knox/data/security/keystores/gateway-identity.pem
    2. Copy the contents of the file, excluding the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.
      [root@dw-weekly bin]# ./knoxcli.sh export-cert --type PEM
      Certificate gateway-identity has been successfully exported to: /usr/$REPO/$VERSION/knox/data/security/keystores/gateway-identity.pem
      [root@dw-weekly bin]# vi /usr/$REPO/$VERSION/knox/data/security/keystores/gateway-identity.pem
      
      -----BEGIN CERTIFICATE-----
      MIIoqToofo6gfwIffgIIfJG6+oql7YUwGQYJKoqIhvoNfQZFfQfwGTZLMfkGf1UZfhMoVVMxGTfL
      fgNVffgTfFRlo3QxGTfLfgNVffoTfFRlo3QxGqfNfgNVffoTfkhhqG9voGZNMfsGf1UZoxMZVGVq
      GGZoMoYGf1UZfxMfqHotG2Vlf2x5LmqpqWxkLmhvonRvfnGvomtqLmNvfTfZFw0xOGf2MTUxNjU0
      MjffFw0xOTf2MTUxNjU0MjffMHUxoqfJfgNVffYTflVTMQ0wowYGVQQIZwRUqXN0MQ0wowYGVQQH
      ZwRUqXN0MQ8wGQYGVQQKZwqIYWRvf3fxGTfLfgNVffsTfFRlo3QxKGfmfgNVffMTH2R3LXGlqWts
      ZS5mfWVsqo5of3J0f253f3Jroy5jf20wgq8wGQYJKoqIhvoNfQZffQfGgY0fMIGJfoGffMjs9Q6M
      f4f4Ussf/Yffpfr7k3Gx8v0/Vlum6OL3Mr0vYQFtNSvGMZTZ25QQ8YHOvGf4frqi9lqwj6qwZYWf
      RQUTIxuiOGPiMhK70onmLflmqpoGYmSJ3/shfOUoyN7+JiImYYn/rJvt4Yt362gGvJynfsZGGKko
      johF4v0FLoqGfgMfffZwGQYJKoqIhvoNfQZFfQfGgYZfZomm8ZTJJufW4vfp8O51Qx7J4ioY6G69
      qgf76j4Oh8fqGqRVfoKYvrIZuJsZKHpIPGhtnVtqHG8YYf6vffSXoMmGpp5qfvZLfqnR1HNl6oZq
      qf7J9qn9MPZqlrf5/kOGY85w0UUkVqotRLjsK/niHhojGKffJrok7hMUo7TYwfQ
      -----END CERTIFICATE-----
    3. When prompted Public Certificate PEM (empty line to finish input), paste the contents of the cert.pem file.
      MIIoqToofo6gfwIffgIIfJG6+oql7YUwGQYJKoqIhvoNfQZFfQfwGTZLMfkGf1UZfhMoVVMxGTfL
      fgNVffgTfFRlo3QxGTfLfgNVffoTfFRlo3QxGqfNfgNVffoTfkhhqG9voGZNMfsGf1UZoxMZVGVq
      GGZoMoYGf1UZfxMfqHotG2Vlf2x5LmqpqWxkLmhvonRvfnGvomtqLmNvfTfZFw0xOGf2MTUxNjU0
      MjffFw0xOTf2MTUxNjU0MjffMHUxoqfJfgNVffYTflVTMQ0wowYGVQQIZwRUqXN0MQ0wowYGVQQH
      ZwRUqXN0MQ8wGQYGVQQKZwqIYWRvf3fxGTfLfgNVffsTfFRlo3QxKGfmfgNVffMTH2R3LXGlqWts
      ZS5mfWVsqo5of3J0f253f3Jroy5jf20wgq8wGQYJKoqIhvoNfQZffQfGgY0fMIGJfoGffMjs9Q6M
      f4f4Ussf/Yffpfr7k3Gx8v0/Vlum6OL3Mr0vYQFtNSvGMZTZ25QQ8YHOvGf4frqi9lqwj6qwZYWf
      RQUTIxuiOGPiMhK70onmLflmqpoGYmSJ3/shfOUoyN7+JiImYYn/rJvt4Yt362gGvJynfsZGGKko
      johF4v0FLoqGfgMfffZwGQYJKoqIhvoNfQZFfQfGgYZfZomm8ZTJJufW4vfp8O51Qx7J4ioY6G69
      qgf76j4Oh8fqGqRVfoKYvrIZuJsZKHpIPGhtnVtqHG8YYf6vffSXoMmGpp5qfvZLfqnR1HNl6oZq
      qf7J9qn9MPZqlrf5/kOGY85w0UUkVqotRLjsK/niHhojGKffJrok7hMUo7TYwfQ
      
  6. When prompted Use SSO for Ambari [y/n] (n)?, enter Y to use or N to not use SSO for Ambari.
    Ambari does not need to be configured for SSO in order for the services to be configured for SSO (and vice-versa).
  7. When prompted Manage SSO configurations for eligible services [y/n] (n)?, enter your selection.
    • y begins the service SSO setup wizard.
    • n exits the SSO setup wizard, saving your PEM setup and Ambari SSO selections.

    If you choose Y, the configurations for each eligible service are changed depending on the your selection when prompted.

    If you choose N, Ambari does not alter the existing configuration for any service. This is important if the cluster was set up using Blueprints and you do not want Ambari to change the SSO settings explicitly set.

  8. If you chose y, you are prompted Use SSO for all services [y/n] (y)?.
    • y automatically sets up SSO for all available services.
    • n enters SSO set up for each individual service, allowing you to choose for which services you wish to enable SSO.
  9. For the JWT Cookie name (), hadoop-jwt is the default.
  10. Leave JWT audiences list empty.
    The prompt returns Ambari Server 'setup-sso' completed successfully.
  11. Select Ambari > Actions > Restart All Required to restart all other services that require a restart.

Example Knox SSO via ambari-server setup-sso

[root@dw-weekly ~]# $JAVA_HOME/bin/keytool -export -alias gateway-identity -rfc -file cert.pem -keystore /usr/$REPO/current/knox-server/data/security/keystores/gateway.jks
[root@dw-weekly ~]# cd /usr/$REPO/current/knox-server/bin
[root@dw-weekly bin]# ./knoxcli.sh export-cert --type PEM
Certificate gateway-identity has been successfully exported to: /usr/$REPO/$VERSION/knox/data/security/keystores/gateway-identity.pem
[root@dw-weekly bin]# vi /usr/$REPO/$VERSION/knox/data/security/keystores/gateway-identity.pem
// <copy the certificate>
[root@dw-weekly ~]# ambari-server setup-sso
Using python  /usr/bin/python
Setting up SSO authentication properties...
Enter Ambari Admin login: admin
Enter Ambari Admin password: 

SSO is currently not configured
Do you want to configure SSO authentication [y/n] (y)? y
Provider URL (https://knox.example.com:8443/gateway/knoxsso/api/v1/websso): https://dw-weekly.field.hortonworks.com:8443/gateway/knoxsso/api/v1/websso
Public Certificate PEM (empty line to finish input):
MIIoqToofo6gfwIffgIIfJG6+oql7YUwGQYJKoqIhvoNfQZFfQfwGTZLMfkGf1UZfhMoVVMxGTfL
fgNVffgTfFRlo3QxGTfLfgNVffoTfFRlo3QxGqfNfgNVffoTfkhhqG9voGZNMfsGf1UZoxMZVGVq
GGZoMoYGf1UZfxMfqHotG2Vlf2x5LmqpqWxkLmhvonRvfnGvomtqLmNvfTfZFw0xOGf2MTUxNjU0
MjffFw0xOTf2MTUxNjU0MjffMHUxoqfJfgNVffYTflVTMQ0wowYGVQQIZwRUqXN0MQ0wowYGVQQH
ZwRUqXN0MQ8wGQYGVQQKZwqIYWRvf3fxGTfLfgNVffsTfFRlo3QxKGfmfgNVffMTH2R3LXGlqWts
ZS5mfWVsqo5of3J0f253f3Jroy5jf20wgq8wGQYJKoqIhvoNfQZffQfGgY0fMIGJfoGffMjs9Q6M
f4f4Ussf/Yffpfr7k3Gx8v0/Vlum6OL3Mr0vYQFtNSvGMZTZ25QQ8YHOvGf4frqi9lqwj6qwZYWf
RQUTIxuiOGPiMhK70onmLflmqpoGYmSJ3/shfOUoyN7+JiImYYn/rJvt4Yt362gGvJynfsZGGKko
johF4v0FLoqGfgMfffZwGQYJKoqIhvoNfQZFfQfGgYZfZomm8ZTJJufW4vfp8O51Qx7J4ioY6G69
qgf76j4Oh8fqGqRVfoKYvrIZuJsZKHpIPGhtnVtqHG8YYf6vffSXoMmGpp5qfvZLfqnR1HNl6oZq
qf7J9qn9MPZqlrf5/kOGY85w0UUkVqotRLjsK/niHhojGKffJrok7hMUo7TYwfQ=

Use SSO for Ambari [y/n] (n)? y
Manage SSO configurations for eligible services [y/n] (n)? y
 Use SSO for all services [y/n] (n)? y
JWT Cookie name (hadoop-jwt): hadoop-jwt
JWT audiences list (comma-separated), empty for any (): 
Ambari Server 'setup-sso' completed successfully.
[root@dw-weekly ~]# ambari-server restart
You must next manually configure Knox SSO by using component configuration files. These steps are documented in “Set up Knox SSO via Component Config Files”.