はじめに
IBM Security Verify Privilege Vault(以下、ISVPV)では、複数のAPI実行方法が提供されています。
今回は、RESTAPIを実行してみました。
- SDK
- REST API
- SOAP API
1.REST APIのガイドについて
最新のガイドは、ISVPVの管理画面を参照します。
https:///SecretServer/app/#/admin/rest-api
古いバージョンについてはマニュアルから参照できます。
https://ibm.docs.thycotic.com/isvp-vault/11.6.x/getting-started-tutorial/15-secret-server-apis-and-cli
2.REST API実行のためのアクセストークン取得
アクセストークンを発行するためのRESTAPIリファレンスです。
https://updates.thycotic.net/secretserver/restapiguide/11.4.2/OAuth/
管理者のID/パスワードを使ってアクセストークンを発行します。
> curl -k -H "Accept: application/json" –H "Content-Type: x-www-forms-urlencoded" -d "username=xxx&password=xxx&grant_type=password" -X POST https://<FQDN>/SecretServer/oauth2/token
アクセストークンをリフレッシュトークンが返ってきます。
アクセストークンは"expires_in":1199 とあるので、約20分有効です。
{"access_token":"Ag~ <割愛> ~Qw","token_type":"bearer","expires_in":1199,"refresh_token":"xE~ <割愛> ~s8_jKs"}
3.REST APIの実行
取得したアクセストークンを使ってRESTAPIを実行してみます。
わかりやすいところで「Get User」を実行してみます。
https://updates.thycotic.net/secretserver/restapiguide/11.4.2/TokenAuth/#tag/Users/operation/UsersService_Get
アクセストークンを渡すときは、"Ag~ <割愛> ~Qw"のダブルコーテーションを除いた値を指定します。
curl -k -H "Accept: application/json" -H "Authorization: Bearer Ag~ <割愛> ~Qw" https://<FQDN>/SecretServer/api/v1/users/
以下のようにユーザー情報が返ってきます。
id=1は内部で予約されているようで、インストール時に登録した管理者には、id=2が採番されていました。
以降順番にidが採番されていました。
{
"filter": {
"searchText": null,
"includeInactive": false,
"domainId": null,
"searchFields": null,
"userIds": null,
"excludeInboxRuleIdSubscribers": null
},
"skip": 0,
"take": 10,
"total": 4,
"pageCount": 1,
"currentPage": 1,
"batchCount": 1,
"prevSkip": 0,
"nextSkip": 10,
"hasPrev": false,
"hasNext": false,
"records": [
{
"id": 2,
"userName": "xxxAdmin",
"displayName": "xxx Admin",
"lastLogin": "2024-02-16T08:04:33",
"created": "2023-12-26T17:23:50",
"enabled": true,
"loginFailures": 0,
"emailAddress": "xxx@xxx.xxx",
"domainId": -1,
"domainName": null,
"isLockedOut": false,
"isApplicationAccount": false,
"twoFactorMethod": "None",
"externalUserSource": "None",
"platformIntegrationType": "None"
}
~~割愛~~
"sortBy": [
{
"name": "DomainId",
"direction": "Asc",
"priority": 0
},
{
"name": "UserName",
"direction": "Asc",
"priority": 1
}
],
"success": true,
"severity": "None"
}
4.実行結果のサンプル
同じ要領でいくつかのAPIをためてみました。
4.1.ユーザー登録
testuser3を登録
curl -k -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer <access_toke> " -X POST https://<FQDN>/SecretServer/api/v1/users --data-raw "{""userName"":""testuser3"",""password"":""P^@ssw0rd1111"",""displayName"":""testuser3"",""enabled"":true}"
実行結果
{
"id": 6,
"personalGroupId": 0,
"userName": "testuser3",
"displayName": "testuser3",
"lastLogin": "0001-01-01T00:00:00",
"created": "2024-02-16T08:05:11.436Z",
"enabled": true,
"loginFailures": 0,
"emailAddress": null,
"slackId": null,
"userLcid": 0,
"domainId": -1,
"lastSessionActivity": null,
"isLockedOut": false,
"radiusUserName": null,
"twoFactor": false,
"radiusTwoFactor": false,
"isEmailVerified": false,
"mustVerifyEmail": false,
"verifyEmailSentDate": "0001-01-01T00:00:00",
"passwordLastChanged": "0001-01-01T00:00:00",
"dateOptionId": -1,
"timeOptionId": -1,
"isEmailCopiedFromAD": false,
"adGuid": null,
"adAccountExpires": "0001-01-01T00:00:00",
"resetSessionStarted": "0001-01-01T00:00:00",
"isApplicationAccount": false,
"oathTwoFactor": false,
"oathVerified": false,
"duoTwoFactor": false,
"fido2TwoFactor": false,
"unixAuthenticationMethod": "Password",
"lockOutReason": null,
"lockOutReasonDescription": null,
"externalUserSource": "None",
"ipAddressRestrictions": null,
"platformIntegrationType": "None"
}
4.2.グループ取得
curl -k -H "Accept: application/json" -H "Authorization: Bearer <access_token>" -X GET https://<FQDN>/SecretServer/api/v1/groups
実行結果
{
"filter": {
"searchText": null,
"platformOnly": null,
"includeInactive": false,
"domainId": null,
"limitToViewableGroups": false,
"excludeInboxRuleIdSubscribers": null
},
"skip": 0,
"take": 10,
"total": 1,
"pageCount": 1,
"currentPage": 1,
"batchCount": 1,
"prevSkip": 0,
"nextSkip": 10,
"hasPrev": false,
"hasNext": false,
"records": [
{
"id": 1,
"name": "All Vault Users",
"enabled": true,
"memberCount": 4,
"domainId": -1,
"domainName": null,
"synchronized": true,
"synchronizeNow": false,
"created": "2023-12-26T17:23:29.863",
"domainGuid": null,
"isPlatform": false
}
],
"sortBy": [],
"success": true,
"severity": "None"
}
4.3.グループ登録
testgroup1を登録
curl -k -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer <access_token>" -X POST https://<FQDN>/SecretServer/api/v1/groups --data-raw "{""name"":""testgroup1"",""enabled"":true}"
実行結果(testgroup1は、id=7が採番)
{
"id": 7,
"name": "testgroup1",
"enabled": true,
"isEditable": true,
"canEditMembers": null,
"created": "2024-02-16T08:33:14.6558453Z",
"domainId": -1,
"synchronized": true,
"synchronizeNow": false,
"domainName": null,
"systemGroup": false,
"adGuid": null,
"hasGroupOwners": false,
"ownerUsers": {},
"ownerGroups": {},
"owners": [],
"ipAddressRestrictions": [],
"isPlatform": false
}
4.4.グループへのユーザー割り当て
インストール時に登録された管理者ユーザー(id=2)を、前の手順で登録したtestgroup1(id=7)に追加。
curl -k -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer <access_token>" -X POST https://<FQDN>/SecretServer/api/v1/groups/7/users --data-raw "{""userid"":""2""}"
実行結果
{
"userId": 2,
"userName": "xxxAdmin",
"userDomainId": -1,
"groupId": 7,
"groupName": "testgroup1",
"groupDomainId": -1
}
4.5.グループへのロール割り当て
curl -k -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer <access_token>" -X POST https://<FQDN>/SecretServer/api/v1/groups/7/roles --data-raw "{""roleIds"":[""1""]}"
実行結果
{
"success": true
}
4.6.Secretの取得
/SecretServer/api/v1/secretsでは、Secret詳細情報(ユーザー名など)は返ってきません。
curl -k -H "Accept: application/json" -H "Authorization: Bearer <access_token>" -X GET https://<FQDN>/SecretServer/api/v1/secrets
実行結果
{
"filter": {
"secretTemplateIds": [
-1
],
"hasLauncher": null,
"extFieldsCombined": null,
"onlyCheckedOutSecrets": null,
"onlySecretsCheckedOutByUser": null,
"secretIds": null,
"searchText": null,
"searchField": null,
"searchFieldSlug": null,
"includeInactive": false,
"includeActive": null,
"includeRestricted": false,
"secretTemplateId": null,
"folderId": null,
"includeSubFolders": false,
"heartbeatStatus": null,
"siteId": null,
"scope": null,
"recentMinDateTime": null,
"recentMaxDateTime": null,
"onlySharedWithMe": null,
"extendedFields": null,
"permissionRequired": null,
"extendedTypeId": null,
"passwordTypeIds": null,
"onlyRPCEnabled": null,
"doubleLockId": null,
"isExactMatch": null,
"allowDoubleLocks": null,
"doNotCalculateTotal": null
},
"skip": 0,
"take": 10,
"total": 1,
"pageCount": 1,
"currentPage": 1,
"batchCount": 1,
"prevSkip": 0,
"nextSkip": 10,
"hasPrev": false,
"hasNext": false,
"records": [
{
"id": 1,
"name": "isvd",
"secretTemplateId": 6007,
"secretTemplateName": "Unix Account (SSH)",
"folderId": 2,
"folderPath": "\\Personal Folders\\xxx Admin01",
"siteId": 1,
"active": true,
"checkedOut": false,
"isRestricted": false,
"isOutOfSync": false,
"outOfSyncReason": "",
"lastHeartBeatStatus": "Pending",
"lastPasswordChangeAttempt": "0001-01-01T00:00:00",
"responseCodes": null,
"lastAccessed": "2024-02-27T06:26:56.857",
"extendedFields": null,
"checkOutEnabled": false,
"autoChangeEnabled": false,
"doubleLockEnabled": false,
"requiresApproval": false,
"requiresComment": false,
"inheritsPermissions": true,
"hidePassword": false,
"createDate": "2024-02-16T09:19:45.153",
"daysUntilExpiration": null,
"hasLauncher": true,
"checkOutUserId": -1,
"checkOutUserName": null
}
],
"sortBy": [],
"success": true,
"severity": "None"
}
4.7.SecretTemplateリストの取得
SecretTemplateを使ってSecretを登録するため、まずは登録したいSecretが利用するSecretTemplate一覧を確認します。
curl -k -H "Accept: application/json" -H "Authorization: Bearer <access_token>" -X GET https://<FQDN>/SecretServer/api/v1/secret-templates-list
実行結果
{
"filter": {
"folderId": null,
"onlyIncludeCreatable": false,
"onlyIncludeTemplatesWithUrl": false
},
"skip": 0,
"take": 1000,
"total": 49,
"pageCount": 1,
"currentPage": 1,
"batchCount": 1,
"prevSkip": 0,
"nextSkip": 1000,
"hasPrev": false,
"hasNext": false,
"records": [
{
"id": 6001,
"name": "Active Directory Account",
"canCreate": true
},
{
"id": 6036,
"name": "Amazon IAM Console Password",
"canCreate": true
}
~~割愛~~
],
"sortBy": [
{
"name": "Name",
"direction": "Asc",
"priority": 1
}
],
"success": true,
"severity": "None"
}
4.8.SecretTemplateの取得
確認したSecretTemplateのうち、Unix Account (SSH)テンプレート(id=6007)の情報を取得します。
curl -k -H "Accept: application/json" -H "Authorization: Bearer <access_token>" -X GET https://<FQDN>/SecretServer/api/v2/secret-templates/6007
実行結果
{
"id": 6007,
"name": "Unix Account (SSH)",
"namePattern": null,
"namePatternErrorMessage": null,
"description": "",
"active": true,
"saveAllNameHistory": false,
"secretNameHistoryLength": 0,
"expirationDays": 30,
"expirationChangeRequiredOnFieldId": null,
"validatePasswordRequirementsOnCreate": false,
"validatePasswordRequirementsOnEdit": false,
"oneTimePasswordEnabled": false,
"oneTimePasswordLength": null,
"oneTimePasswordDuration": null,
"oneTimePasswordHash": null,
"sshKeyFormat": "0",
"sshKeyAlgorithm": "2",
"sshKeySize": "Key2048",
"secretCount": 1,
"permissionRequiredToEditPasswordChangeConfiguration": "Owner"
}
4.9.SecretTemplateを使うときのFields定義の取得
GUIの管理画面からUnix Account (SSH)テンプレートを使ってSecretを登録する際には、ユーザー名、パスワード、マシン情報などを登録します。
登録する属性情報ごとに内部的にidが採番されています。
Secret登録時には、各属性に対応するidを指定する必要があるため、フィールド情報を取得します。
>curl -k -H "Accept: application/json" -H "Authorization: Bearer <access_token>" -X GET https://<FQDN>/SecretServer/api/v1/secret-templates/fields/search?filter.secretTemplateId
=6007
実行結果
{
"filter": {
"secretTemplateId": 6007,
"includeInactive": false
},
"skip": 0,
"take": 10,
"total": 6,
"pageCount": 1,
"currentPage": 1,
"batchCount": 1,
"prevSkip": 0,
"nextSkip": 10,
"hasPrev": false,
"hasNext": false,
"records": [
{
"id": 108,
"name": "Machine",
"slugName": "machine",
"description": "The Server or Location of the Unix Machine.",
"type": "Text",
"required": true,
"historyLength": 2147483647,
"searchable": true,
"editRequiresPermission": "Edit",
"viewingRequiresEdit": false,
"exposeForDisplay": false,
"active": true,
"sortOrder": 1
},
{
"id": 111,
"name": "Username",
"slugName": "username",
"description": "The Unix Machine Username.",
"type": "Text",
"required": true,
"historyLength": 2147483647,
"searchable": true,
"editRequiresPermission": "Edit",
"viewingRequiresEdit": false,
"exposeForDisplay": false,
"active": true,
"sortOrder": 2
},
{
"id": 110,
"name": "Password",
"slugName": "password",
"description": "The password of the Unix Machine.",
"type": "Password",
"required": true,
"historyLength": 2147483647,
"searchable": false,
"editRequiresPermission": "Edit",
"viewingRequiresEdit": false,
"exposeForDisplay": false,
"active": true,
"sortOrder": 3
},
{
"id": 109,
"name": "Notes",
"slugName": "notes",
"description": "Any additional notes.",
"type": "Notes",
"required": false,
"historyLength": 2147483647,
"searchable": true,
"editRequiresPermission": "Edit",
"viewingRequiresEdit": false,
"exposeForDisplay": false,
"active": true,
"sortOrder": 4
},
{
"id": 189,
"name": "Private Key",
"slugName": "private-key",
"description": "The SSH private key.",
"type": "File",
"required": false,
"historyLength": 2147483647,
"searchable": false,
"editRequiresPermission": "Edit",
"viewingRequiresEdit": false,
"exposeForDisplay": false,
"active": true,
"sortOrder": 5
},
{
"id": 190,
"name": "Private Key Passphrase",
"slugName": "private-key-passphrase",
"description": "The passphrase for decrypting the SSH private key.",
"type": "Password",
"required": false,
"historyLength": 2147483647,
"searchable": false,
"editRequiresPermission": "Edit",
"viewingRequiresEdit": false,
"exposeForDisplay": false,
"active": true,
"sortOrder": 6
}
],
"sortBy": [],
"success": true,
"severity": "None"
}
4.10.Secretのデフォルト値(stub)の取得
Unix Account (SSH)テンプレート(id=6007)のStubを取得することで、Secretのデフォルト値を確認できます。
curl -k -H "Accept: application/json" -H "Authorization: Bearer <access_token>" -X GET https://<FQDN>/SecretServer/api/v1/secrets/stub?filter.secrettemplateid=6007
実行結果
{
"id": 0,
"name": null,
"secretTemplateId": 6007,
"folderId": 0,
"active": true,
"items": [
{
"fileAttachmentId": null,
"filename": null,
"itemValue": null,
"fieldId": 108,
"fieldName": "Machine",
"slug": "machine",
"fieldDescription": "The Server or Location of the Unix Machine.",
"isFile": false,
"isNotes": false,
"isPassword": false,
"isList": false,
"listType": "None"
},
{
"fileAttachmentId": null,
"filename": null,
"itemValue": null,
"fieldId": 111,
"fieldName": "Username",
"slug": "username",
"fieldDescription": "The Unix Machine Username.",
"isFile": false,
"isNotes": false,
"isPassword": false,
"isList": false,
"listType": "None"
},
{
"fileAttachmentId": null,
"filename": null,
"itemValue": null,
"fieldId": 110,
"fieldName": "Password",
"slug": "password",
"fieldDescription": "The password of the Unix Machine.",
"isFile": false,
"isNotes": false,
"isPassword": true,
"isList": false,
"listType": "None"
},
{
"fileAttachmentId": null,
"filename": null,
"itemValue": null,
"fieldId": 109,
"fieldName": "Notes",
"slug": "notes",
"fieldDescription": "Any additional notes.",
"isFile": false,
"isNotes": true,
"isPassword": false,
"isList": false,
"listType": "None"
},
{
"fileAttachmentId": null,
"filename": null,
"itemValue": null,
"fieldId": 189,
"fieldName": "Private Key",
"slug": "private-key",
"fieldDescription": "The SSH private key.",
"isFile": true,
"isNotes": false,
"isPassword": false,
"isList": false,
"listType": "None"
},
{
"fileAttachmentId": null,
"filename": null,
"itemValue": null,
"fieldId": 190,
"fieldName": "Private Key Passphrase",
"slug": "private-key-passphrase",
"fieldDescription": "The passphrase for decrypting the SSH private key.",
"isFile": false,
"isNotes": false,
"isPassword": true,
"isList": false,
"listType": "None"
}
],
"launcherConnectAsSecretId": -1,
"checkOutMinutesRemaining": -1,
"checkedOut": false,
"checkOutUserDisplayName": "",
"checkOutUserId": 0,
"isRestricted": false,
"isOutOfSync": false,
"outOfSyncReason": "",
"autoChangeEnabled": false,
"autoChangeNextPassword": null,
"requiresApprovalForAccess": false,
"requiresComment": false,
"checkOutEnabled": false,
"checkOutIntervalMinutes": -1,
"checkOutChangePasswordEnabled": false,
"accessRequestWorkflowMapId": null,
"proxyEnabled": false,
"sessionRecordingEnabled": false,
"restrictSshCommands": false,
"jumpboxRouteId": null,
"allowOwnersUnrestrictedSshCommands": false,
"isDoubleLock": false,
"doubleLockId": 0,
"enableInheritPermissions": true,
"passwordTypeWebScriptId": -1,
"siteId": -1,
"enableInheritSecretPolicy": false,
"secretPolicyId": -1,
"lastHeartBeatStatus": "Pending",
"lastHeartBeatCheck": "0001-01-01T00:00:00",
"failedPasswordChangeAttempts": 0,
"lastPasswordChangeAttempt": "0001-01-01T00:00:00",
"secretTemplateName": "Unix Account (SSH)",
"responseCodes": [],
"webLauncherRequiresIncognitoMode": false
}
4.11.SecretTemplateを使ったSecretの登録
Unix Account (SSH)テンプレート(id=6007)を使って新しくSecretを登録します。
curl -k -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer <access_token>" -X POST https://<FQDN>/SecretServer/api/v1/secrets -d @c:\temp\createsecret.json
指定したJSONファイル
{
"name":" isvd2",
"secretTemplateId": 6007,
"siteId": 1,
"items": [
{
"fieldDescription": "The Server or Location of the Unix Machine.",
"fieldId": 108,
"fieldName": "Machine",
"fileAttachmentId": 0,
"filename": "string",
"isFile": false,
"isList": false,
"isNotes": false,
"isPassword": false,
"itemId": 0,
"itemValue": "x.x.x.x",
"listType": "Generic",
"slug": "machine"
},
{
"fieldDescription": "The Unix Machine Username.",
"fieldId": 111,
"fieldName": "Username",
"fileAttachmentId": 0,
"filename": "string",
"isFile": false,
"isList": false,
"isNotes": false,
"isPassword": false,
"itemId": 0,
"itemValue": "root",
"listType": "Generic",
"slug": "username"
},
{
"fieldDescription": "The password of the Unix Machine.",
"fieldId": 110,
"fieldName": "Password",
"fileAttachmentId": 0,
"filename": "string",
"isFile": false,
"isList": false,
"isNotes": false,
"isPassword": true,
"itemId": 0,
"itemValue": "admin",
"listType": "Generic",
"slug": "password"
}
]
}
実行結果
{
"id": 2,
"name": " isvd2",
"secretTemplateId": 6007,
"folderId": -1,
"active": true,
"items": [
{
"itemId": 7,
"fileAttachmentId": null,
"filename": null,
"itemValue": "x.x.x.x",
"fieldId": 108,
"fieldName": "Machine",
"slug": "machine",
"fieldDescription": "The Server or Location of the Unix Machine.",
"isFile": false,
"isNotes": false,
"isPassword": false,
"isList": false,
"listType": "None"
},
{
"itemId": 8,
"fileAttachmentId": null,
"filename": null,
"itemValue": "root",
"fieldId": 111,
"fieldName": "Username",
"slug": "username",
"fieldDescription": "The Unix Machine Username.",
"isFile": false,
"isNotes": false,
"isPassword": false,
"isList": false,
"listType": "None"
},
{
"itemId": 9,
"fileAttachmentId": null,
"filename": null,
"itemValue": "admin",
"fieldId": 110,
"fieldName": "Password",
"slug": "password",
"fieldDescription": "The password of the Unix Machine.",
"isFile": false,
"isNotes": false,
"isPassword": true,
"isList": false,
"listType": "None"
},
{
"itemId": 10,
"fileAttachmentId": null,
"filename": null,
"itemValue": "",
"fieldId": 109,
"fieldName": "Notes",
"slug": "notes",
"fieldDescription": "Any additional notes.",
"isFile": false,
"isNotes": true,
"isPassword": false,
"isList": false,
"listType": "None"
},
{
"itemId": 11,
"fileAttachmentId": null,
"filename": null,
"itemValue": "*** Not Valid For Display ***",
"fieldId": 189,
"fieldName": "Private Key",
"slug": "private-key",
"fieldDescription": "The SSH private key.",
"isFile": true,
"isNotes": false,
"isPassword": false,
"isList": false,
"listType": "None"
},
{
"itemId": 12,
"fileAttachmentId": null,
"filename": null,
"itemValue": "",
"fieldId": 190,
"fieldName": "Private Key Passphrase",
"slug": "private-key-passphrase",
"fieldDescription": "The passphrase for decrypting the SSH private key.",
"isFile": false,
"isNotes": false,
"isPassword": true,
"isList": false,
"listType": "None"
}
],
"launcherConnectAsSecretId": -1,
"checkOutMinutesRemaining": 0,
"checkedOut": false,
"checkOutUserDisplayName": "",
"checkOutUserId": 0,
"isRestricted": false,
"isOutOfSync": false,
"outOfSyncReason": "",
"autoChangeEnabled": false,
"autoChangeNextPassword": null,
"requiresApprovalForAccess": false,
"requiresComment": false,
"checkOutEnabled": false,
"checkOutIntervalMinutes": -1,
"checkOutChangePasswordEnabled": false,
"accessRequestWorkflowMapId": -1,
"proxyEnabled": false,
"sessionRecordingEnabled": false,
"restrictSshCommands": false,
"jumpboxRouteId": null,
"allowOwnersUnrestrictedSshCommands": false,
"isDoubleLock": false,
"doubleLockId": 0,
"enableInheritPermissions": false,
"passwordTypeWebScriptId": -1,
"siteId": 1,
"enableInheritSecretPolicy": false,
"secretPolicyId": -1,
"lastHeartBeatStatus": "Pending",
"lastHeartBeatCheck": "0001-01-01T00:00:00",
"failedPasswordChangeAttempts": 0,
"lastPasswordChangeAttempt": "0001-01-01T00:00:00",
"secretTemplateName": "Unix Account (SSH)",
"responseCodes": [],
"webLauncherRequiresIncognitoMode": false
}
最後に
IBM Security Verify Privilege VaultのRESTAPIを試してみました。ご参考になれば幸いです。
OEM元のDelinea社ではPostmanのjsonファイルを提供しています。
Postmanを利用できる環境でしたらこちらをご利用ください。
https://github.com/DelineaXPM/secretserver-postman