Secure Deployment Manager REST API Access

This document explains how to enable Kerberos-based authentication and admin rights authorization for the Deployment Manager REST APIs.

Kerberos Authentication

This section covers:

Prerequisites to Enable Kerberos on Deployment Manager

Note: Make sure that your organization has a KDC configured and available. You need to configure your SNP or ServiceNamePrincipal with the KDC.

SNP: The ServiceNamePrincipal is divided into three parts, in the format primary/instance@KDC_REALM:

  • primary – Typically HTTP.
  • instance – Hostname for the DM REST API Server.
  • KDC_REALM – The Kerberos realm. Typically in uppercase letters.

Setting up the Required Configurations

To enable Kerberos on the Deployment Manager REST API Server, set the following two environment variables:

  • DM_PRINCIPAL – The SNP goes here. For example, if your Deployment Manager is hosted at http://hostname:8085:
    • DM_PRINCIPAL should be HTTP/hostname@<KDC_REALM>
    • DM_KEYTAB_FILE - The absolute path to the Keytab file, corresponding to the SNP and DM_PRINCIPAL specified above.

Tip: Proper Configuration

Both of these environment variables must be properly configured to enable Kerberos for your Deployment Manager REST API Server.

  • Be sure the DM_PRINCIPAL is a 3-part Kerberos Principal and has the 3 components: primary, instance, and KDC_REALM.
  • In case the keytab file specified is not present at the location, or only one of the configurations is present, an appropriate error message is returned.

In order to run Deployment Manager with Kerberos authentication disabled, make sure neither of these variables is set before starting Deployment Manager.

In addition, make sure /etc/krb5.conf has the correct default_realm and realm information.

Verifying Kerberos state at startup

When starting Deployment Manager with Kerberos enabled, the following lines are displayed in the logs:

Deployment Manager REST API Server running with Kerberos enabled

When starting the Deployment Manager with Kerberos disabled, the following line are displayed in the logs:

Deployment Manager REST API Server running with Kerberos disabled

Verifying Kerberos authentication using curl

Once you have Deployment Manager running with Kerberos, use the steps below to verify Kerberos authentication:

Obtain a TGT

Make sure you have a valid ticket-granting ticket (TGT) for the client principal you intend to use for authentication. The way to do this is using the kinit command. For example, for the client principal john@<KDC_REALM> that you intend to use for authentication, do the following:

  1. Enter the principal password (if you know it). The command is:
    $ kinit <principal_name>
    

    Example: principal entry

    $ kinit john
    
  2. Enter the keytab for the principal. The command is:
    $ kinit -kt <path_to_keytab> <principal_name>
    

    Example:

    $ kinit -kt /Users/john/john.keytab john
    
  3. Initiate the curl request.
    $ curl --negotiate -u : <HOSTNAME>:<PORT>/api/kerberos/client
    

    This should return the client name.

    Example: curl request

    $ curl --negotiate -u : hostname:8085/api/kerberos/client
    
    Authenticated client name is: john
    

If the output is the client name expected, Kerberos authentication setup for the Deployment Manager REST API Server is now complete.

DM Administrator Authorization

The Deployment Manager REST API service supports an administrator role.

This section covers:

Setting Up Users and Groups with Admin Privileges

In order to enable Administrator authorization on Deployment Manager and its REST API service, set the DM_ADMIN_USERS environment variable. The names of all individual users and Unix groups that have administrator privileges to the Deployment Manager go here as a CSV.

For example, if the user john is an admin, and all users in the group sysadmins are admins, the following value should be set john,sysadmins.

Verifying Admin Authorization Using Curl

Curl commands for a server running with Kerberos enabled:

  • Once the Deployment Manager is running with DM_ADMIN_USERS set, follow the steps above to kinit and get a TGT for the client.
  • The following curl commands return the client’s admin authorization status:
  # This REST API is for Kerberos authenticated clients only
  $ curl --negotiate -u : hostname:8085/api/kerberos/isAdmin

  true
  # The general API endpoint for authorization
  # Assuming kinit john on client
  $ curl -H "Content-Type: application/json" -X POST -d '{"user":"sally","token":""}' --negotiate -u : hostname:8085/api/system/isAdmin

  john is admin
  • For the call to /api/system/isAdmin, if the server is Kerberized, check for an authenticated client principal, irrespective of the user supplied in the POST request.

Curl command for server running with Kerberos disabled:

  • The following curl command should return the client’s admin authorization status:
  $ curl -H "Content-Type: application/json" -X POST -d '{"user":"john","token":"xyz"}' --negotiate -u : hostname:8085/api/system/isAdmin

  john is admin

Authorization of authenticated vs. unauthenticated clients.

Keep in mind the following points:

  • Authentication and authorization are independent.
  • If the client is Kerberos authenticated, then the Kerberos principal used by the client is used to authorize the user as an Admin, irrespective of the user information stored in the request.
  • If the client is not Kerberos authenticated, the user information provided in the request is used to authorize the client.
  • In either case, the user being authorized must be a valid Unix user.If this is not the case, an appropriate error message is returned.