PAM Core API

12 minutes to read

Print
Share
Dark
Light
PDF

PAM Core API

12 minutes to read

Print
Share
Dark
Light
PDF

Article Summary

senhasegura's A2A WebService includes methods that allow you to create, request, and change stored data. This includes adding, updating or removing devices, credentials, users, and more.

Caution

These methods are only available if PAM Core is listed under "Authorized resources" in your A2A module.

Devices

Get a List of Registered Devices

The following method returns a list of all the devices in your PAM Core, limited by the permission level of your A2A.

GET /iso/pam/device

Expected response

HTTP/1.1 200 OK

{
    "response": {
        "status": 200,
        "mensagem": "2 devices found",
        "erro": false,
        "message": "2 devices found",
        "error": false
    },
    "devices": [
        {
            "id": "1",
            "hostname": "mydevicehostname",
            "ip": "172.10.20.30",
            "model": "Windows Server 2012",
            "type": "Server",
            "vendor": "Microsoft",
            "site": "LAX"
        },
        {
            "id": "6",
            "hostname": "myseconddevice",
            "ip": "41.41.208.182",
            "model": "CentOS 7",
            "type": "Server",
            "vendor": "CentOS",
            "site": "AWS"
        }
    ]
}

Get the Parameters of a Device

This method takes a Device ID and returns the device’s parameters.

GET /iso/pam/device/[DEVICE_ID]

Expected response

HTTP/1.1 200 OK

{
    "response": {
        "status": 200,
        "mensagem": "Dispositivo 53",
        "erro": false,
        "cod_erro": 0,
        "message": "Dispositivo 53",
        "error": false,
        "error_code": 0
    },
    "device": {
        "id": "53",
        "hostname": "desktop-91.com",
        "ip": "172.10.20.90",
        "model": "Ubuntu",
        "type": "Desktop",
        "vendor": "Linux",
        "site": "AWS",
        "device_domain": "senhasegura.lab",
        "device_tags": "api, app",
        "connectivities": "SSH:22",
        "session_remote_config": "SSH:EXPECT:FILL",
        "tags": "tag1"
    }
}

Expected response if no device is found

HTTP/1.1 400 Bad Request

{
    "response": {
        "status": 400,
        "mensagem": "1011: Device not found",
        "erro": true,
        "message": "1011: Device not found",
        "error": true
    },
    "exception": {
        "code": 1011,
        "message": "1011: Device not found",
        "detail": null
    }
}

Deactivate a device

This method deactivates devices based on their device ID.

Note

When you deactivate a device, all the credentials associated with it are automatically suspended.

DELETE iso/pam/device/[DEVICE_ID]

Expected response

HTTP/1.1 200 OK

{
    "response": {
        "status": 200,
        "mensagem": "Device successfully deactivated",
        "erro": false,
        "message": "Device successfully deactivated",
        "error": false
    }
}

Expected response for device not found

HTTP/1.1 400 Bad Request

{
    "response": {
        "status": 400,
        "mensagem": "1011: Device not found",
        "erro": true,
        "message": "1011: Device not found",
        "error": true
    },
    "exception": {
        "code": 1011,
        "message": "1011: Device not found",
        "detail": null
    }
}

Add or Update a Device

This method adds a device to your PAM Core or updates an existing device.

POST /iso/pam/device

{
    "response": {
        "status": 201,
        "mensagem": "Dispositivo registrado com sucesso!",
        "erro": false,
        "cod_erro": 0,
        "message": "Dispositivo registrado com sucesso!",
        "error": false,
        "error_code": 0
    },
    "device": {
        "id": "53",
        "hostname": "desktop-91.com",
        "ip": "172.10.20.90",
        "model": "Ubuntu",
        "type": "Desktop",
        "vendor": "Linux",
        "site": "AWS",
        "device_domain": "senhasegura.lab",
        "device_tags": "api, app",
        "connectivities": "SSH:22",
        "session_remote_config": "SSH:EXPECT:FILL",
        "tags": "tag1"
    }
}

