IBM Security Secret Server

APIs
—
Support Webinar

Grey Thrasher
[email protected]
Announcing IBM VIP Rewards
Engage. Earn points. Get Rewards.

IBM VIP Rewards is a way to engage with and

recognize the ways that you, the client, add
value to IBM. Join IBM VIP Rewards for
Learn more… Security…
Complete fun challenges and get rewarded for ibm.biz/vip-rewards ibm.biz/JoinIBMVIPRewards
interacting with IBM, learning new -Security
technologies and sharing your knowledge.
IBM Security Learning Academy
http://ibm.biz/ISSS-LearningAcademy

• Courses
• Videos
• Hands-on Labs
• Live Events
• Badges
Learning at no cost.

New content published daily.

Panel

• Presenter:
Grey Thrasher - Identity Support Technical Lead

• Panelists:
Daryl Romano - Identity Support
Jensen Toma - Identity Support
Gary Sedler - Identity Support
Mohammad Khan - Identity Support
Agenda

• Introduction
• REST
• SDK
• Demo
• Q/A
Introduction
Introduction
• API: Application Programming Interface

- Provides a way for customers/vendors to create custom

scripts/applications/etc that can interact with an application.
• IBM Security Secret Server API Options:

- Java, SOAP, REST, SDK

• Objects/Activities available in the APIs:
- Authentication
- Secrets
- Folders
- Users
- Reports
- Launchers…
Introduction
Web Services must be enabled in ISSS
REST
• Overview
• Coding
• Troubleshooting
• Documentation
What is REST?
REpresentational State Transfer
• Every Service is identified by a URI
• Uses standard HTTP methods for CRUD:

😴
• POST
• GET
• PUT
• DELETE
• Stateless: Each request is independent
• Request Data is typically JSON,
x-www-form-urlencoded and/or query parameters
• Response Data is typically JSON
 {
"id": 12,
"name": "SDK Test",

Coding/Usage:
"secretTemplateId": 2,
"folderId": 7,
"active": true,
"items": [
{
"itemId": 53,
"fileAttachmentId": null,
"filename": null,
"itemValue": "fooserver",
"fieldId": 60,
"fieldName": "Resource",
"slug": "resource",
• Authentication: returns Token to be used in all other requests "fieldDescription": "The URL or location where information is being secured.",
"isFile": false,
"isNotes": false,
"isPassword": false
},

POST: https://ss/SecretServer/oauth2/token {
{
"itemId": 54,
"access_token": "AgLlj_5QYUil….", "fileAttachmentId": null,
Headers: Content-Type: application/x-www-form-urlencoded "token_type": "bearer",
"filename": null,
"itemValue": "sdktest",
"fieldId": 61,
Body: username, password, grant_type=password "expires_in": 1200
}
"fieldName": "Username",
"slug": "username",
"fieldDescription": "The name assocated with the password.",
"isFile": false,
"isNotes": false,
"isPassword": false
• Get Secret: },
{
"itemId": 55,
"fileAttachmentId": null,
"filename": null,

GET: https://ss/SecretServer/api/v1/secrets/<secretID> "itemValue": "#5r5^(h^jLzK",

"fieldId": 7,
"fieldName": "Password",

Authorization: Bearer <token> "slug": "password",

"fieldDescription": "The password used to access information.",
"isFile": false,
Headers: Accept: application/json "isNotes": false,
"isPassword": true
},
{
"itemId": 56,
"fileAttachmentId": null,
• Add Secret Permission: "filename": null,
"itemValue": "This is a test secret to use with SDK",
"fieldId": 8,
"fieldName": "Notes",
"slug": "notes",

POST: https://ss/SecretServer/api/v1/secrets-permissions
"fieldDescription": "Any comments or additional information for the secret.",
"isFile": false,
"isNotes": true,

Authorization: Bearer <token> "isPassword": false

}
],

Headers: "launcherConnectAsSecretId": -1,

"checkOutMinutesRemaining": 0,
"checkedOut": false,
Accept: application/json "checkOutUserDisplayName": "",
"checkOutUserId": -1,
"isRestricted": false,
Content-Type: application/json "isOutOfSync": false,
"outOfSyncReason": "",
"autoChangeEnabled": false,
Body: "autoChangeNextPassword": null,
"requiresApprovalForAccess": false,

