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.
Anchor |
---|
| Create a Credential |
---|
| Create a Credential |
---|
|
Create a Credential
Anchor |
---|
| Create a Credential Example Request |
---|
| Create a Credential Example Request |
---|
|
Create a Credential: Example Request
XML Request | JSON Request |
---|
Expand |
---|
| <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<credential exportReleaseLevel="7.3.0.0" exportTable="ops_credentials" retainSysIds="true" version="28">
<description />
<name>AWS_Secrets_Manager</name>
<opswiseGroups/>
<provider>AWS Secrets Manager</provider>
<providerParameters>
<providerParameter>
<name>ACCESS_KEY_ID</name>
<value>*****</value>
</providerParameter>
<providerParameter>
<name>SECRET_ACCESS_KEY</name>
<value>*****</value>
</providerParameter>
<providerParameter>
<name>REGION</name>
<value>us-east-1</value>
</providerParameter>
<providerParameter>
<name>SECRET_ID</name>
<value>arn:aws:secretsmanager:us-east-1:792840030488:secret:uc-e6wnD3</value>
</providerParameter>
<providerParameter>
<name>SECRET_PASSWORD_KEY</name>
<value>password</value>
</providerParameter>
<providerParameter>
<name>SECRET_PASSPHRASE_KEY</name>
<value></value>
</providerParameter>
<providerParameter>
<name>SECRET_TOKEN_KEY</name>
<value></value>
</providerParameter>
</providerParameters>
<runtimeKeyLocation />
<runtimeUser>secret</runtimeUser>
<sysId>f71d4960469840c2ac3734962405bedd</sysId>
<type>Standard</type>
</credential>
|
|
Expand |
---|
| {
"description": null,
"exportReleaseLevel": "7.3.0.0",
"exportTable": "ops_credentials",
"name": "AWS_Secrets_Manager",
"opswiseGroups": [],
"provider": "AWS Secrets Manager",
"providerParameters": [
{
"name": "ACCESS_KEY_ID",
"value": "*****"
},
{
"name": "SECRET_ACCESS_KEY",
"value": "*****"
},
{
"name": "REGION",
"value": "us-east-1"
},
{
"name": "SECRET_ID",
"value": "arn:aws:secretsmanager:us-east-1:792840030488:secret:uc-e6wnD3"
},
{
"name": "SECRET_PASSWORD_KEY",
"value": "password"
},
{
"name": "SECRET_PASSPHRASE_KEY",
"value": ""
},
{
"name": "SECRET_TOKEN_KEY",
"value": ""
}
],
"retainSysIds": true,
"runtimeKeyLocation": null,
"runtimeUser": "secret",
"sysId": "f71d4960469840c2ac3734962405bedd",
"type": "Standard",
"version": 28
}
|
|
Anchor |
---|
| Credential Properties |
---|
| Credential Properties |
---|
|
Credential Properties
Properties | UI Field Name | Description | Specifications | Required |
---|
Anchor |
---|
| description - CRED |
---|
| description - CRED |
---|
|
description | Description | User-defined; description of this record. |
| N |
Anchor |
---|
| exportReleaseLevel - CRED |
---|
| exportReleaseLevel - CRED |
---|
|
exportReleaseLevel | n/a | Universal Controller release that the record was exported from. | read only | N |
Anchor |
---|
| exportTable - CRED |
---|
| exportTable - CRED |
---|
|
exportTable | n/a | Record table information. | read only | N |
| Name | Name used within the Controller to identify this Credential. | Maximum 40 alphanumerics. | Y |
Anchor |
---|
| opswiseGroups - CRED |
---|
| opswiseGroups - CRED |
---|
|
opswiseGroups | Member of Business Services | Business Services that this record belongs to. Format: XML
Panel |
---|
Html bobswift |
---|
<pre>
<opswiseGroups>
<opswiseGroup>test</opswiseGroup>
</opswiseGroups>
</pre> |
|
JSON
Panel |
---|
Html bobswift |
---|
<pre>
"opswiseGroups": ["test"]
</pre> |
|
|
| N |
provider
| Provider | Provider of credentials. | Valid values (case-insensitive): As String = Universal Controller, As Value = 1 As String = AWS Secrets Manager, As Value=2 As String = Azure Key Vault, As Value = 3 As String = CyberArk Credential Provider, As Value = 4 As String = CyberArk Central Credential Provider, As Value = 5
Default is Universal Controller (1). | N |
providerParameters
| Provider Parameters | Set of parameters specific to provider. See Provider Parameters for provider parameter details for each provider. | Code Block |
---|
| <providerParameters>
<providerParameter>
<name>PARAMETER_1</name>
<value>VALUE_1</value>
</providerParameter>
<providerParameter>
<name>PARAMETER_2</name>
<value>VALUE_2</value>
</providerParameter>
</providerParameters> |
Code Block |
---|
| "providerParameters": [
{
"name": "PARAMETER_1",
"value": "VALUE_1"
},
{
"name": "PARAMETER_2",
"value": "VALUE_2"
}
] |
| Y (if provider is not Universal Controller) |
Anchor |
---|
| retainSysIds - CRED |
---|
| retainSysIds - CRED |
---|
| retainSysIds | n/a | Specification for whether or not the Create a Credential web service will persist the sysId property. - If retainSysIds="true" and
sysId is included in the request, sysId will be persisted to the database. - If retainSysIds="false" and
sysId is included in the request, sysId will be ignored; it will be autogenerated by the Controller.
Note |
---|
| In XML web services, retainSysIds is specified as an attribute in the <credential> element. |
| Optional; Valid values: true/false (default is true). | N |
Anchor |
---|
| runtimeKeyLocation - CRED |
---|
| runtimeKeyLocation - CRED |
---|
|
runtimeKeyLocation | 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. For File Transfer over SSL/TLS, make sure you have your private/public keys properly set up and working before you configure the Controller to use it. For example, to validate the keys, log into your destination server from your agent server using SSL/TLS. |
| N |
Anchor |
---|
| runtimePassPhrase - CRED |
---|
| runtimePassPhrase - CRED |
---|
|
runtimePassPhrase | Pass Phrase (SFTP only) | Pass phrase for the Runtime User's SSL/TLS Private key file. |
| N |
Anchor |
---|
| runtimePassword - CRED |
---|
| runtimePassword - CRED |
---|
|
runtimePassword | Runtime Password | Runtime user's password. | - If
runtimePassword is omitted in the request, it will be ignored. - If
runtimePassword is provided in the request, it will be updated.
| N |
Anchor |
---|
| runtimeToken - CRED |
---|
| runtimeToken - CRED |
---|
|
runtimeToken | Token | Runtime user Token that can be used with the ${_credentialToken(credential_name)} function. |
- If
runtimeToken is omitted in the request, it will be ignored. - If
runtimeToken is provided in the request, it will be updated.
| N |
Anchor |
---|
| runtimeUser - CRED |
---|
| runtimeUser - CRED |
---|
|
runtimeUser | 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: - As String = Standard, As Value = 1
- As String = Resolvable, As Value = 2
- As String = Web Service, As Value = 3
- As String = Email, As Value = 4
Default is Standard (1). | N |
Provider Parameters
Note |
---|
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) |
Anchor |
---|
| Delete a Credential |
---|
| Delete a Credential |
---|
|
Delete a Credential
Anchor |
---|
| Delete a Credential URI Parameters |
---|
| Delete a Credential URI Parameters |
---|
|
Delete a Credential: URI Parameters
Parameter | Description | Specifications | Required | Mutually Exclusive With |
---|
credentialid
| ID used within the Controller to identify this Credential. | String; URI parameter. | Y (unless credentialname is specified) | credentialname
|
credentialname
| Name used within the Controller to identify this Credential. | String; URI parameter. | Y (unless credentialid is specified) | credentialid
|
Anchor |
---|
| List Credentials |
---|
| List Credentials |
---|
|
List Credentials
Anchor |
---|
| List Credentials Example Response |
---|
| List Credentials Example Response |
---|
|
List Credentials: Example Response
XML Response | JSON Response |
---|
Expand |
---|
| <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<credential exportReleaseLevel="7.3.0.0" exportTable="ops_credentials" retainSysIds="true" version="28">
<description />
<name>AWS_Secrets_Manager</name>
<opswiseGroups/>
<provider>AWS Secrets Manager</provider>
<providerParameters>
<providerParameter>
<name>ACCESS_KEY_ID</name>
</providerParameter>
<providerParameter>
<name>SECRET_ACCESS_KEY</name>
</providerParameter>
<providerParameter>
<name>REGION</name>
<value>us-east-1</value>
</providerParameter>
<providerParameter>
<name>SECRET_ID</name>
<value>arn:aws:secretsmanager:us-east-1:792840030488:secret:uc-e6wnD3</value>
</providerParameter>
<providerParameter>
<name>SECRET_PASSWORD_KEY</name>
<value>password</value>
</providerParameter>
<providerParameter>
<name>SECRET_PASSPHRASE_KEY</name>
<value></value>
</providerParameter>
<providerParameter>
<name>SECRET_TOKEN_KEY</name>
<value></value>
</providerParameter>
</providerParameters>
<runtimeKeyLocation />
<runtimeUser>secret</runtimeUser>
<sysId>f71d4960469840c2ac3734962405bedd</sysId>
<type>Standard</type>
</credential>
|
|
Expand |
---|
| {
"description": null,
"exportReleaseLevel": "7.3.0.0",
"exportTable": "ops_credentials",
"name": "AWS_Secrets_Manager",
"opswiseGroups": [],
"provider": "AWS Secrets Manager",
"providerParameters": [
{
"name": "ACCESS_KEY_ID",
"value": null
},
{
"name": "SECRET_ACCESS_KEY",
"value": null
},
{
"name": "REGION",
"value": "us-east-1"
},
{
"name": "SECRET_ID",
"value": "arn:aws:secretsmanager:us-east-1:792840030488:secret:uc-e6wnD3"
},
{
"name": "SECRET_PASSWORD_KEY",
"value": "password"
},
{
"name": "SECRET_PASSPHRASE_KEY",
"value": ""
},
{
"name": "SECRET_TOKEN_KEY",
"value": ""
}
],
"retainSysIds": true,
"runtimeKeyLocation": null,
"runtimeUser": "secret",
"sysId": "f71d4960469840c2ac3734962405bedd",
"type": "Standard",
"version": 28
}
|
|
Anchor |
---|
| Modify a Credential |
---|
| Modify a Credential |
---|
|
Modify a Credential
Anchor |
---|
| Modify a Credential Example Request |
---|
| Modify a Credential Example Request |
---|
|
Modify a Credential: Example Request
XML Request | JSON Request |
---|
Expand |
---|
| <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<credential exportReleaseLevel="7.3.0.0" exportTable="ops_credentials" retainSysIds="true" version="28">
<description />
<name>AWS_Secrets_Manager</name>
<opswiseGroups/>
<provider>AWS Secrets Manager</provider>
<providerParameters>
<providerParameter>
<name>ACCESS_KEY_ID</name>
<value>*****</value>
</providerParameter>
<providerParameter>
<name>SECRET_ACCESS_KEY</name>
<value>*****</value>
</providerParameter>
<providerParameter>
<name>REGION</name>
<value>us-east-1</value>
</providerParameter>
<providerParameter>
<name>SECRET_ID</name>
<value>arn:aws:secretsmanager:us-east-1:792840030488:secret:uc-e6wnD3</value>
</providerParameter>
<providerParameter>
<name>SECRET_PASSWORD_KEY</name>
<value>password</value>
</providerParameter>
<providerParameter>
<name>SECRET_PASSPHRASE_KEY</name>
<value></value>
</providerParameter>
<providerParameter>
<name>SECRET_TOKEN_KEY</name>
<value></value>
</providerParameter>
</providerParameters>
<runtimeKeyLocation />
<runtimeUser>secret</runtimeUser>
<sysId>f71d4960469840c2ac3734962405bedd</sysId>
<type>Standard</type>
</credential>
|
|
Expand |
---|
| {
"description": null,
"exportReleaseLevel": "7.3.0.0",
"exportTable": "ops_credentials",
"name": "AWS_Secrets_Manager",
"opswiseGroups": [],
"provider": "AWS Secrets Manager",
"providerParameters": [
{
"name": "ACCESS_KEY_ID",
"value": "*****"
},
{
"name": "SECRET_ACCESS_KEY",
"value": "*****"
},
{
"name": "REGION",
"value": "us-east-1"
},
{
"name": "SECRET_ID",
"value": "arn:aws:secretsmanager:us-east-1:792840030488:secret:uc-e6wnD3"
},
{
"name": "SECRET_PASSWORD_KEY",
"value": "password"
},
{
"name": "SECRET_PASSPHRASE_KEY",
"value": ""
},
{
"name": "SECRET_TOKEN_KEY",
"value": ""
}
],
"retainSysIds": true,
"runtimeKeyLocation": null,
"runtimeUser": "secret",
"sysId": "f71d4960469840c2ac3734962405bedd",
"type": "Standard",
"version": 28
}
|
|
Anchor |
---|
| Read a Credential |
---|
| Read a Credential |
---|
|
Read a Credential
Anchor |
---|
| Read a Credential URI Parameters |
---|
| Read a Credential URI Parameters |
---|
|
Read a Credential: URI Parameters
Parameter | Description | Specifications | Required | Mutually Exclusive With |
---|
credentialid
| ID used within the Controller to identify this Credential. | String; URI parameter. | Y (unless credentialname is specified) | credentialname
|
credentialname
| Name used within the Controller to identify this Credential. | String; URI parameter. | Y (unless credentialid is specified) | credentialid
|
Anchor |
---|
| Read a Credential Example Response |
---|
| Read a Credential Example Response |
---|
|
Read a Credential: Example Response
XML Response | JSON Response |
---|
Expand |
---|
| <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<credential exportReleaseLevel="7.3.0.0" exportTable="ops_credentials" retainSysIds="true" version="28">
<description />
<name>AWS_Secrets_Manager</name>
<opswiseGroups/>
<provider>AWS Secrets Manager</provider>
<providerParameters>
<providerParameter>
<name>ACCESS_KEY_ID</name>
</providerParameter>
<providerParameter>
<name>SECRET_ACCESS_KEY</name>
</providerParameter>
<providerParameter>
<name>REGION</name>
<value>us-east-1</value>
</providerParameter>
<providerParameter>
<name>SECRET_ID</name>
<value>arn:aws:secretsmanager:us-east-1:792840030488:secret:uc-e6wnD3</value>
</providerParameter>
<providerParameter>
<name>SECRET_PASSWORD_KEY</name>
<value>password</value>
</providerParameter>
<providerParameter>
<name>SECRET_PASSPHRASE_KEY</name>
<value></value>
</providerParameter>
<providerParameter>
<name>SECRET_TOKEN_KEY</name>
<value></value>
</providerParameter>
</providerParameters>
<runtimeKeyLocation />
<runtimeUser>secret</runtimeUser>
<sysId>f71d4960469840c2ac3734962405bedd</sysId>
<type>Standard</type>
</credential>
|
|
Expand |
---|
| {
"description": null,
"exportReleaseLevel": "7.3.0.0",
"exportTable": "ops_credentials",
"name": "AWS_Secrets_Manager",
"opswiseGroups": [],
"provider": "AWS Secrets Manager",
"providerParameters": [
{
"name": "ACCESS_KEY_ID",
"value": null
},
{
"name": "SECRET_ACCESS_KEY",
"value": null
},
{
"name": "REGION",
"value": "us-east-1"
},
{
"name": "SECRET_ID",
"value": "arn:aws:secretsmanager:us-east-1:792840030488:secret:uc-e6wnD3"
},
{
"name": "SECRET_PASSWORD_KEY",
"value": "password"
},
{
"name": "SECRET_PASSPHRASE_KEY",
"value": ""
},
{
"name": "SECRET_TOKEN_KEY",
"value": ""
}
],
"retainSysIds": true,
"runtimeKeyLocation": null,
"runtimeUser": "secret",
"sysId": "f71d4960469840c2ac3734962405bedd",
"type": "Standard",
"version": 28
}
|
|
Test Provider
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 |
---|
Expand |
---|
| <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<command-response>
<type>credential_provider_test</type>
<success>true</success>
<info>Credential provider test completed successfully for "My_AWS_Secret".</info>
<errors></errors>
</command-response>
|
Expand |
---|
| <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<command-response>
<type>credential_provider_test</type>
<success>false</success>
<info></info>
<errors>The security token included in the request is invalid.</errors>
</command-response>
|
|
Expand |
---|
|
{
"type": "credential_provider_test",
"success": true,
"info": "Credential provider test completed successfully for \"My_AWS_Secret\".",
"errors": ""
}
|
Expand |
---|
|
{
"type": "credential_provider_test",
"success": false,
"info": "",
"errors": "The security token included in the request is invalid."
}
|
|