Parameters

This table lists all the required and optional parameters for devices:

Field	Type	Example	Required	Obs.	New Device Default Value
hostname	String	localhost	Yes	Device name.	-
ip	String	127.0.0.1	Yes	Device's IP address.	-
type	String	Server	Yes	Device type. A new type is created if unique.	-
vendor	String	Debian	Yes	Device vendor. A new vendor is created if unique.	-
model	String	10.0 Buster	Yes	Device model. A new model is created if unique.	-
site	String	Default	Yes	Device's site. A new site is created if unique.	-
device_domain	String	senhasegura.lab	No	Domain name or abbreviation. Only previously registered domains are accepted.	-
device_tags	String	api, app	No	Tags associated with this device.	-
connectivities	String	SSH:22, HTTPS:443	No	Device connectivity.	-
session_remote_config	String	SSH:EXPECT:FILL	No	Login expression.	-

Info

If the hostname matches that of a previously added device, this method will update the existing device. If not, this method creates a new device and assigns it to this hostname.

Expected response

HTTP/1.1 200 OK

{
    "response": {
        "status": 201,
        "mensagem": "Device successfully registered!",
        "erro": false,
        "message": "Device successfully registered!",
        "error": false
    },
    "device": {
        "id": "9",
        "hostname": "mydevice02",
        "ip": "22.13.50.71",
        "site": "AWS"
    }
}

Expected response for missing required parameter

HTTP/1.1 400 Bad Request

{
      "response": {
          "status": 400,
          "mensagem": "1004: The device's hostname was not informed",
          "erro": true,
          "message": "1004: The device's hostname was not informed",
          "error": true
      },
      "exception": {
          "code": 1004,
          "message": "1004: The device's hostname was not informed",
          "detail": null
      }
  }

Credentials

Get a List of All Credentials

This method returns a list of all the credentials in your PAM Core, limited by the permission level of your A2A.

GET /iso/pam/credential

Expected response

HTTP/1.1 200 OK

{
    "response": {
        "status": 200,
        "mensagem": "2 credentials found",
        "erro": false,
        "message": "2 credentials found",
        "error": false
    },
    "credentials": [
        {
            "id": "1",
            "identifier": "fakeuser01ws",
            "username": "fakeuser01",
            "expiration": null,
            "change": "2020-11-17 16:14:35",
            "view": null,
            "hostname": "fakedevice01",
            "management_ip": "172.10.20.30",
            "type": "Local User",
            "type_code": "1",
            "device_model": "Fake Product",
            "device_type": "Server",
            "device_vendor": "Fake Vendor",
            "automatic_change": "0",
            "connectivity": "",
            "connectivity_code": ""
        },
        {
            "id": "2",
            "identifier": "fakeuser02ws",
            "username": "fakeuser02",
            "expiration": null,
            "change": "2020-11-17 16:14:35",
            "view": null,
            "hostname": "fakedevice01",
            "management_ip": "172.10.20.30",
            "type": "Local User",
            "type_code": "1",
            "device_model": "Fake Product",
            "device_type": "Server",
            "device_vendor": "Fake Vendor",
            "automatic_change": "0",
            "connectivity": "",
            "connectivity_code": ""
        }
    ]
}

Get the Parameters of a Credential

This method takes a Credential ID and returns the credential’s parameters.

GET /iso/pam/credential/[CREDENTIAL_ID]

Expected response

HTTP/1.1 200 OK

{
    "response": {
        "status": 200,
        "mensagem": "Credential 5",
        "erro": false,
        "message": "Credential 5",
        "error": false
    },
    "credential": {
        "id": "5",
        "tag": "robot-test-5",
        "username": "credential_5",
        "password": "[email protected]",
        "content": "[email protected]",
        "hostname": "destktop-91.com",
        "parent_credential_cod": null,
        "parent_credential": null,
        "additional": "CREDADD01",
        "domain": "",
        "ip": "172.10.10.90",
        "port": "22",
        "model": "Ubuntu",
        "expiration_time": "2021-01-16T17:31:39"
    }
}

