Credential Web Services
Overview
Universal Controller supports the following RESTful-based web services for Credential operations, which are listed alphabetically on this page.
Formatting specifications for each web service, including details about property requirements, are provided.
Note
If you want to change only the runtime password, rather than modifying the whole credential record, you can use the Password API.
Create a Credential
Description | |
---|---|
URI | http://host_name/uc/resources/credential |
HTTP Method | POST |
Description | Creates a Credentials. |
Example URI | http://localhost:8080/uc/resources/credential |
Consumes Content-Type | application/xml, application/json |
Produces Content-Type | n/a |
Example Request | See Create a Credential Example Request, below. |
Properties | See Credential Properties. |
Example Response |
|
Create a Credential: Example Request
XML Request | JSON Request |
---|---|
Credential Properties
Properties | UI Field Name | Description | Specifications | Required |
---|---|---|---|---|
| Description | User-defined; description of this record. | N | |
| n/a | Universal Controller release that the record was exported from. | read only | N |
| n/a | Record table information. | read only | N |
| Name | Name used within the Controller to identify this Credential. | Maximum 40 alphanumerics. | Y |
| Member of Business Services | Business Services that this record belongs to. <opswiseGroups> <opswiseGroup>group1</opswiseGroup> <opswiseGroup>group2</opswiseGroup> </opswiseGroups> "opswiseGroups": ["group1","group2"] | N | |
| Provider | Provider of credentials. | Valid values (case-insensitive):
Default is Universal Controller (1). | N |
| Provider Parameters | Set of parameters specific to provider. See Provider Parameters for provider parameter details for each provider. | XML JSON | Y |
| n/a | Specification for whether or not the Create a Credential web service will persist the sysId - CRED property.
Note In XML web services, | Optional; Valid values: true/false (default is true). | N |
| Key Location (SFTP only) | Using SFTP requires that you supply a valid credential that specifies the location of the SSL/TLS Private key on your Agent. This property provides the location, which must exist on the Agent where you intend to run the SFTP task. Currently, the Controller does not support password authentication for SFTP Transfer. | N | |
| Pass Phrase (SFTP only) | Pass phrase for the Runtime User's SSL/TLS Private key file. | N | |
| Runtime Password | Runtime user's Change Runtime Password of Credentials. |
| N |
| Token | Runtime user Token that can be used with the Return Token of a Credential function. |
| N |
| Runtime User | Runtime user ID, including an LDAP- or AD-formatted user ID, under which the job will be run. | Y | |
| n/a | System ID field in the database for this Credential record. | Persisted only if retainSysIds is set to true. | N |
| Type | Type of Credential. Note: You cannot modify the type after the Credential has been created, but you can convert any Credential type to any other type. | Valid Values:
Default is Standard (1). | N |
Provider Parameters
If a provider parameter is secure, its value will not be exposed in the GET response (xml: no <value>
property; json: "value"
: null). However, you can manually add it to the PUT/POST request to update the value.
AWS Secrets Manager
Provider Parameter | Required | Description |
---|---|---|
ACCESS_KEY_ID | true | The AWS access key, used to identify the user interacting with AWS. |
SECRET_ACCESS_KEY | true | The AWS secret access key, used to authenticate the user interacting with AWS. |
REGION | true | The region name (e.g., us-east-1). |
SECRET_ID | true | The ARN or name of the secret to retrieve. |
SECRET_PASSWORD_KEY | false | If this secret was created by using the console, then Secrets Manager stores the information as a JSON structure of key/value pairs. Specifies the key for the password in the JSON structure.
|
SECRET_PASSPHRASE_KEY | false | Specifies the key for the passphrase in the JSON structure.
|
SECRET_TOKEN_KEY | false | Specifies the key for the token in the JSON structure.
|
CACHE_TTL | false | The TTL (Time To Live), in seconds, for the cached secret before a new request to the provider is made. (default 3600 seconds / 1 hour) |
Azure Key Vault
Provider Parameter | Required | Description |
---|---|---|
KEY_VAULT_NAME | true | The name of the Key Vault used to build the vault URL to send HTTP requests to.
|
SECRET_NAME | true | The name of the secret. |
CLIENT_ID | true | The client (application) ID. |
TENANT_ID | true | The Azure Active Directory tenant (directory) Id. |
CLIENT_SECRET | The client secret used to authenticate.
| |
CLIENT_ASSERTION | The client assertion used to authenticate.
| |
PEM_CERTIFICATE | The path of the PEM certificate used for authenticating.
| |
PFX_CERTIFICATE | The path of the PFX certificate used for authenticating.
| |
PFX_CERTIFICATE_PASSWORD | The password for the PFX certificate.
| |
CACHE_TTL | false | The TTL (Time To Live), in seconds, for the cached secret before a new request to the provider is made. (default 28800 seconds / 8 hours) |
CyberArk Credential Provider
Provider Parameter | Required | Description |
---|---|---|
APPLICATION_ID | true | The unique ID of the application issuing the password request. |
SAFE | true | The name of the Safe where the password is stored. |
FOLDER | true | The name of the folder where the password is stored. |
OBJECT | true | The name of the password object to retrieve. |
REASON | false | The reason for retrieving the password. |
CACHE_TTL | false | The TTL (Time To Live), in seconds, for the cached secret before a new request to the provider is made. (default 5 |
CyberArk Central Credential Provider
Provider Parameter | Required | Description |
---|---|---|
HOST | true | The hostname of the Central Credential Provider. |
PORT | true | The port of the Central Credential Provider. |
APPLICATION_ID | true | The unique ID of the application issuing the password request. |
SAFE | true | The name of the Safe where the password is stored. |
FOLDER | true | The name of the folder where the password is stored. |
OBJECT | true | The name of the password object to retrieve. |
CACHE_TTL | false | The TTL (Time To Live), in seconds, for the cached secret before a new request to the provider is made. (default 5 seconds) |
HashiCorp Vault
Provider Parameter | Required | Description |
---|---|---|
ADDRESS | true | The address of the Vault server (e.g. http://127.0.0.1:8200). |
TOKEN | The Vault token for use with Vault’s token auth method. | |
ROLE_ID | The Role ID of the AppRole for use with Vault’s AppRole auth method. | |
SECRET_ID | The Secret ID belonging to the AppRole for use with Vault’s AppRole auth method.
| |
JWT | The signed JSON Web Token (JWT) for use with Vault’s JWT auth method. | |
ROLE | The Role name for use with Vault’s JWT auth method.
| |
KEYSTORE | The path to the keystore containing the client certificate and private key for use with Vault’s TLS Certificates auth method. | |
KEYSTORE_PASSWORD | The password used to unlock the keystore. | |
KEYSTORE_TYPE | The type of keystore. Default is PKCS12.
| |
CLIENT_CERTIFICATE | The path to the X.509 certificate, in PEM format, for use with Vault’s TLS certificates auth method. | |
CLIENT_KEY | The path to the unencrypted RSA private key, in PEM format, for use with Vault’s TLS certificates auth method.
| |
AUTH_MOUNT_PATH | false | Specifies the path where the auth method backend is mounted. |
MOUNT_PATH | false | Specifies the path where the KV backend is mounted.
|
SECRET_PATH | true | The path to the KV secret. |
DATA_PASSWORD_KEY | false | Specifies the key for the password in the secret data. |
DATA_PASSPHRASE_KEY | false | Specifies the key for the passphrase in the secret data. |
DATA_TOKEN_KEY | false | Specifies the key for the token in the secret data. |
CACHE_TTL | false | The TTL (Time To Live), in seconds, for the cached secret before a new request to the provider is made. (default 300 seconds / 5 minutes) If the secret has a TTL, then it will be used to set the expiration time (KV Version 1 only). |
Delete a Credential
Description | |
---|---|
URI | http://host_name/uc/resources/credential |
HTTP Method | DELETE |
Description | Deletes a Credential. |
URI Parameters | See Delete a Credential URI Parameters, below. |
Example URI | http://localhost:8080/uc/resources/credential?credentialname=test |
Example Response |
|
Delete a Credential: URI Parameters
Parameter | Description | Specifications | Required | Mutually Exclusive With |
---|---|---|---|---|
| ID used within the Controller to identify this Credential. | String; URI parameter. | Y |
|
| Name used within the Controller to identify this Credential. | String; URI parameter. | Y |
|
List Credentials
Description | |
---|---|
URI | http://host_name/uc/resources/credential/list |
HTTP Method | GET |
Description | Retrieves information on all Credentials. |
Example URI | http://localhost:8080/uc/resources/credential/list |
Authentication | HTTP Basic |
Consumes Content-Type | n/a |
Produces Content-Type | application/xml, application/json |
Example Response | See List Credentials Example Response, below. |
Properties | See Credential Properties. |
List Credentials: Example Response
XML Response | JSON Response |
---|---|
Modify a Credential
Description | |
---|---|
URI | http://host_name/uc/resources/credential |
HTTP Method | PUT |
Description | Modifies the Credential specified by the |
Example URI | http://localhost:8080/uc/resources/credential |
Consumes Content-Type | application/xml, application/json |
Produces Content-Type | n/a |
Example Request | See Modify a Credential Example Request, below. |
Properties | See Credential Properties. |
Example Response |
|
Modify a Credential: Example Request
XML Request | JSON Request |
---|---|
Read a Credential
URI | http://host_name/uc/resources/credential |
HTTP Method | GET |
Description | Retrieves information on a specific Credential. |
URI Parameters | See Read a Credential URI Parameters, below. |
Example URI | |
Consumes Content-Type | n/a |
Produces Content-Type | application/xml, application/json |
Example Response | See Read a Credential Example Response, below. |
Properties | See Credential Properties. |
Read a Credential: URI Parameters
Parameter | Description | Specifications | Required | Mutually Exclusive With |
---|---|---|---|---|
| ID used within the Controller to identify this Credential. | String; URI parameter. | Y |
|
| Name used within the Controller to identify this Credential. | String; URI parameter. | Y |
|
Read a Credential: Example Response
XML Response | JSON Response |
---|---|
Test Provider
Description | |
---|---|
URI | http://host_name/uc/resources/credential/testprovider |
HTTP Method | POST |
Description | Run the Test Provider command for the specified credentials. |
Example URI | http://localhost:8080/uc/resources/credential/testprovider?credentialname=My_AWS_Secret |
Authentication | HTTP Basic |
Produces Content-Type | application/xml, application/json |
Consumes Content-Type | N/A |
Example Responses |
|
Test Provider: Query Parameters
The following request parameters will be needed for the service.
Property | UI Field Name | Description | Specifications | Required | Mutually Exclusive With |
---|---|---|---|---|---|
credentialname | N/A | Name used within the Controller to identify the Credentials. | String; URI parameter | Y (unless credentialid is specified) | credentialid |
credentialid | N/A | ID used within the Controller to identify the Credentials. | String; URI parameter | Y (unless credentialname is specified) | credentialname |
Test Provider: Example Response
XML Response | JSON Response |
---|---|