REST API Shell Scripts

Getting Started Guide using REST APIs in Shell with Privileged Access Management.

This page outlines several specific scenarios in which REST APIs in PAM can be called using Shell scripts.

Please note that security is strictly enforced, so ensure the account executing the scripts has the appropriate permissions to access the objects in PAM.

In addition to this detailed guide you can also view the list of other functions you can call using REST API by navigating to Administration > Settings > Application Nodes > API Documentation.

Looking for REST API examples using other scripts? Click PowerShell examples, VBScript examples or Python examples for additional information.

The following scripts are provided as an example of what is possible, however they can and should be customized to meet your requirements including outside script integration, formatting and proper error handling.

Please note that our examples include use of curl for execution and jq for JSON parsing. Ensure these packages are deployed prior to executing the scripts or customize them to fit your needs.

Create a Record
Create a Folder
Retrieve Root Folder
List Folder Content
Retrieve a Record
Retrieve a Record with Password (Unlock)
Retrieve a Record Field (Unlock)
Update a Record
Update One Record Field
Download a File
Share a Record or Folder
Delete a Record
Search for Objects (Record or Folder)
List Record Types
Database Export (Decrypted)
Database Export (Encrypted)
Database Import
API Token
Secure Authentication

Create a Record

Provides the ability to create a new record with the defined parameters.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
folderId="183320"   # ID of Parent Folder
typeId="1724"   #  ID of Record Type
recordName="Record Name"   # Record Name (required)
recordDescription="Record Description"  # Record Description (optional)