Expected response for credential not found, or access denied

HTTP/1.1 400 Bad Request

{
    "response": {
        "status": 400,
        "mensagem": "1007: Credential not found",
        "erro": true,
        "message": "1007: Credential not found",
        "error": true
    },
    "exception": {
        "code": 1007,
        "message": "1007: Credential not found",
        "detail": null
    }
}

Deactivate a credential

This method deactivates a credential based on its ID.

DELETE /iso/pam/credential/[CREDENTIAL_ID]

Expected response

HTTP/1.1 200 OK

{
    'response': {
        'status': 200,
        'mensagem': 'Credential successfully deactivated',
        'erro': False,
        'message': 'Credential successfully deactivated',
        'error': False
    }
}

Expected response when the A2A client is denied access to the credential or the credential has been previously deactivated

HTTP/1.1 400 Bad Request

{
    'response': {
        'status': 400,
        'mensagem': '1007: Credential not found',
        'erro': True,
        'message': '1007: Credential not found',
        'error': True
    },
    'exception': {
        'code': 1007,
        'message': '1007: Credential not found',
        'detail': None
    }
}

Add or update a credential

This method adds a credential to your PAM Core or updates an existing credential.

POST /iso/pam/credential

Parameters

Field	Type	Example	Required	Obs.	New Credential Default Value
identifier	Int	123	No	Credential ID. Required to update an existing credential.	Generated by senhasegura
username	String	my_user	Yes*	Username assigned to this credential.	usr
content	String	[email protected]	No	Password assigned to this credential.	-
additional	String	DATABASE	No	Additional information.	-
tags	String	api, app	No	Tags associated with the credential.	-
credential_type	String	Domain User	No	Type of credential. A new type is created for each unique value.	Local User
domain	String	senhasegura.lab	No	Domain name or abbreviation. Only previously registered domains are accepted.	-
parent_password	Int	123	No	ID of the Parent Credential.	-
hostname	String	localhost	Yes	Device name.	-
ip	String	127.0.0.1	Yes	Device's IP address.	-
type	String	Server	No	Device type. A new type is created for each unique value.	-
vendor	String	Debian	No	Device vendor. A new vendor is created for each unique value.	-
model	String	10.0 Buster	No	Device model. A new model is created for each unique value.	-
site	String	Default	No	Device's site. A new site is created for each unique value.	-
device_domain	String	senhasegura.lab	No	Domain name or abbreviation. Only previously registered domains are accepted.	-
device_tags	String	api, app	No	Tags associated with the device.	-
connectivities	String	SSH:22, HTTPS:443	No	Device connectivity.	-
session_remote_config	String	SSH:EXPECT:FILL	No	Login expression.	-

*Mandatory field only when adding a new credential.

Info

To update an existing credential, please inform the credential ID or the device’s IP address, as well as the username and device hostname.

Expected response

HTTP/1.1 200 OK

{
    "response": {
        "status": 201,
        "mensagem": "Credential updated successfully!",
        "erro": false,
        "message": "Credential updated successfully!",
        "error": false
    },
    "credential": {
        "id": "5",
        "tag": "robot-test-5"
    }
}

Expected response for missing required parameter

HTTP/1.1 400 Bad Request

Note

Here is a list of error codes and their respective missing parameters:

1004: missing device's hostname

1005: missing device's IP address

1007: Credential not found

{
    "response": {
        "status": 400,
        "mensagem": "1004: The device's hostname was not informed",
        "erro": true,
        "message": "1004: The device's hostname was not informed",
        "error": true
    },
    "exception": {
        "code": 1004,
        "message": "1004: The device's hostname was not informed",
        "detail": null
    }
}

