Credential Web Services

Owned by Former user (Deleted)
Last updated: May 03, 2023 by Stonebranch
16 min read

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

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.

Create a Credential: Example Request


XML Request

JSON Request
 XML 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>
 JSON 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
}

Credential Properties

Properties

UI Field Name

Description

Specifications

Required

description

Description

User-defined; description of this record.


N

exportReleaseLevel

 n/a

Universal Controller release that the record was exported from.

 read only N

exportTable

 n/a Record table information. read only N

name

Name

Name used within the Controller to identify this Credential.

Maximum 40 alphanumerics.

Y

opswiseGroups

Member of Business Services

Business Services that this record belongs to.
 
Format:
 
XML


<opswiseGroups>
      <opswiseGroup>group1</opswiseGroup>
      <opswiseGroup>group2</opswiseGroup>
</opswiseGroups>

 
JSON


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



XML
<providerParameters>
    <providerParameter>
        <name>PARAMETER_1</name>
        <value>VALUE_1</value>
    </providerParameter>
    <providerParameter>
        <name>PARAMETER_2</name>
        <value>VALUE_2</value>
    </providerParameter>
</providerParameters>
JSON
"providerParameters": [
	{
		"name": "PARAMETER_1",
		"value": "VALUE_1"
	},
	{
		"name": "PARAMETER_2",
		"value": "VALUE_2"
	}
]

Y
(if provider is not Universal Controller)

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

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

runtimePassPhrase

Pass Phrase (SFTP only)

Pass phrase for the Runtime User's SSL/TLS Private key file.


N

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

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

runtimeUser

Runtime User

Runtime user ID, including an LDAP- or AD-formatted user ID, under which the job will be run.


Y

sysId

n/a

System ID field in the database for this Credential record.

Persisted only if retainSysIds is set to true.

N

type

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 

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)

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.

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

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
 XML 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>
 JSON 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
}

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

Modify a Credential: Example Request

XML Request

JSON Request
 XML 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>
 JSON 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
}

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

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

Read a Credential: Example Response

XML Response

JSON Response
 XML 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>
 JSON 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
 XML 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>
 XML 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>
 JSON Response

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

 JSON Response

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