Centrify CLI (ccli), built with .net Core 2.2, provides a command line interface to the Centrify REST API. Features include:

• List and search of Centrify API endpoints.
• JSON Schemas of Centrify API endpoints.
• Handling of Authentication through OAuth or user/password.

The following documentation provides details around key Centrify CLI components:

• General Usage
• Options to Centrify CLI
• Files and Directories Included with Centrify CLI
• Authenticating Centrify CLI
• Profiles for Centrify CLI
• Example CLI

Each invocation requires a command and optional parameters.

There is one command per invocation. It must be the first parameter, with no prefacing punctuation such as ccli listConfig:

• Running an API

  • Specify the API path as documented on the Centrify Developers site: https://developer.centrify.com/reference (example: /sysinfo/version).
  • If an API requires URL arguments, specify the arguments in the API path: /UserMgmt/[email protected]
  • If an API has payload, use the various command line options for providing the payload to the API.

• Saving/Loading default configurations are as follows:

  • listConfig: Lists the current config from {UserHome}centrifycli.config. This is a JSON file you can edit directly as well.
  • saveConfig: Saves the current parameters, including connection parameters, to {UserHome}centrifycli.config. These parameters are loaded by default for subsequent runs.
  • listProfiles: Lists the current server profiles from {UserHome}/centrifycli.servers. This is a JSON file you can edit directly as well.
  • saveProfile: Saves the current connection parameters to the {UserHome}/centrifycli.servers file. Useful primarily to create an example file for subsequent editing.

• OAuth

  • requestToken: Retrieves an OAuth token from the Centrify server using provided credentials.
  • saveToken: Requires -token , used to write the token to centrifycli[.profile].token.

• REST APIs Information

  • listAPIs: Lists the callable endpoints known by the current (embedded or referenced API) list, each contains a short description and the JSON schema.
  • findAPI searchword: Similar to listAPIs, but filters for _searchword _in the path or description.
  • updateAPIs: Force refresh of the cached Centrify API list (this will occur automatically when cached data is sufficiently out of date).

• Miscellaneous

  • version: Shows Centrify CLI and cloud versions.
  • help: Displays help.

Options are just that, optional. There may be several ways to accomplish the same goal, using different options. For example, authentication could be accomplished by one of the following avenues:

• username/password in the command line.
• in the config file server.
• as specified in a profile.
• through OAuth token at the command line.
• the token file. Similarly, an API command may not require any parameters. If it does, the JSON input could be specified on the command line, or in a file named on the command line, or piped in through stdin as specified on the command line.

Most options can be saved in the configuration files centrifycli.config and centrifycli.servers.

Centrify CLI looks in the user's home directory for its saved configuration.

• centrifycli.config contains saved configuration including default profile.
• centrifycli.servers contains any custom saved server profiles and facilitates switching between several accounts or servers.
• centrifycli.swagger.json contains the cached Centrify REST API information.
• centrifycli[.profile].token contains the saved OAuth token (default or per profile where '[.profile]' is replaced by the profile nickname).

Note: The above first three files are JSON text files, the .config and .servers files can be hand edited, and the .token files are text files holding the token (the token is over 600 somewhat-random characters). This file is precisely the same as copying the portion of the redirect URL between 'access_token=' and the subsequent ampersand into a text file.

There are several possible sources of configuration values. They are processed in the following order:

• centrifycli.config for general configuration and the default profile.
• The command-line may specify a profile from the centrifycli.servers file; if so, the profile is loaded and replaces the default profile from config.
• The command-line may have individually-specified values - they override everything else and are processed last.

Most operations require authentication against a remote server. This can be done through OAuth Token or user/password. In both cases, the values can be:

• Passed in on the command line (and saved to configuration).
• Loaded from configuration.

Note: The username may be stored in the profile without the password being in the file. At that point the authorization will fail if the password is not provided on the command line through -pw during invocation.

OAuth allows for authenticating a token that will time out eventually (five hours is the default, configured in the Web Applications settings page of the management portal). It can, however, be used without additional authentication until then and does not require an account password after that.

Warning: If/when the token expires, it is still the default authentication mechanism for the profile or configuration. Pass an empty value to clear it.)

Before Centrify CLI can use OAuth against the service, the service must be configured. See Configuring Centrify Service OAuth for Centrify CLI for more information about configuring the service and using tokens with Centrify CLI.

The alternative to OAuth is to specify the user name and password using -u and -pw. These can be stored in the configuration or in a profile, such that they need not be provided each time. Note: Users that require MFA cannot authenticate through this method. Additionally, the password will not be saved to config by default, you must provide the -savepw option to do so (not recommended) and that will save the password in clear text.

Profiles hold server connection parameters. These are for users switching between multiple Centrify tenants or users regularly. Note: The typical user will not need profiles, as the centrifycli.config file contains a default profile.

Create a profile by setting the appropriate configuration through command line args and use 'saveprofile'.

`OAuth version: ccli saveprofile -p MyProfile -url https://myco.my.centrify.net -u [email protected] -app MyCliApp ccli requesttoken -p MyProfile

User version: ccli saveprofile -p MyProfile -url https://myco.my.centrify.net -u [email protected]`

Use the 'listprofiles' command: ccli listprofiles

Provide profile command line arg with the name of the Profile: ccli /UserMgmt/GetUserAttributes -ja ID="[email protected]" -p MyProfile

ccli findapi secret

Example before configuring: ccli /ServerManage/GetSecretsAndFolders -j "{'Parent': ''}"

Response: `Could not find config file C:\Users\cliuser\centrifycli.config Exception: Exception: Invalid URI: The format of the URI could not be determined.'

Running with command-line authentication: ccli /ServerManage/GetSecretsAndFolders -j "{'Parent': ''}" -user [email protected] -pw supersecretpwd -url https://myco.my.centrify.net

Saving Authentication to the default configuration: ccli saveConfig -user [email protected] -url https://myco.my.centrify.net

Running with the configured (non-explicit) authentication: This time it picks it up from the configuration file at ${UserHome}/centrifycli.config

`ccli /ServerManage/GetSecretsAndFolders -pw supersecretpwd -j "{'Parent': '' }"

{
  "IsAggregate": false,
  "Count": 1,
  "Columns": [
  ...
}`

ccli /sysinfo/version

ccli /UserMgmt/GetUserAttributes

ccli /UserMgmt/GetUserAttributes -j "{ 'ID': '[email protected]' }"

ccli /UserMgmt/GetUserAttributes -ja ID="[email protected]"