Release the custody of a credential

DELETE /iso/pam/credential/custody/[CREDENTIAL_ID]

When the API receives a password request, we say it gives the user temporary custody of the respective credential. We say this custody is "released" when the API revokes access to this credential.

Expected response

HTTP/1.1 200 OK

{
    "response": {
        "status": 200,
        "mensagem": "Credential custody 1 released",
        "erro": false,
        "message": "Credential custody 1 released",
        "error": false
    }
}

In the example above, "1" is the Credential ID.

Expected response for credential not found, or access denied

HTTP/1.1 400 Bad Request

{
    "response": {
        "status": 400,
        "mensagem": "1007: Credential not found",
        "erro": true,
        "message": "1007: Credential not found",
        "error": true
    },
    "exception": {
        "code": 1007,
        "message": "1007: Credential not found",
        "detail": null
    }
}

Privileged Information

Retrieve Privileged Information

This method takes an ID and returns the data that had been previously protected.

GET /iso/pam/info/[PROTECTED_INFORMATION_ID]

Expected response

HTTP/1.1 200 OK

{
    "response": {
        "status": 201,
        "mensagem": "Information successfully registered!",
        "erro": false,
        "message": "Information successfully registered!",
        "error": false
    },
    "info": {
	    "name": "saas_vault1",
		"type": "access credential",
		"service": "saas_client",
		"url": "10.10.10.2",
		"content": "login: mt4adm, password: mt4admp4ss",
		"users_allowed": "admin, account_manager, mscharra",
		"identifier": "INFOSAASVAULT1"
    }
}

Expected response for data not found or access denied

HTTP/1.1 400 Bad Request

{
    "response": {
        "status": 400,
        "mensagem": "1026: The information content was not informed",
        "erro": false,
        "message": "1026: The information content was not informed",
        "error": false
    },
    "exception": {
        "code": 1026,
        "message": "1026: The information content was not informed",
        "detail": null
    }
}

Expected response if the data is no longer available

HTTP/1.1 400 Bad Request

{
    "response": {
        "status": 400,
        "mensagem": "1024: Inactive information",
        "erro": true,
        "message": "1024: Inactive information",
        "error": true
    },
    "exception": {
        "code": 1024,
        "message": "1024: Inactive information",
        "detail": null
    }
}

Deactivate Privileged Information

You can also use WebService A2A methods to remove data from the list of protected information.

DELETE /iso/pam/info/[PROTECTED_INFORMATION_ID]

Expected response

HTTP/1.1 200 OK

{
    "response": {
        "status": 200,
        "mensagem": "Information successfully deactivated",
        "erro": false,
        "message": "Information successfully deactivated",
        "error": false
    }
}

Expected response for data not found or access denied

HTTP/1.1 400 Bad Request

{
    "response": {
        "status": 400,
        "mensagem": "1023: Information not found",
        "erro": true,
        "message": "1023: Information not found",
        "error": true
    },
    "exception": {
        "code": 1023,
        "message": "1023: Information not found",
        "detail": null
    }
}

Expected response if the data is no longer available

HTTP/1.1 400 Bad Request

{
    "response": {
        "status": 400,
        "mensagem": "1024: Inactive information",
        "erro": true,
        "message": "1024: Inactive information",
        "error": true
    },
    "exception": {
        "code": 1024,
        "message": "1024: Inactive information",
        "detail": null
    }
}

Protected Data

POST /iso/pam/info

Parameters

Field	Type	Example	Req.	Obs.
content	String	My secret data	Yes	Data you want to protect. File upload is not available.

Expected response

HTTP/1.1 200 OK

{
    "response": {
        "status": 201,
        "mensagem": "Information successfully registered!",
        "erro": false,
        "message": "Information successfully registered!",
        "error": false
    },
    "info": {
        "id": "4",
        "tag": null
    }
}

List of all the required and optional input parameters with examples:

