Version: 3.22

PAM Methods

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 resource must be selected in the application authorization.

Devices

Query device list

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

Query a single device

You can also query a single device using WebService A2A methods.

You should replace the wildchar * with the desired Device ID number or ID Identificator.

GET /iso/pam/device/*

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

Inativating a device

You can also inativating a device using WebService A2A methods. When a device is inative, all it's credentials will be automaticaly deactivated also.

You should replace the wildchar * with the desired Device ID number or ID Identificator.

DELETE iso/pam/device/*

Expected response on success

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

Creating and Updating a device

POST /iso/pam/device

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

Field	Type	Example	Req.	Obs.
hostname	String	mydevice02	Yes
ip	String	22.13.50.71	Yes
site	String	AWS	Yes
model	String	CentOS 7	Yes
vendor	String	CentOS	Yes
type	String	Server	Yes	Should be an existing one.

info

To update a record you must use this same resource. The device will be queried by the hostname. That is, if you find a device, the registry will be updated. If it does not, then the registry 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

Query credential list

GET /iso/pam/credential

This method returns the list of credentials that the A2A client can have access to.

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": ""
        }
    ]
}

Query a single credential

GET /iso/pam/credential/*

You can also query a single credential using WebService A2A methods.

You should replace the wildchar * with the desired Credential ID number or ID Identificator.

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

Inativating a credential

DELETE /iso/pam/credential/*

You can also inativating a credential using WebService A2A methods.

You should replace the wildchar * with the desired Credential ID number or ID Identificator.

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

Updating a credential

POST /iso/pam/credential

This method only allows you to update a credential that already exists in the senhasegura and that the A2A client already has access to. The following table is an example of the required input parameters:

Field	Type	Example	Req.
hostname	String	mydevice02	Yes
ip	String	22.13.50.71	Yes
identifier	String	5	Yes
username	String	credential05	Yes

info

To update a record you must use this same method. If the numeric ID (credential id) is not provided, the credential will be changed by IP, Hostname and Username set. That is, if you find a device, the register will be updated. If it does not, then the register will be created.

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 custody of a credential

DELETE /iso/pam/credential/custody/*

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.

You should replace the wildchar * with the desired Credential ID number or ID Identificator.

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

Query a single protected information

GET /iso/pam/info/*

This method only allows you to query a single protected information. You should replace the wildchar * with the desired Protected Information ID number or ID Identificator.

Expected response

URI

Using the Method POST

https://url_do_cofre/iso/pam/info

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

Name	Success	Error
status	2xx	4xx
message	Information successfully registered	Information not registered
erro	false	true
info	Division only
name	Information name. (mandatory) Ex.: info1, info
type	Information type. (mandatory) Ex.: access credential, Digital certificate
service	Name of the service to which the information refers. Ex.: facebook
url	URL of the service referring to the information Ex.: www.facebook.com
content	Content to be protected, cannot be a text file only. (mandatory) Ex.: protected information
users_allowed	Username of users authorized to access information separated by a comma. Ex: Admin, user1
identifier	Unique identifier of the information, for later reference. Ex: INFO129

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

Inativating a protected information

DELETE /iso/pam/info/*

You can also inativating a protected information using WebService A2A methods.

You should replace the wildchar * with the desired Protected Information ID number or ID Identificator.

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

Creating of protected information

POST /iso/pam/info

The following information is an example of the required input parameter:

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

Creating 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

\hfill

{
    "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

DELETE /iso/session/drop/[identifier]

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.

Response

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

PAM Methods

Devices​

Query device list​

Expected response​

Query a single device​

Expected response​

Expected response when the device is not found​

Inativating a device​

Expected response on success​

Expected response when inactivating a device that does not exist​

Creating and Updating a device​

Expected response​

Expected response when registering without providing some required data​

Credentials​

Query credential list​

Expected response​

Query a single credential​

Expected response​

Expected response when a credential does not exist or is not allowed access​

Inativating a credential​

Expected response​

Expected response when A2A client is not allowed access to the credential, or the credential is already inactive​

Updating a credential​

Expected response​

Expected response when one of the required data is not provided​

Release the custody of a credential​

Expected response​

Expected response when you do not have access to the credential or the credential does not exist​

Protected Information​

Query a single protected information​

Expected response​

URI​

Expected response when you do not have access to information or does not exist​

Expected response when you have access to information, but it is inactive​

Inativating a protected information​

Expected response​

Expected response when you do not have access to information or does not exist​

Expected response when the information is already inactive​

Creating of protected information​

Expected response​

Expected response​

Expected response when the information content is not provided​

Proxy Sessions​

Creating a web session authenticated URL​

Expected response​

Expected response when one of the required data is not provided​

Mandatory Proxy Session Termination​

Response​

Devices

Query device list

Expected response

Query a single device

Expected response

Expected response when the device is not found

Inativating a device

Expected response on success

Expected response when inactivating a device that does not exist

Creating and Updating a device

Expected response

Expected response when registering without providing some required data

Credentials

Query credential list

Expected response

Query a single credential

Expected response

Expected response when a credential does not exist or is not allowed access

Inativating a credential

Expected response

Expected response when A2A client is not allowed access to the credential, or the credential is already inactive

Updating a credential

Expected response

Expected response when one of the required data is not provided

Release the custody of a credential

Expected response

Expected response when you do not have access to the credential or the credential does not exist

Protected Information

Query a single protected information

Expected response

URI

Expected response when you do not have access to information or does not exist

Expected response when you have access to information, but it is inactive

Inativating a protected information

Expected response

Expected response when you do not have access to information or does not exist

Expected response when the information is already inactive

Creating of protected information

Expected response

Expected response

Expected response when the information content is not provided

Proxy Sessions

Creating a web session authenticated URL

Expected response

Expected response when one of the required data is not provided

Mandatory Proxy Session Termination

Response