{
"requiresComment": false,
"checkOutEnabled": false,
"checkOutIntervalMinutes": -1,

“secretId” : 15,
"checkOutChangePasswordEnabled": false,
"accessRequestWorkflowMapId": -1,
"proxyEnabled": true,

“userId” : 12, "sessionRecordingEnabled": false,

"restrictSshCommands": false,
"allowOwnersUnrestrictedSshCommands": false,

“secretAccessId” : null, "isDoubleLock": false,

"doubleLockId": -1,
"enableInheritPermissions": false,
“secretAccessName” : “View” "passwordTypeWebScriptId": -1,
"siteId": 1,
"enableInheritSecretPolicy": true,
} "secretPolicyId": -1,
"lastHeartBeatStatus": "Pending",
"lastHeartBeatCheck": "0001-01-01T00:00:00",
"failedPasswordChangeAttempts": 0,
"lastPasswordChangeAttempt": "0001-01-01T00:00:00",
"secretTemplateName": "Password",
"responseCodes": []
}
Coding: Node.js var express = require('express');
var request = require('request');
var router = express.Router();

router.post('/', (req, res) => {

console.log("login.js: in login...");

Authentication var username = req.body.username;

var password = req.body.password;

//auth to SS

Define the data for the const options = {

method: "POST",
url: process.env.SS_URL + "/oauth2/token",
call to /oauth2/token to headers: {
'cache-control': 'no-cache’,
authenticate },
'Content-Type': 'application/x-www-form-urlencoded’

form: {
username: username,
password: password,
grant_type: 'password’
}
};

//trust self-signed cert

process.env["NODE_TLS_REJECT_UNAUTHORIZED"] = 0;

request(options, (error, response, body) => {

if(error){
throw new Error(error);
res.send("Login failed: " + error);
} else {

Execute the call to const jsonBody = JSON.parse(body);

console.log(JSON.stringify(jsonBody));

/oauth2/token to if(jsonBody.hasOwnProperty("error")){
console.log("login error: " + jsonBody.error);
res.send('<p><strong>Login Failed...please try again: </strong><a href="/">Login</a></p>’);
authenticate and save the } else {
req.session.sstoken = jsonBody.access_token;
Token to the Session console.log("login.js: login success. here's the token: " + jsonBody.access_token);
req.session.save();
res.redirect('./menu’);
}
}
});
});

module.exports = router;
Coding: Node.js
Get Secrets var express = require('express');
var request = require('request');
var router = express.Router();

router.get('/', (req, res) => {

//auth to SS
const options = {
method: "GET",
Define the data for the url: process.env.SS_URL + "/api/v1/secrets",
headers: {
pass to /api/v1/secrets 'cache-control': 'no-cache’,
'Accept': 'application/json’,
'Authorization': 'Bearer ' + req.session.sstoken
}
};

//trust self-signed cert

process.env["NODE_TLS_REJECT_UNAUTHORIZED"] = 0;

request(options, (error, response, body) => {

Execute the call to if(error){

throw new Error(error);
res.send("Login failed: " + error);
/api/v1/secrets to retrieve } else {
const jsonBody = JSON.parse(body);
all Secrets and pass to the console.log("JSON Body from menu.js: " + body);
res.render('./menu',{app_title: process.env.APP_TITLE, secrets: jsonBody.records, ssurl: process.env.SS_URL});

client });
}

});

module.exports = router;
Troubleshooting
• Server:

• IIS (C:\inetpub\logs\) and SS logs (C:\inetpub\wwwroot\SecretServer\log\)

• Audit logs for associated Object (e.g. Secret > Audit)
• Client:

• Catch/Print errors
Documentation
• REST APIs: Can access docs locally via SS console > Help > Secret
Server REST API Guide:
example: https://<SecretServer>/SecretServer/Documents/restapi/

• REST Web Services API Guide:

https://www.ibm.com/support/pages/node/1136272

• Getting Started with the REST API –

• PowerShell:
https://www.ibm.com/support/pages/node/1136266
• Perl:
• https://www.ibm.com/support/pages/node/1136260
SDK (tss)
• Overview
• Coding
• Troubleshooting
• Documentation
What is the SDK?
• Command line utility to Get Secret data
• Does not require username/password at runtime
• Uses “Application Users”
• Does not provide full API capabilities (e.g. cannot get Folders, etc).
• Can be used by applications to retrieve auth token to then make
direct API calls
SDK Configuration
• Create Application User:
- Admin > Users > Create New
- Enter details, and click ”Advanced”
- Select the “Application Account”
- Save
• Admin > All > SDK Client Management
- Client Onboarding > “+Rule”
- Enter:
• Rule Name
• IP Address(es) or CIDR notation
• Select the Application Account
• Require this generated onboarding key
- Save
SDK Usage
• Initialization:
tss init –u https://ss/SecretServer -r <rulename> -k <onboarding key>

• Status:
tss status

• Remove configuration:
tss remove

• Retrieve Token:
tss token

• Get Secret:
tss secret –s <secretID> -f <field slug> -o <output file> -ad

• Version:
tss version
SDK Usage

./tss secret -s 12 –ad

{"resource":"fooserver","username":"sdktest","passw
ord":"#5r5^(h^jLzK","notes":"This is a test secret
to use with SDK"}

./tss secret -s 12 -f notes

This is a test secret to use with SDK

SDK Usage (in a Python script)

import subprocess
import json
secret = None

secret = subprocess.check_output([”./tss secret -s 12 -ad"],shell=True)

jsonSec = json.loads(secret)

print(jsonSec["username"])
print(jsonSec["password"])

python sdkTest.py
sdktest
#5r5^(h^jLzK
Troubleshooting
• Server:

• IIS (C:\inetpub\logs\) and SS logs (C:\inetpub\wwwroot\SecretServer\log\)

• Admin > SDK Client Mgmt > Audit
• Client:

• -v | --verbose: output verbose errors.

• -i | --interactive: prompts for data entry (in case command syntax is in
question)
Documentation
• SDK Scripting Tool Usage:
https://www.ibm.com/support/pages/sdk-ibm-security-secret-
server-scripting-tool-devops-%E2%80%93-guide-use

• SDK Client Downloads:

https://www.ibm.com/support/pages/sdk-secret-server-scripting-
tool-devops
Demo
• REST
- cURL
- Postman
- Node.js

• SDK (tss)
- Initialize
- Get Secrets

• Combining SDK and REST

Demo / Hands-on
• cURL
- Get Auth Token
curl -k -H "Accept: application/json" –H “Content-Type: x-www-forms-urlencoded” -d "username=admin&password=test&grant_type=password" -X
POST https://ss/SecretServer/oauth2/token

- Get Secret Data

curl -k -H "Accept: application/json" -H "Authorization: Bearer AgLlj_5QYUilF6-sclepH…" https://ss/SecretServer/api/v1/secrets/12

• Postman
- Download/install Postman ( https://getpostman.com )
- Create an Environment
- Create a Collection
- Get Auth Token
- Get Secret Data

• Node.js
Examples
• GitHub:
https://github.com/gthrasher/SecretServer
Summary

• Applications/Scripts can leverage IBM Security Secret Server (ISSS) APIs

• ISSS REST APIs are portable/powerful

• ISSS SDK is great for automation

Questions for the panel
Ask the panelists a question now

Enter your question in the Q&A area

To ask a question after this presentation:

You are encouraged to ask follow-up questions in the Support forums:

https://www.ibm.com/mysupport/s/forumshome

IBM Secret Server Support forum:

http://ibm.biz/SecretServer-SupportForum

28
For more information
• IBM Secret Server Support Forum: http://ibm.biz/SecretServer-SupportForum
• IBM Secret Server Security Learning Academy: http://ibm.biz/ISSS-LearningAcademy

• IBM Knowledge Center for IBM Secret Server:

https://www.ibm.com/support/knowledgecenter/SSWHLP
• IBM Secret Server Support: https://ibm.biz/SecretServerSupport
Useful links:
Get started with IBM Security Support IBM Support
Sign up for My Notifications IBM Security Community
Follow us:

www.youtube.com/user/IBMSecuritySupport twitter.com/askibmsecurity http://ibm.biz/ISCS-LinkedIn

29
Thank you

Follow us: © Copyright IBM Corporation 2019. All rights reserved. The information contained in these
materials is provided for informational purposes only, and is provided AS IS without
warranty of any kind, express or implied. Any statement of direction represents IBM’s
securitylearningacademy.com current intent, is subject to change or withdrawal, and represent only goals and objectives.
IBM, the IBM logo, and other IBM products and services are trademarks of the
International Business Machines Corporation, in the United States, other countries or both.
ibm.biz/JoinIBMVIPRewards-Security Other company, product, or service names may be trademarks or service marks of others.
All names and references for organizations and other business institutions used in this
youtube/user/IBMSecuritySupport deliverable’s scenarios are fictional. Any match with real organizations or institutions is
coincidental.

@AskIBMSecurity Statement of Good Security Practices: IT system security involves protecting systems and
information through prevention, detection and response to improper access from within
and outside your enterprise. Improper access can result in information being altered,
ibm.biz/IBMSecurityClientSuccess-LinkedIn destroyed, misappropriated or misused or can result in damage to or misuse of your
systems, including for use in attacks on others. No IT system or product should be
considered completely secure and no single product, service or security measure can be
securityintelligence.com completely effective in preventing improper use or access. IBM systems, products and
services are designed to be part of a lawful, comprehensive security approach, which will
xforce.ibmcloud.com necessarily involve additional operational procedures, and may require other systems,
products or services to be most effective. IBM does not warrant that any systems,
products or services are immune from, or will make your enterprise immune from, the
ibm.com/security/community malicious or illegal conduct of any party.