Field	Type	Example	Req.	Obs.
content	String	My secret data	Yes	Plain-text content you want to protect. File upload is not available.
identifier	String	INFO1298	No	Unique ID used to retrieve the data when necessary.
name	String	My privileged info	No	Name assigned to this data. Visible in the senhasegura application.
type	String	Access credential	No	Information type. Only existing types are accepted.

Proxy Sessions

Create an Authenticated URL for a Web Session

POST /iso/remote/session

This method generates an authenticated URL that you can use to start a web session using senhasegura's Web Proxy in a previously registered device.This method allows you to generate an authenticated URL to start a web session in a device previously registered in the solution using senhasegura Web Proxy.

Info

By default, the system will set the screen resolution at 1920x1080 unless otherwise specified.

This table lists all the required and optional parameters:

Field	Type	Example	Req.	Obs.
user	String	senhasegura-user	Yes	Username used for authentication. The user must have been previously added to senhasegura.
credential	String	admin	Yes	Username of the credential used in this web session.
device	String	172.12.32.14	Yes	Target device's hostname or IP address.
protocol	String	SSH	Yes	Network protocol (SSH, RDP, HTTPS...).
remotedevice	String	123	No	Device ID, IP address, or Hostname for the web session. Only required if the session uses domain credentials.
remoteAddr	String	201.13.25.61	No	User IP address. This IP address will be used throughout the session.
port	Int	22	No	Port used throughout the session. By default, it uses the Device Port of the chosen device unless otherwise specified.
remoteapp	Int	123	No	RemoteApp ID. For RemoteApp sessions only.
screensize	String	1900x1200	Screen resolution.	Display resolution.

Expected response

HTTP/1.1 200 OK

{
    "response": {
        "status": 200,
        "mensagem": "Session created successfully",
        "erro": false,
        "message": "Session created successfully",
        "error": false
    },
    "session": {
        "session_url": "https://senhasegura/modulos/auth?_sr=cmJzOkQwUzdq
        Wk9zQkhKY2FvRkNaQ0Q2OVRnbVdmTnk1MEc2cDNnM1orM2ltL3BxQURZNW91WW1G
        TExFU2JlYldkTlRabFNWb0Z2VzllU0E1WlIraEtJM3NvMlZmZ0NZTXV4QlNFWEt
        PUko3YlMxQWNwZmxYTWw2ZGxsUlFEOCtPdlBq",
        "token": "c4ac50a35bcc0a0d1641b02e64dd7c6421d3e5be2afa5378ca29ce5621e2eb38"
    }
}

Note

Authenticated URLs expire after 30 seconds and can no longer be used. Generate a new one if needed.

Expected response for missing required parameter

HTTP/1.1 400 Bad Request

Info

These are required parameters that can result in a bad request if not specified:

user: User not specified
credential: Credential not specified
device: Credential device not specified
protocol: Invalid protocol

{
    "response": {
        "status": 400,
        "mensagem": "Credential not specified",
        "erro": true,
        "cod_erro": 0,
        "message": "Credential not specified",
        "error": true,
        "error_code": 0
    }
}

Mandatory Proxy Session Termination

This method terminates a proxy session and returns a message with the reason for termination. You can use this method to trigger external systems, such as SIEM, into ending sessions based on the alerts sent by senhasegura.

DELETE /iso/session/drop/[SESSION_IDENTIFIER]

Expected response

{
    "response": {
        "status": 200,
        "menssage": "Session finished",
        "erro": false
    }
}

These methods allow you to manage the Related Users in your PAM Core through WebService A2A methods.

Requirements

To request the Related Users API, you must enable the option Users in Authorized resources in the authorization safety settings of the registered A2A application.

The table below shows all the required input parameters with examples:

Field	Type	Example	Req.	Obs.
id	Int	123	Yes	Related user ID.
name	String	Ashley Perry	Yes	Name assigned to this data. Visible in the senhasegura application.
username	String	aperry	Yes	User identification name on senhasegura.

