Ambari CLI Wizard for Knox SSO Reference

Reference information, including syntax, for the command ambari-server setup-sso. This command is used to set up and configure Knox SSO.

Silent Mode

In silent mode all configuration details may be set on the command line via arguments. However, one argument is a password that is needed for authentication to use Ambari's REST API. This argument may be left off of the command causing the CLI to prompt for it.

For example:

# ambari-server setup-sso --ambari-admin-username=admin ...
Using python  /usr/bin/python
Setting up SSO authentication properties...
Enter Ambari Admin password:

You can run ambari-server setup-sso --help for syntax help.

Required Syntax, Enabling SSO

 --sso-enabled=true
                        Indicates whether to enable/disable SSO
  --sso-enabled-ambari=<true|false>
                        Indicates whether to enable/disable SSO authentication
                        for Ambari, itself
  --sso-manage-services=<true|false>
                        Indicates whether Ambari should manage the SSO
                        configurations for specified services
  --sso-enabled-services=<service list>
                        A comma separated list of services that are expected
                        to be configured for SSO (you are allowed to use '*'
                        to indicate ALL services)
  --sso-provider-url=<URL>
                        The URL of SSO provider; this must be provided when
                        --sso-enabled is set to 'true'
  --sso-public-cert-file=SSO_PUBLIC_CERT_FILE
                        The path where the public certificate PEM is located;
                        this must be provided when --sso-enabled is set to
                        'true'
  --ambari-admin-username=<username>
                        Ambari administrator username for accessing Ambari's
                        REST API

Optional Syntax, Enabling SSO

  --sso-jwt-cookie-name=<cookie name>
                        The name of the JWT cookie 
                        Default value: hadoop-jwt
  --sso-jwt-audience-list=<audience list>
                        A comma separated list of JWT audience(s)
                        Default value <empty>
  --ambari-admin-password=<password>
                        Ambari administrator password for accessing Ambari's
                        REST API

Required Syntax, Disabling SSO

  --sso-enabled=false
                        Indicates whether to enable/disable SSO
  --ambari-admin-username=AMBARI_ADMIN_USERNAME
                        Ambari administrator username for accessing Ambari's
                        REST API

Optional Syntax, Disabling SSO

  --ambari-admin-password=<password>
                        Ambari administrator password for accessing Ambari's
                        REST API

Interactive Mode

In interactive mode some configuration details may be set on the command line via arguments and the CLI will prompt for the rest.

# 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):
Public Certificate PEM (empty line to finish input):
MIICVTCCAb6gAwIBAgIIKwH4/V7SjxEwDQYJKoZIhvcNAQEFBQAwbTELMAkGA1UE
...
6fSqZSwbBXwFKf0gIBttufyldePpAsM7Yg==

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)? n
   Use SSO for ATLAS [y/n] (n)? y
JWT Cookie name (hadoop-jwt):
JWT audiences list (comma-separated), empty for any ():
Ambari Server 'setup-sso' completed successfully.

In either case, the CLI collects the data and submits it to Ambari via the REST API. This then triggers processes in Ambari to enable or disable SSO as needed.

SSO via the REST API

The SSO configuration may be managed using Ambari's REST API, via the following entry point: /api/v1/services/AMBARI/components/AMBARI_SERVER/configurations.

This entry point supports the following request types:


GET - retrieve the SSO configuration data
POST - explicitly set the SSO configuration data, replacing all properties
PUT - update the SSO configuration data, only the specified properties are updated
DELETE - removes the SSO configuration data

Getting the SSO Configuration

To retrieve the SSO configuration data:

GET /api/v1/services/AMBARI/components/AMBARI_SERVER/configurations/sso-configuration

Example 404 response:

{
  "status" : 404,
  "message" : "The requested resource doesn't exist: RootServiceComponentConfiguration not found where Configuration/service_name=AMBARI AND Configuration/component_name=AMBARI_SERVER AND Configuration/category=sso-configuration."
}

Example 200 response:

{
  "href" : "http://ambari_server.host:8080/api/v1/services/AMBARI/components/AMBARI_SERVER/configurations/sso-configuration",
  "Configuration" : {
    "category" : "sso-configuration",
    "component_name" : "AMBARI_SERVER",
    "service_name" : "AMBARI",
    "properties" : {
      "ambari.sso.authentication.enabled" : "false",
      "ambari.sso.enabled_services" : "AMBARI, ATLAS",
      "ambari.sso.jwt.audiences" : "",
      "ambari.sso.jwt.cookieName" : "hadoop-jwt",
      "ambari.sso.manage_services" : "true",
      "ambari.sso.provider.certificate" : "-----BEGIN CERTIFICATE-----\nMIIC...TYptEVg==\n-----END CERTIFICATE-----",
      "ambari.sso.provider.originalUrlParamName" : "originalUrl",
      "ambari.sso.provider.url" : "https://knox.host:8443/gateway/knoxsso/api/v1/websso"
    },
    "property_types" : {
      "ambari.sso.authentication.enabled" : "PLAINTEXT",
      "ambari.sso.enabled_services" : "PLAINTEXT",
      "ambari.sso.jwt.audiences" : "PLAINTEXT",
      "ambari.sso.jwt.cookieName" : "PLAINTEXT",
      "ambari.sso.manage_services" : "PLAINTEXT",
      "ambari.sso.provider.certificate" : "PLAINTEXT",
      "ambari.sso.provider.originalUrlParamName" : "PLAINTEXT",
      "ambari.sso.provider.url" : "PLAINTEXT"
    }
  }
}

Setting the SSO Configuration

To set the SSO configuration data, replacing any previously existing data:

POST /api/v1/services/AMBARI/components/AMBARI_SERVER/configurations

Example payload:

{
  "Configuration": {    
    "category" : "sso-configuration",
    "properties": {
      "ambari.sso.manage_services" : "true",
      "ambari.sso.enabled_services": "AMBARI, ATLAS",
      "ambari.sso.provider.url": "https://knox.host:8443/gateway/knoxsso/api/v1/websso",
      "ambari.sso.provider.certificate": "-----BEGIN CERTIFICATE-----\nMIIC...TYptEVg==\n-----END CERTIFICATE-----",
      "ambari.sso.authentication.enabled": "true",
      "ambari.sso.jwt.audiences": "",
      "ambari.sso.jwt.cookieName": "hadoop-jwt",
      "ambari.sso.provider.originalUrlParamName": "originalUrl"
    }
  }
}

Updating the SSO Configuration

To update the SSO configuration data, only replacing or adding specific properties:

PUT /api/v1/services/AMBARI/components/AMBARI_SERVER/configurations/sso-configuration

Example payload:

{
  "Configuration": {    
    "properties": {
      "ambari.sso.manage_services" : "true",
      "ambari.sso.enabled_services": "AMBARI, ATLAS, RANGER",
      "ambari.sso.authentication.enabled": "false"
    }
  }
}

Deleting the SSO Configuration

To delete the SSO configuration data, removing all properties:

DELETE /api/v1/services/AMBARI/components/AMBARI_SERVER/configurations/sso-configuration