Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Panel
Table of Contents
maxlevel1

Anchor
Overview
Overview

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


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

  • Status 200 /OK
    Successfully created the credential with sysId {sysId}.
  • Status 400 /Bad Request
    Create credential failed. A duplicate value has been detected. Name must be unique.

Anchor
Create a Credential Example Request
Create a Credential Example Request

Create a Credential: Example Request


XML Request

JSON Request


Expand
titleXML Request
<?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
titleJSON Request
{
    "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 onlyN

Anchor
exportTable - CRED
exportTable - CRED
exportTable

n/aRecord table information.read onlyN

Anchor
name - CRED
name - CRED
name

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
<opswiseGroups>
      <opswiseGroup>group1</opswiseGroup>
      <opswiseGroup>group2</opswiseGroup>
</opswiseGroups>

 
JSON


Panel
"opswiseGroups": ["group1","group2"]



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
languagexml
titleXML




Code Block
languagexml
titleJSON




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 - CRED 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
titleNote

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 Web Services#Change Runtime Password of Credentials.

  • 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 Functions#Return Token of a Credential 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

Anchor
sysId - CRED
sysId - CRED
sysId

n/a

System ID field in the database for this Credential record.

Persisted only if retainSysIds is set to true.

N

Anchor
type - CRED
type - CRED
type

Type

Type of Credential.
 


Note
titleNote:

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:

  • 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.

  • If left unspecified, the password will evaluate to the entire secret value.

SECRET_PASSPHRASE_KEY

false

Specifies the key for the passphrase in the JSON structure.

  • If left unspecified, the passphrase will be undefined.

SECRET_TOKEN_KEY

false

Specifies the key for the token in the JSON structure.

  • If left unspecified, the token will be undefined.

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.

  • https://<your-key-vault-name>.vault.azure.net

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.

  • Only one of CLIENT_SECRET, CLIENT_ASSERTION, PEM_CERTIFICATE, or PFX_CERTIFICATE can be specified.

CLIENT_ASSERTION


The client assertion used to authenticate.

  • Only one of CLIENT_SECRET, CLIENT_ASSERTION, PEM_CERTIFICATE, or PFX_CERTIFICATE can be specified.

PEM_CERTIFICATE


The path of the PEM certificate used for authenticating.

  • Only one of CLIENT_SECRET, CLIENT_ASSERTION, PEM_CERTIFICATE, or PFX_CERTIFICATE can be specified.

PFX_CERTIFICATE


The path of the PFX certificate used for authenticating.

  • Only one of CLIENT_SECRET, CLIENT_ASSERTION, PEM_CERTIFICATE, or PFX_CERTIFICATE can be specified.

PFX_CERTIFICATE_PASSWORD


The password for the PFX certificate.

  • Required if the PFX_CERTIFICATE is specified.

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


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

  • Status 200 /OK
    Credential deleted successfully.
  • Status 400 /Bad Request
    Mutual exclusion violation. Cannot specify credentialname and credentialid at the same time.
  • Status 404 /Not Found
    A credential with {name/id} "test" does not exist.

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


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.

Anchor
List Credentials Example Response
List Credentials Example Response

List Credentials: Example Response

XML Response

JSON Response


Expand
titleXML Response
<?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
titleJSON Response
{
    "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


Description

URI

http://host_name/uc/resources/credential

HTTP Method

PUT

Description

Modifies the Credential specified by the sysId.

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

  • Status 200 /OK
    Successfully updated the credential with sysId <sysId> to version <version>.

Anchor
Modify a Credential Example Request
Modify a Credential Example Request

Modify a Credential: Example Request

XML Request

JSON Request


Expand
titleXML Request
<?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
titleJSON Request
{
    "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

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.

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
titleXML Response
<?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
titleJSON Response
{
    "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 


 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

  • Status 200

    • Successfully created the credentialname with id {uuid}.

  • Status 400

    • Error message.

  • Status 403

    • Operation prohibited due to security constraints.

  • Status 404

    • A credential with name “{name}” does not exist.

    • A credential with id "{uuid}" does not exist.

  • Status 500

    • Unexpected request failure. See log(s) for more details.

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
titleXML Response
<?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
titleXML Response
<?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
titleJSON Response

{
    "type": "credential_provider_test",
    "success": true,
    "info": "Credential provider test completed successfully for \"My_AWS_Secret\".",
    "errors": ""
}


Expand
titleJSON Response

{
    "type": "credential_provider_test",
    "success": false,
    "info": "",
    "errors": "The security token included in the request is invalid."
}