Security Controls REST API

Home 

Credentials

Credentials consist of a user name and password pair. They are used to access specified target machines in order to perform scans and push any necessary files. You can define new scan credentials, locate existing credentials and delete credentials.

You can also add session credentials for the current user. This is required to initialize the Security Controls credential store. It also eliminates the need for delegation when performing patch scan and patch deployment operations remotely via the REST API.

Here are some important notes about session credentials:

If you manage user credentials remotely, you must initialize a session credential.

The session credential password must be the same as the Windows user account that is used to authenticate to the REST API.

There is not a session credential timeout.

It is safe to initialize the session credential multiple times. If it already exists, the REST API will respond with a 409 Conflict response status code. This can safely be ignored.

To reset the session credential you must delete it and then add it back.

Base URL

        https://<consoleFQDN:port>/st/console/api/v1.0/credentials
        https://<consoleFQDN:port>/st/console/api/v1.0/sessioncredentials

Supported Requests

Method URL Input Return

DELETE

https://<consoleFQDN:port>/st/console/api/v1.0/credentials/{credential id}

 

Success code

https://<consoleFQDN:port>/st/console/api/v1.0/sessioncredentials

  Success code

GET

https://<consoleFQDN:port>/st/console/api/v1.0/credentials

 

User credential list

https://<consoleFQDN:port>/st/console/api/v1.0/credentials/{credential id}

 

UserCredential

https://<consoleFQDN:port>/st/console/api/v1.0/credentials/{credential name}

 

UserCredential

     

POST

https://<consoleFQDN:port>/st/console/api/v1.0/credentials

Credentials Body

UserCredential

https://<consoleFQDN:port>/st/console/api/v1.0/sessioncredentials

Session Body  

PUT

https://<consoleFQDN:port>/st/console/api/v1.0/credentials/{credential id}

Credentials Body

Success code

Input Model

Session Body

Name Description

cipherText

Sets the encrypted password. The type of encryption is determined by ProtectionMode and SessionKey. Mutually exclusive with ClearText.

clearText

Sets the unencrypted password. Mutually exclusive with CipherText.

protectionMode

The type of data protection applied to the password for at-rest security. The valid options are:

None: This is the default

Local DPApi: Will not work remotely

SessionKey: Protected with an RSA-encrypted session key

sessionKey

Defines an encrypted session key used to protect the password in transit and at rest. It contains the following fields:

algorithmIdentifier: Required. The algorithm URI identifier. Valid values vary based on platform, FIPS compliance and the availability of crypto providers. The best practice is AES.

encryptedKey: Required. The base64-encoded, RSA-encrypted session key.

iv: The base64-encoded, unencrypted initialization vector used with the session key. It is used to seed the security algorithm.

Credentials Body

Name Required? Type Default Value Description

name

Yes

String

None

Provide a friendly name for this credential that describes exactly where it should be used.

password

Yes

Password

None

Provides the password that is associated with the UserName.

userName

Yes

String

None

Provide a user name that has access to the desired machines.

Password

Name Description

cipherText

Sets the encrypted password. The type of encryption is determined by ProtectionMode and SessionKey. Mutually exclusive with ClearText.

clearText

Sets the unencrypted password. Mutually exclusive with CipherText.

protectionMode

The type of data protection applied to the password for at-rest security. The valid options are:

None: This is the default

Local DPApi: Will not work remotely

SessionKey: Protected with an RSA-encrypted session key

sessionKey

Defines an encrypted session key used to protect the password in transit and at rest. It contains the following fields:

algorithmIdentifier: Required. The algorithm URI identifier. Valid values vary based on platform, FIPS compliance and the availability of crypto providers. The best practice is AES.

encryptedKey: Required. The base64-encoded, RSA-encrypted session key.

iv: The base64-encoded, unencrypted initialization vector used with the session key. It is used to seed the security algorithm.

Example

Find all credentials created by the current user

GET Request

https://<consoleFQDN:port>/st/console/api/v1.0/credentials

Sample Response

{

"count": 1,

"value": [

{

"id": "01234567-89AB-CDEF-0123-456789ABCDEF",

"links": {

"self": {

"href": "https://device-name.fakedomain.com:3121/st/console/api/v1.0/credentials/01234567-89AB-CDEF-0123-456789ABCDEF"

}

},

"name": "JoesCreds",

"userName": "joe.coder"

}

]

}

Other Request Examples

Add a credential using a clear text password

The password is only in clear text in memory. Passwords sent over the network are encrypted via TLS and are always encrypted in storage.

POST Request

https://<consoleFQDN:port>/st/console/api/v1.0/credentials

{

"name": "SampleName",

"password":{"ClearText": "SamplePW"},

"userName": "SampleName"

}

Add a credential using a secure password

This follows the security best practices by encrypting the password while it is in memory. As in the clear text example above, passwords sent over the network are encrypted via TLS and are always encrypted in storage.

POST Request

https://<consoleFQDN:port>/st/console/api/v1.0/credentials

{

"name": "SampleName",

"password": @{ "cipherText": $cipherText; "protectionMode": "SessionKey"; "sessionKey": "AES" },

"userName": "SampleName"

}

For more information, see function Add-Credential in the Start-to-Finish Example.

Add a session credential using a secure password

This follows the security best practices by encrypting the password while it is in memory. As in the clear text example above, passwords sent over the network are encrypted via TLS and are always encrypted in storage.

POST Request

https://<consoleFQDN:port>/st/console/api/v1.0/sessioncredentials

{

"cipherText": $cipherText; "protectionMode": "SessionKey"; "sessionKey": "AES"

}

For more information, see function Add-Credential in the Start-to-Finish Example.

Find the credential named SampleCred

GET Request

https://<consoleFQDN:port>/st/console/api/v1.0/credentials?name=SampleCred

Find the credential with ID 01234567-89AB-CDEF-0123-456789ABCDEF

GET Request

https://<consoleFQDN:port>/st/console/api/v1.0/credentials/01234567-89AB-CDEF-0123-456789ABCDEF

Delete the credential with ID 01234567-89AB-CDEF-0123-456789ABCDEF

DELETE Request

https://<consoleFQDN:port>/st/console/api/v1.0/credentials/01234567-89AB-CDEF-0123-456789ABCDEF

 

Output Model

SessionCredential

Name Type Description

created

Boolean

Status success indicator.

UserCredential

Name Type Description

name

String

A friendly name for this credential that describes exactly where it should be used.

password

Password

The password that is associated with the UserName.

userName

String

A user name that has access to the desired machines.

id

Guid

The unique credential identifier that was automatically assigned to the credential. This is read only.

links

Links

Shows the related URL for the credential.


Was this article useful?    

The topic was:

Inaccurate

Incomplete

Not what I expected

Other