Version: 3.25

PAM Core

The 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 list all devices in the PAM Core, according to permissions defined to the used A2A authorization.

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": "Device 91",
        "erro": false,
        "message": "Device 91",
        "error": false
    },
    "device": {
        "id": "91",
        "hostname": "desktop-91.com",
        "ip": "172.10.20.90",
        "model": "Ubuntu",
        "type": "Desktop",
        "vendor": "Linux",
        "site": "AWS"
    }
}

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 inactivate a device identified by its ID.

info

When a device is inative, 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 add or update a device in PAM Core.

POST /iso/pam/device

Parameters

The following table is an example of the required input parameters:

Field	Type	Example	Required	Obs.
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.

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 list all credentials in the PAM Core, according to permissions defined to the used A2A authorization.

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": "secret@2504",
        "content": "secret@2504",
        "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 inactivate 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 add or update a credential in PAM Core.

POST /iso/pam/credential

Parameters

Field	Type	Example	Required	Obs.
identifier	Int	123	No	Credential ID. Required to update.
username	String	my_user	No	Credential username.
content	String	MyPrettyPassword@1234	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.
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.

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 inativating 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 scret 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.

Expected response

HTTP/1.1 200 OK

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

Expected response when the information content is not provided

HTTP/1.1 400 Bad Request

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

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.

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.

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
    }
}

PAM Core

Devices​

List devices​

Get a device​

Inactivate a device​

Add or Update a device​

Credentials​

List credentials​

Get a credential​

Inactivate a credential​

Add or Update a credential​

Release the credential custody​

Protected Information​

Get a protected information​

Inactivate a protected information​

Create protected information​

Proxy Sessions​

Create a web session authenticated URL​

Mandatory Proxy Session Termination​

Devices

List devices

Get a device

Inactivate a device

Add or Update a device

Credentials

List credentials

Get a credential

Inactivate a credential

Add or Update a credential

Release the credential custody

Protected Information

Get a protected information

Inactivate a protected information

Create protected information

Proxy Sessions

Create a web session authenticated URL

Mandatory Proxy Session Termination