Using delegated machine credentials

During enrollment of a computer to the service, the computer communicates with Privileged Access Service by using its own authentication credentials in the background. You can make use of those same computer or machine credentials to call APIs against your tenant. Using the computer credentials simplifies the authentication process for your automation needs and provides a more secure, contained approach to privileged access. This feature of brokering the computer's trusted credentials without granting direct access to them is called delegated machine credentials or DMC.

By using delegated machine credentials, you don't have to set up another OAUTH2 client application and an associated service account with yet another password to manage and so forth. Doing it this way is both more secure and easier to automate.

For example, a DevOps administrator can now automate the creation of temporary computers that run specific workloads and enable those computers to have access to a vaulted secret that they need to run those workloads. A developer can use delegated machine credentials with microservices to authenticate to each other, without having to create and manage service accounts and their credentials.

The main benefits of using delegated machine credentials are as follows:

  • Limit the profileration of service accounts:

    With traditional application to application password management (AAPM), you have to create an OAUTH2 client application and the partner service account, delegate the appropriate permissions, and then embed the client/secret so that the application can call APIs. That set of tasks is per workload.

    With DMC, you can leverage the machine identity and have workloads interact with Centrify PAS using the machine's credentials, thereby reducing the number of service accounts and administrative overhead considerably.

  • Use delegated machine credentials in your automation framework:

    You can incorporate client installation, enrollment, and delegation at the point when you initialize your workload systems, thus allowing you to make Centrify PAS a standard part of your DevOps pipeline.

  • Reduce your risk:

    You can scope API access for the machine credentials at the individual workload level, so that you give each workload just enough access.

To use delegated machine credentials (an overview):

  1. Set up an enrollment code with preassigned roles and grant the desired permissions to those roles. For details, see Adding systems using enrollment codes.

    The machine account will get the set of permissions granted by the pre-assigned roles.

  2. Download and install the Centrify Client for Windows or Centrify Client for Linux in one of the following ways:

  3. Enroll a computer and enable delegated machine credentials (DMC) when enrolling, either from the client wizard or command line. For details, see Enrolling a computer and enabling delegated machine credentials.

    Note:   You must enable DMC at the time of enrollment. If you don't, you have to unenroll and re-enroll with the DMC feature enabled.

  4. Configure your applications, scripts, or workloads to call Centrify PAS APIs by referencing the delegated machine credentials. For details, see Using delegated machine credentials to call an API.

 

Enrolling a computer and enabling delegated machine credentials

After you finish enrolling a computer with delegated machine credentials, you'll see the following in the Admin Portal:

  • In the System information, the Client Profile tab lists the DMC feature as enabled.
  • In the Users list, the machine account is listed under "All Users" and "All Service Users."

For details about client commands and their parameters, see Using Centrify Client commands.

For more information about enrolling, see Downloading and installing the Centrify Client for Windows and Enrolling a computer.

To enroll the computer interactively and enable delegated machine credentials on Windows:

  1. Run the Windows client installer program.
  2. On the enrollment page, specify the enrollment code and tenant URL.

    • If you want to enable all client features, don't enter any additional options.

      Information about the other available client features are listed in the information about client commands.

    • If you want to enable DMC only, enter "-F DMC" in the additional option field.

    If you'd prefer, you can exit the wizard without specifying any enrollment information. You'll need to later run the cenroll command to enroll the system.

To enroll the computer from the command line and enable delegated machine credentials on Windows or Linux:

  • In a command line window, run cenroll with the following parameters:

    cenroll -c <enrollmentcode> -t <tenantURL> -F dmc -d [scopename:scopedefinition]
    • Specify the enrollment code with the -c option

    • Specify the entire tenant URL with the -t option

    • Specify -F DMC to enable delegated machine credentials.

    • Optionally, specify the -f option to force enrollment. Doing this can be useful in cases where you have already unenrolled a system without deleting it.

    • Optionally, you can specify the -d option to define an API scope, which defines which APIs are allowed to be called by this machine credential with a scope name and a regular expression. You can also later set the API scope in the system's Client Profile tab.

      For example, you can specify -d pwd:.+password to define a scope named pwd that allows any APIs that end in the word "password."

    After the enrollment completes, the command displays a message listing the enrollment parameters.

To unenroll a computer:

  • From the command line, run cunenroll. For which specific options to run with cunenroll, see the command line help.

    You can verify that the computer unenrolled successfully either by running cinfo or by checking the system information in the Admin Portal. If you unenroll with the -md option that also deletes the system, then you won't see the system in the list. If you unenroll with the -m option, then you will still see the system listed but there won't be an agent version under the system name nor in the Client Profile.

 

Using delegated machine credentials to call an API

Your automation scripts or applications can reference the delegated machine credentials for API calls to Centrify PAS directly or by using the Centrify command line interface (Centrify CLI). For details about APIs, please visit the Centrify developer portal.

The examples below use the Centrify command line utility to call the APIs just so that you can see what the API calls might look like.

To use delegated machine credentials to call an API using the Centrify command line (CCLI):

  1. If you want to use the Centrify Command Line, you can find the installation information here: https://github.com/centrify/centrifycli/wiki/Centrify-CLI:-Centrify-Command-Line-Interface
  2. In a command line window, call the desired API with the delegated machine credential:

    ccli -m [-ms <apiscope>] -url <tenanturl> <apiendpoint> [-j <jsoninputfile>]
    • -m specifies the command line to use machine credentials
    • -ms specifies the API scope and references a scope that you've already defined in the Client Profile. For example, -ms pwd calls an api scope named pwd.
    • -url specifies the tenant URL
    • specify the API endpoint, such as /servermanage/checkoutpassword
    • -j specifies a JSON file, if the API takes an input

    You can have multiple scopes defined, such as a scope for reading secrets and another scope for updating secrets. You can share the read scope with many users but only share the update scope with a handful of administrators.

    So, here's what a full API call might look like, as an example:

    ccli -m -ms pwd -url https://ABC1234.my.centrify.net /servermanage/checkoutpassword -j "{'ID':'abcdefgh-1234-ijkl-56789mnopqrs'}