PAM Core API
- 14 minutes to read
-
Print
-
DarkLight
-
PDF
PAM Core API
- 14 minutes to read
-
Print
-
DarkLight
-
PDF
senhasegura WebService A2A has methods of query, create and change information stored in the application such as: add, change and inactivate devices and credentials, among others.
Caution
To use these methods the PAM Core resource must be selected in the application authorization.
Devices
List devices
This method lists all devices in the PAM Core, according to permissions defined for the 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 a device
This method returns information about a device identified by its ID.
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 when the device is 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
}
}
Inactivate a device
This method inactivates a device identified by its ID.
Info
When a device is inactive, all it's credentials will be automaticaly inactivated too.
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 when inactivating a device that does not exist
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 or updates a device in PAM Core.
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
The following table is an example of the required input parameters:
| Field | Type | Example | Required | Obs. | New Device Default Value |
|---|---|---|---|---|---|
| hostname | String | localhost | Yes | Device name. | - |
| ip | String | 127.0.0.1 | Yes | Device IP address. | - |
| type | String | Server | Yes | Device type. If not exists, a new one will be created. | - |
| vendor | String | Debian | Yes | Device vendor. If not exists, a new one will be created. | - |
| model | String | 10.0 Buster | Yes | Device model. If not exists, a new one will be created. | - |
| site | String | Default | Yes | Device site. If not exists, a new one will be created. | - |
| device_domain | String | senhasegura.lab | No | Domain long or short name. It must already exists on senhasegura. | - |
| device_tags | String | api, app | No | Device tags. | - |
| connectivities | String | SSH:22, HTTPS:443 | No | Device connectivities. | - |
| session_remote_config | String | SSH:EXPECT:FILL | No | Expressions for login. | - |
Info
If exists a device with the informed hostname, it will be updated. If not, a new device will be created.
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 when registering without providing some required data
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
List credentials
This method lists all credentials in the PAM Core, according to permissions defined for the 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 a credential
This method returns information about a credential identified by its ID.
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 when a credential does not exist or is not allowed access
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
}
}
Inactivate a credential
This method inactivates a credential identified by 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 A2A client is not allowed access to the credential, or the credential is already inactive
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 or updates a credential in PAM Core.
POST /iso/pam/credential
Parameters
| Field | Type | Example | Required | Obs. | New Credential Default Value |
|---|---|---|---|---|---|
| identifier | Int | 123 | No | Credential ID. Required to update. | Generated by senhasegura |
| username | String | my_user | Yes* | Credential username. | usr |
| content | String | [email protected] | No | Credential password. | - |
| additional | String | DATABASE | No | Additional information. | - |
| tags | String | api, app | No | Credential tags. | - |
| credential_type | String | Domain User | No | Credential type. If not exists, a new one will be created. | Local User |
| domain | String | senhasegura.lab | No | Domain long or short name. It must already exists on senhasegura. | - |
| parent_password | Int | 123 | No | Parent credential ID. | - |
| hostname | String | localhost | Yes | Device name. | - |
| ip | String | 127.0.0.1 | Yes | Device IP address. | - |
| type | String | Server | No | Device type. If not exists, a new one will be created. | - |
| vendor | String | Debian | No | Device vendor. If not exists, a new one will be created. | - |
| model | String | 10.0 Buster | No | Device model. If not exists, a new one will be created. | - |
| site | String | Default | No | Device site. If not exists, a new one will be created. | - |
| device_domain | String | senhasegura.lab | No | Domain long or short name. It must already exists on senhasegura. | - |
| device_tags | String | api, app | No | Device tags. | - |
| connectivities | String | SSH:22, HTTPS:443 | No | Device connectivities. | - |
| session_remote_config | String | SSH:EXPECT:FILL | No | Expressions for login. | - |
*Mandatory only when creating a new credential, not for updates.
Info
To update a crential, you must inform the credental ID or device IP, device hostname and username.
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 when one of the required data is not provided
HTTP/1.1 400 Bad Request
Info
The following error codes may occur if the required data is not provided:
- 1004: The device's hostname was not informed
- 1005: The device's IP was not informed
- 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 credential custody
DELETE /iso/pam/credential/custody/[CREDENTIAL_ID]
When a password request is performed via API, the credential remains in custody of the applicant. To release the custody, it is necessary to use this method.
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 the number "1" is the ID of the credential.
Expected response when you do not have access to the credential or the credential does not exist
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
}
}
Protected Information
Get a protected information
This method only allows you to query a single protected information.
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 when you do not have access to information or does not exist
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 when you have access to information, but it is inactive
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
}
}
Inactivate a protected information
You can also inactivate a protected information using WebService A2A methods.
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 when you do not have access to information or does not exist
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 when the information is already inactive
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
}
}
Create protected information
POST /iso/pam/info
Parameters
| Field | Type | Example | Req. | Obs. |
|---|---|---|---|---|
| content | String | My secret data | Yes | Secret data to be protected. 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
}
}
The following information is an example of the complete input parameters:
| Field | Type | Example | Req. | Obs. |
|---|---|---|---|---|
| content | String | My secret data | Yes | Plain-text content to be protected. File upload is not available. |
| identifier | String | INFO1298 | No | Unique identificator used to request this data. |
| name | String | My protected info | No | Information name to be presented into senhasegura pages. |
| type | String | Access credential | No | Information type. Should be an existing one. |
Proxy Sessions
Create a web session authenticated URL
POST /iso/remote/session
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
If a resolution is not informed, the system will use the value of 1920x1080 as the system default.
The following table is an example of the required input parameters:
| Field | Type | Example | Req. | Obs. |
|---|---|---|---|---|
| user | String | senhasegura-user | Yes | Username for authentication on senhasegura . It must exist on the solution. |
| credential | String | admin | Yes | Credential username to be used for web session. |
| device | String | 172.12.32.14 | Yes | Hostname or IP from the target device. |
| protocol | String | SSH | Yes | Network protocol (SSH, RDP, HTTPS...). |
| remotedevice | String | 123 | No | Device ID, IP ou Hostname for web session. Necessary only for sessions that use domain credentials. |
| remoteAddr | String | 201.13.25.61 | No | User connection IP address. The session will works online troghtout this IP address. |
| port | Int | 22 | No | Port to be used on the session. If not informed, the default port set on the device will be used. |
| remoteapp | Int | 123 | No | RemoteApp ID. Used in case of RemoteApp session. |
| screensize | String | 1900x1200 | Screen 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"
}
}
Info
The session URL is valid for 30 seconds. After that time you need to generate a new one.
Expected response when one of the required data is not provided
HTTP/1.1 400 Bad Request
Info
The following error may occur if the required data is not provided:
- 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
The proxy session ends indicating the reason for the termination. Use this functionality so that external systems like SIEM can end sessions based on the alerts issued by the senhasegura itself.
DELETE /iso/session/drop/[SESSION_IDENTIFIER]
Expected response
{
"response": {
"status": 200,
"menssage": "Session finished",
"erro": false
}
}
Related users
You can manage related users in the PAM Core, according to permissions defined in the A2A.
The table below contains the required input parameters and its examples:
| Field | Type | Example | Req. | Obs. |
|---|---|---|---|---|
| id | Int | 123 | Yes | Related user ID. |
| name | String | Ashley Perry | Yes | Information name to be presented into senhasegura pages. |
| username | String | aperry | Yes | User identifier on senhasegura. |
List all
This method lists all the 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 a related user
This method returns information about a related user identified by its ID.
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 when the user is 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": ""
}
}
Inactivate a related user
This method inactivates a related user identified by its 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 when the related user does not exist
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": ""
}
}
Add a related user
This method registers a new related user.
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 when registering without providing required data
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 updates a related user by its 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?