rhost="host.company.com"   # Host URL
rport="22"   # Host Port
ruser="user"   # Host User
rpassword="myPassw0rd"   # Host Password
rparameters={\"Host\":\"$rhost\",\"Port\":\"$rport\",\"User\":\"$ruser\",\"Password\":\"$rpassword\"}

curl -s $auth -H "Accept: application/json" -H "Content-Type:application/x-www-form-urlencoded" -H "X-XSRF-TOKEN: $apitoken" -X POST  \
--data "name=$recordName&description=$recordDescription" --data-urlencode "custom=$rparameters" \
$url/rest/record/new/$folderId/$typeId

echo Done

Create a Folder

Provides the ability to create a new folder with the defined parameters.

Copy

1
2
3
4
5
6
7
8
folderId="183320"   # ID of Parent Folder
folderName="Folder Name"   # Folder Name (required)
folderDescription="Folder Description"   # Folder Description (optional)

curl -s $auth -H "Accept: application/json" -H "Content-Type:application/json" -H "X-XSRF-TOKEN: $apitoken" -X POST  \
--data "{\"name\":\"$folderName\",\"description\":\"$folderDescription\"}" $url/rest/folder/create/$folderId

echo Done

Retrieve Root Folder

Provides the ability to retrieve the Root Folder (All Records) and its parameters including ID.

Copy

1
2
3
4
5
6
7
rootFolder=$(curl -s $auth $url/rest/folder/root)

rootFolderId=$(echo $rootFolder | jq -r '.id')

#echo $rootFolder   # Retrieve all Root Folder parameters
echo id:$rootFolderId   # Retrieve Root Folder ID
echo Done

List Folder Content

Provides the ability to list all content of the specified folder.

Copy

1
2
3
4
5
6
7
8
9
10
folderId="183320"    # Folder ID

allContent=$(curl -s $auth $url/rest/folder/list/$folderId)

allNamesOnly=$(echo $allContent | jq '.[] | .name, .id')

#echo $allContent    # Get all Content parameters
echo $allNamesOnly    # Get all Content "Names" and ID only

echo Done

Retrieve a Record

Provides the ability to retrieve the parameters of an existing record excluding the password.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
recordId="168351"   # Record ID

record=$(curl -s $auth $url/rest/record/get/$recordId)
recordname=$(echo $record | jq -r '.name')
check_status "Failed to unlock record"

recorduser=$(get_custom "$record" "User")
check_status "Failed to parse response"

echo $recordname: $recorduser
echo $record
echo Done

Retrieve a Record with Password Unlock

Provides the ability to retrieve the parameters of an existing record including the password.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
recordId="168351"   # Record ID

record=$(curl -s $auth $url/rest/record/unlock/$recordId)
recordname=$(echo $record | jq -r '.name')
check_status "Failed to unlock record"

recorduser=$(get_custom "$record" "User")
recordpassword=$(get_custom "$record" "Password")
check_status "Failed to parse response"

echo $recordname: $recorduser / $recordpassword
echo Done

Retrieve a Record Field Unlock

Provides the ability to retrieve a single parameter from a record’s field including the password.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
recordId="168351"   # Record ID
$field="Password"   # The (internal) Name of the field

record=$(curl -s $auth $url/rest/record/unlock/$recordId/$field)
check_status "Failed to unlock record"

recorduser=$(get_custom "$record" "User")
recordpassword=$(get_custom "$record" "Password")
check_status "Failed to parse response"

echo $field: $record
echo Done

Update a Record

Provides the ability to update an existing record.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
recordId="183323"   # Record ID
recordName="Updated Name"   # Updated Record Name
recordDescription="Updated Description"   # Updated Record Description

rhost="host1.company.com"   # Updated Host URL
rport="3389"   # Updated Host Port
ruser="user1"   # Updated Host User
rpassword="myPassw0rd1"   # Updated Host Password
rparameters={\"Host\":\"$rhost\",\"Port\":\"$rport\",\"User\":\"$ruser\",\"Password\":\"$rpassword\"}

curl -s $auth -H "Accept: application/json" -H "Content-Type:application/x-www-form-urlencoded" -H "X-XSRF-TOKEN: $apitoken" -X PUT  \
--data "name=$recordName&description=$recordDescription" \
--data-urlencode "custom=$rparameters" \
$url/rest/record/update/$recordId

echo Done

Update One Record Field

Provides the ability to update one record field.

Copy

1
curl -s $auth -H "Accept: application/json" -H "Content-Type: application/json" -H "X-XSRF-TOKEN: $apitoken" -X PUT --data "{\"string\":\"FIELD-VALUE\"}" $base/record/updateField/$recordID/$fieldName

Download a File

Provides the ability to download a file (certificate, SSH key, secured file) associated to a record.

Copy

1
2
3
4
5
6
recordId="183323"   # Record ID
fieldName="Cert"   # Internal Name of Field that contains the file

curl -O -J $auth $url/rest/content/record/$recordId/$fieldName

echo Done

Share a Record or Folder

Provides the ability to share a record or folder with other users or groups.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
shareUser="user"   # Share object with User or Group Login

shareUserParam=$(curl -s $auth $url/rest/user/ensure/$shareUser)
shareUserId=$(echo $shareUserParam | jq -r '.id')

objectId="186460"   # Record or Folder ID to Share
userId=$shareUserId
recordControl="View"   # Permission Options: View / Unlock / Edit / Admin
sessionControl="None"   # Permission Options: None / Recording / Connect
taskControl="None"   # Permission Options: None / Execute / Review / Manage

curl -s $auth -H "X-XSRF-TOKEN: $apitoken" -X POST -d "" $url/rest/permissions/share/$objectId/$userId/$recordControl/$sessionControl/$taskControl

echo Done

Delete a Record

Provides the ability to delete an existing record.

Copy

1
2
3
4
5
6
recordId="186008"   # ID of Record to Delete
folderId="183320"   # Parent Folder ID

curl -s $auth -H "X-XSRF-TOKEN: $apitoken" -X DELETE $url/rest/record/delete/$folderId/$recordId

echo Done

Look up for Objects

Search for Objects Record or Folder.

Provides the ability to search for existing objects, like records or folders, using search query types.

A list of query types can be found here and will allow you to target specific objects like folders, ACLs or shadow accounts. For example, if you use the search term folder:Production, it will return all folders found using the term Production.

Copy

1
2
3
4
5
6
7
8
9
10
searchTerm="object name"   # Value to Search
searchTerm=${searchTerm// /%20}

results=$(curl -s $auth -X GET $url/rest/record/find/View/$searchTerm)
searchResults=$(echo $results | jq '.[] | .name, .id')

echo Results:
echo $searchResults   # Displays results as "Object Name" Object ID
#echo $results   # Displays all parameters of Objects returned in results
echo Search Complete

List Record Types

Provides the ability to output a list of all currently available Record Types.

Copy

1
2
3
4
5
recordTypes=$(curl -s $auth -X GET $url/rest/recordtype/list)
recordTypeNamesId=$(echo $recordTypes | jq '.[] | .name, .id')

echo $recordTypeNamesId   # Output as "Record Type Name" Record Type ID
echo Done

Database Export Decrypted

Provides the ability to output a list of all currently available Record Types.

Copy

1
2
3
curl -s $auth -H "X-XSRF-TOKEN: $apitoken" -X PUT $url/rest/application/export/false

echo Done

Database Export Encrypted

Provides the ability to output a list of all currently available Record Types.

Copy

1
2
3
curl -s $auth -H "X-XSRF-TOKEN: $apitoken" -X PUT $url/rest/application/export/true

echo Done

Database Import

Provides the ability to output a list of all currently available Record Types.

Copy

1
2
3
4
5
exportName="xtamexp-20180313152316-120"   # Export file name

curl -s $auth -H "X-XSRF-TOKEN: $apitoken" -X PUT $url/rest/application/import/$exportName

echo Done

API Token

To provide protection against Cross-Site Request Forgery (CSRF) attacks each PAM API function that changes something in the system (mostly, POST, PUT and DELETE REST methods) requires an API Token passed using X-XSRF-TOKEN header.

To obtain a token, an PAM REST client has to request it from PAM server by calling /rest/user/whoami function that sets XSRF-TOKEN cookie with the value of the token.

Below is the example of Shell function that obtains the API token from PAM server by the server base URL and authentication string. See examples of using this token in the code samples above.

Copy

1
2
3
4
5
6
7
8
9
function api_token {
    base=${1}
    auth=${2}

    whoami=$(curl -D whoami.tmp -s $auth $base/rest/user/whoami)
    apitoken=$(cat whoami.tmp | grep "Set-Cookie" |cut -c 13- | cut -d "=" -f 2 | cut -d ";" -f 1)
    rm whoami.tmp
    echo $apitoken
}

API token enforcement could be disabled by defining parameter xtam.api.token.verification=false

Secure Authentication

PAM provides several methods for authenticating, first is a standard, non-federated username and password login, the second is a form-based login method, the third is a more robust federated login experience that supports multi-factor authentication and additional options and the fourth is using Authentication Tokens.

Depending on how your PAM installation is configured, the following authentication methods will be used.

Standard Authentication (non-federated)

If your login experience to PAM is a simple prompt like the one shown below, then you will use the following to authenticate using our REST APIs.

NoCAS-Login

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
#!/bin/bash

cookies=$(mktemp)
curl_opts="-s"

function cleanup {
    rm -f ${cookies}
}

trap cleanup EXIT

function check_exe() {
  which "$1" >/dev/null 2>&1
  if [ "$?" -ne 0 ]; then
      (>&2 echo "Required executable [$1] not found. Please install it using system package manager.")
      (>&2 echo "Exiting.")
      exit 1
  fi
}

function check_status() {
    if [ $? != 0 ]; then
        echo $1
        exit 1
    fi
}

function cas_auth {
    base=${1}
    cas_base=${2}
    username=${3}
    password=${4}

    # get TGT ticket from Location header
    tgt_location=$(curl ${curl_opts} -X POST -D - ${cas_base}/v1/tickets -d "username=${username}" -d "password=${password}" | grep "^Location" | cut -d":" -f 2- | tr -d \\r\\n)

    if [ -z "${tgt_location}" ]; then
        (>&2 echo "CAS authentication failed: unable to obtain TGT ticket")
        exit 1
    fi

    # get service ticket from TGT
    service_ticket=$(curl ${curl_opts} -X POST ${tgt_location} -d "service=${base}/")

    if [ -z "${service_ticket}" ]; then
        (>&2 echo "CAS authentication failed: unable to exchange TGT to service ticket")
        exit 1
    fi

    # write session cookie to file
    curl $curl_opts --cookie-jar ${cookies} $base/?ticket=$service_ticket

    # print curl auth string to stdout
    echo "--cookie ${cookies}"
}

function get_custom {
    record=$1
    field=$2

    echo $record | jq -r ".custom | fromjson | .${field}"
}

check_exe curl
check_exe jq

url="https://pam.company.com/xtam"   # PAM URL
user="admin"   # PAM User
#password="myPassw0rd"   # Optionally define your PAM User's Password

read -p "Enter $user password: " -s password   # Prompt for PAM User's Password
echo

auth="-u $user:$password"

# Your code starts here

Form-Based Authentication

If your login experience to PAM is a form-based login page like the one shown below, then you will use the following to authenticate using our REST APIs.

FAQ-XTAM-Form-Based-Login-Page

Copy

1
2
3
4
5
6
7
8
9
10
11
url="https://pam.company.com/xtam"   # PAM URL
user="admin"   # PAM User
#password="myPassw0rd"   # Optionally define your PAM User's Password

tc=$(mktemp)
cookies=$(mktemp)
curl -s -X GET -c ${tc} -D - ${base}/rest/user/whoami > /dev/null
curl -s -X POST -b ${tc} -c ${cookies} -D - ${base}/j_security_check -d "j_username=${username}" -d "j_password=${password}" > /dev/null
auth="-b ${cookies}"

# Your code starts here

Federated Authentication

If your login experience to PAM is a federated sign-in page like the one shown below, then you will use the following to authenticate using our REST APIs.

CAS-Login

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
#!/bin/bash

cookies=$(mktemp)
curl_opts="-s"

function cleanup {
    rm -f ${cookies}
}

trap cleanup EXIT

function check_exe() {
  which "$1" >/dev/null 2>&1
  if [ "$?" -ne 0 ]; then
      (>&2 echo "Required executable [$1] not found. Please install it using system package manager.")
      (>&2 echo "Exiting.")
      exit 1
  fi
}

function check_status() {
    if [ $? != 0 ]; then
        echo $1
        exit 1
    fi
}

function cas_auth {
    base=${1}
    cas_base=${2}
    username=${3}
    password=${4}

    # get TGT ticket from Location header
    tgt_location=$(curl ${curl_opts} -X POST -D - ${cas_base}/v1/tickets -d "username=${username}" -d "password=${password}" | grep "^Location" | cut -d":" -f 2- | tr -d \\r\\n)

    if [ -z "${tgt_location}" ]; then
        (>&2 echo "CAS authentication failed: unable to obtain TGT ticket")
        exit 1
    fi

    # get service ticket from TGT
    service_ticket=$(curl ${curl_opts} -X POST ${tgt_location} -d "service=${base}/")

    if [ -z "${service_ticket}" ]; then
        (>&2 echo "CAS authentication failed: unable to exchange TGT to service ticket")
        exit 1
    fi

    # write session cookie to file
    curl $curl_opts --cookie-jar ${cookies} $base/?ticket=$service_ticket

    # print curl auth string to stdout
    echo "--cookie ${cookies}"
}

function get_custom {
    record=$1
    field=$2

    echo $record | jq -r ".custom | fromjson | .${field}"
}

check_exe curl
check_exe jq

url="https://pam.company.com/xtam"   # PAM URL
cas_url="https://pam.company.com/cas"   # PAM Signin Page URL
user="admin"   # PAM User
#password="myPassw0rd"   # Optionally define your PAM User's Password

read -p "Enter $user password: " -s password   # Prompt for PAM User's Password
echo

auth=$(cas_auth $url $cas_url $user $password)

# Your code starts here

Token Authentication

If you are using Authentication Tokens, then you will use the following to authenticate using our REST APIs.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
#!/bin/bash

cookies=$(mktemp)
curl_opts="-s"

function cleanup {
    rm -f ${cookies}
}

trap cleanup EXIT

function check_exe() {
  which "$1" >/dev/null 2>&1
  if [ "$?" -ne 0 ]; then
      (>&2 echo "Required executable [$1] not found. Please install it using system package manager.")
      (>&2 echo "Exiting.")
      exit 1
  fi
}

function check_status() {
    if [ $? != 0 ]; then
        echo $1
        exit 1
    fi
}

function token_auth {
    base=${1}
    cas_base=${2}
    token=${3}

    # get service ticket from TGT 
    hdr=$(curl -si "${cas_base}/login?service=${base}/" -H "token:${token}" | grep "^Location")
    service_ticket=$(echo ${hdr} | cut -d"=" -f 2- | tr -d \\r\\n)

    if [ -z "${service_ticket}" ]; then
        (>&2 echo "CAS authentication failed: unable to exchange token to service ticket")
        exit 1
    fi

    # write session cookie to file
    curl $curl_opts --cookie-jar ${cookies} $base/?ticket=$service_ticket

    # print curl auth string to stdout
    echo "--cookie ${cookies}"
}

function get_custom {
    record=$1
    field=$2

    echo $record | jq -r ".custom | fromjson | .${field}"
}

check_exe curl
check_exe jq

url="https://pam.company.com/xtam"   # PAM URL
cas_url="https://pam.company.com/cas"   # PAM Signin Page URL
token="yourPAMtoken"   # PAM Token

auth=$(token_auth $url $cas_url $token)

# Your code starts here