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.
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 Password Web Services#Change Runtime Password of Credentials. |
| N |
| Token | Runtime user Token that can be used with the Functions#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 Credentials#Converting Credential Types 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) |
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 |
---|---|