List all

This method returns a list of all Related users.

GET /iso/user/related

Expected response

HTTP/1.1 200 OK

{
    "response": {
        "status": 200,
        "mensagem": "2 related users found",
        "erro": false,
        "cod_erro": 0,
        "message": "2 related users found",
        "error": false,
        "error_code": 0
    },
    "relatedUsers": [
   	{          
        "id": 1,
        "name":  "Ashley Perry",
        "username": "aperry"
      },
      {
        "id": 2,
        "name": "John Green",
        "username": "jgreen"
      }
   ]
}

Get the Parameters of a Related user

This method takes the ID of a Related User and returns this user’s other parameters.

GET /iso/user/related/{identifier}

Expected response

HTTP/1.1 200 OK

{
    "response": {
        "status": 200,
        "mensagem": "User found",
        "erro": false,
        "cod_erro": 0,
        "message": "User found",
        "error": false,
        "error_code": 0
    },
    "relatedUsers": 
   	{          
        "id": 1,
        "name": "Ashley",
        "username": "aperry"
      }
}

Expected response for user not found

HTTP/1.1 400 Bad Request

{
    "response": {
        "status": 400,
        "mensagem": "1005: User does not exist",
        "erro": true,
        "cod_erro": 0,
        "message": "1005: User does not exist",
        "error": true,
        "error_code": 0
    },
    "exception": {
        "code": 1005,
        "message": "1005: User does not exist",
        "detail": ""
    }

}

Deactivate a Related User

This method deactivates a Related User based on their ID.

DELETE /iso/user/related/{identifier}

Expected response

HTTP/1.1 200 OK

{
    "response": {
        "status": 200,
        "mensagem": "Related user successfully deactivated",
        "erro": false,
        "message": "Related user successfully deactivated",
        "error": false,
    }
}

Expected response for Related User not found

HTTP/1.1 400 Bad Request

{
    "response": {
        "status": 400,
        "mensagem": "1005: Related user not found",
        "erro": true,
        "cod_erro": 0,
        "message": "1005: Related user not found",
        "error": true,
        "error_code": 0
    },
    "exception": {
        "code": 1005,
        "message": "1005: Related user not found",
        "detail": ""
    }

}

Create a Related User

Use this method to add a new Related User to the list.

POST /iso/user/related

Expected request

{ 
    "name": "Ashley Perry",
    "username": "aperry"
}

Expected response

HTTP/1.1 200 OK

{
    "response": {
        "status": 200,
        "mensagem": "Related user successfully registered!",
        "erro": false,
        "message": "Related user successfully registered!",
        "error": false,
    },
    "relatedUsers": {          
        "id": 3,
        "name": "Ashley Perry",
        "username": "aperry"
      }
}

Expected response for missing required parameter

HTTP/1.1 400 Bad Request

{
    "response": {
        "status": 400,
        "mensagem": "1001: Parameter 'username' was not informed!",
        "erro": true,
        "cod_erro": 0,
        "message": "1001: Parameter 'username' was not informed!",
        "error": true,
        "error_code": 0
    },
    "exception": {
        "code": 1001,
        "message": "1001: Parameter 'username' was not informed!",
        "detail": ""
    }

}

Update a Related User

This method changes the parameters of a Related User based on their ID.

PUT /iso/user/related

Expected request

{ 
    "id" : 15,
    "name": "Test name",
    "username": "test"
}

Expected response

"response": {
        "status": 200,
        "mensagem": "Related user successfully updated!",
        "erro": false,
        "cod_erro": 0,
        "message": "Related user successfully updated!",
        "error": false,
        "error_code": 0
    },
    "relatedUsers": {
        "id": "15",
        "name": "Test Update",
        "username": "test"
    }

Was this article helpful?

What's Next

Related User

On this page

Devices
Credentials
Privileged Information
Proxy Sessions
Related users