A2A
Integration
Webservice Integration
senhasegura integration API enables other applications to create, query, update and remove passwords, keys and other protected information using webservices. The webservice follows a REST architecture and can authenticate with OAuth v1.0 or OAuth v2.0 methods.
Every call made to the service is recorded with the date, time, call source IP, and the calling API client application. Sensitive data, such as password and key values, is hidden from log1 messages.
Each client application's access is controlled, in addition to OAuth v1.0 or OAuth v2.0 authentication, by the request's source IP.
Each client has access only to passwords registered by him or assigned by configuration in the application.
The senhasegura works with two basic types of data that are securely stored: passwords and protected information.
Passwords can be Credentials for accessing Devices such as servers and routers, as well as RSA keys used for SSH access. Passwords are automatically changed by the application according to the configured policies.
Protected Information is any type of information and is not altered by the application. They can be used to store sensitive information such as SSH certificate keys or API keys.
Default Request Usage
Every request into WebService A2A must target requests to the base URI. So, lets understand the URI structure.
https://senhasegura/iso/*MODULE*/*FUNCTION*
MODULE: senhasegura WebService A2A function module
FUNCTION: Module function
From this point ahead, you must understand which authentication method you will use.
Without OAuth Authentication
This method is not recommend by senhasegura . Avoid it if OAuth v2.0 can be used.
Every request into WebService A2A should have the client OAuth Consumer Key and the client OAuth Token. By this way, every request URI looks like the following example.
https://senhasegura/iso/*MODULE*/*FUNCTION*?oauth_consumer_key=*KEY*&
oauth_token=*TOKEN*
MODULE: senhasegura WebService A2A function module
FUNCTION: Module function
KEY: Client OAuth key
TOKEN: Client OAuth token
When using a GET method, do not forget to append oauth_consumer_key and oauth_token before the function extra arguments.
When using POST methods, both parameters must be filled at the URL as a GET method.
Using OAuth v1.0 Authentication
This method is not recommend by senhasegura . Avoid it if OAuth v2.0 can be used.
Using OAuth v1.0, ensure that oauth_signature_method used is HMAC-SHA1 and oauth_version is setted to 1.0.
oauth_timestamp, oauth_nonce and oauth_signature are mandatory.
You can find the full spec about OAuth v1.0 at RFC 58492.
Using OAuth v2.0 Authentication
Using OAuth v2.0, your application must renew the authorization token when its expire. By default, senhasegura will create this token valid for a day.
Using the registered and approved Client Key and Client Secret, request a new token to WebService A2A using the following URI:
POST https://senhasegura/iso/oauth2/token
This request must have the Basic Authorization header. See the section "2.3 Client Authentication" into RFC 67493 for better understand.
Your application will receive a JSON dictionary similar as the following example:
{
"token_type": "Bearer",
"expires_in": 3600,
"access_token": "
eyJ0eXAiOiJKV1QiL0IjoxNTgwNDM2NTk4LCJuYmYiOjE1ODA0MzY1OTgsImV4cCI
6MTU4MDQ0MDE5OCwic3ViIjoiTVRNeE1qQWtTRGRPUVRWV1ozcEVSI6Ijg0OWYw
ZmVhNDI0ZDc5NWUwYTg2MjVlMTdiZWE2YTAyNTQyMzAxNjQzYmRmYTc5ZjYzZDN
hM2U3ZmI5ZjQzbGCJhjg0OWYwZmVhNDI0ZDc5NWUwYTg2MjVlMTdiZWE2YTAyNT
QyMzAxNjQzYmRmYTc5ZjYzZDNhM2U3ZmI5ZjQzYmM2MjRhYzg5YmVhMzFhOGQwI
iwiaWFciOiJSUzI1NiIsImp0ahYzg5YmVhMzFhOGQwIn0.eyJhdWQiOiIzY2E4Y
Tk4ZDkwNzU0MzgxMjMzNGY3ZjVkYmFmY2E2NTA1ZTMzMTlmYiIsImp0aSI6IYmM
2MjRTRzB6ZFZONlZXVXhhVWN2Y1RKdFRXNTVhM05sZGtOd1JHeHllbXR5VEV3eE
5EMD0iLCJzY29wZXMiOltdfQ.efqHZdlij6sQcj_l9RbNNKxDbf81CbIoTFwdIk
ooT5bK14N5iUazrT8jpB_JsgQdQ8RyD5xF_ReKSj4Al7hp1uRXIiuErlKv1FpxY
9oNC44kldlumjyevu87GJ0qzem0RYNc3930UbT-XEYqnQijg0se8_GdzdLkxyMn
0kxApkAkv-to9EUdbbrvvno_pmqiZGyamw6J2BL1aCqwne3S8CCG34TXRyJyqkG
rPrDO-NPi2fj25PRbX8Ci1iIqXdYvEkefg-g-i0A_Hp9E3s585c5wqxreSBAIwi
aGtnTkxw0D14JPzqWf48hbvVRPGMj_-KXJTnu-zXkkEPNYs8oWpA"
}
Cache the access_token. It should be used into every next method call. Fill the request header Authorization with the token_type and access_token values. You can check the RFC 6749 section "7.1. Access Token Types" for more details.
It is possible to link an SSL certificate fingerprint to a customer's authorization WebService A2A .
If linked, the senhasegura will validate the CA of the client's SSL certificate with each request, as an additional authentication step.
The use of the certificate does not invalidate or replace validation using OAuth methods.
Providing a new application
For the access to credentials by applications, separately from common users, the senhasegura has the functionality A2A where each application will have its own access group. Also implementing the principle of unique privilege where an application will not have access to the same information as another application.
It is possible to link devices and/or protected information to a WebService A2A authorization.
To perform a provisioning follow the instructions:
Access the menu A2A ➔ Applications and click on the action button of the report, choose the option New
In the form enter the name of the application that will be provisioned and the type of signature that you will use in the field *Use OAuth signature**
Indicate if this application is Active for use
If you want to insert Tags of identification and a Description about the application.
Click Save.
With the configuration done wait for the screen to be updated or use the update button located on the top bar of the report. When the created application is available in the report click on the respective action button and choose the option Authorizations. In this form you will define which credentials the created application will be allowed to access, fill in the information:
Select the System and the Environment that the application will access
Then indicate the credentials that the application will have access to in the field Access Credential and click on the button Add, perform this process for all the credentials you want to include. You can also select the box Register a new credential in the safe to indicate a credential that is not yet registered in the senhasegura , but for this it will be necessary to select the device, which must already be registered in the system, in which this credential grants access, then indicate the username and password of the credential. Click on the add button, perform this process for all the credentials you want to include. The credentials and respective devices that the application will have access to will be listed in the table below.
Go to the tab Security
Indicate which resources the application will have access to:
PAM: Provisioning and querying credentials, SSH keys, and other protected information from the PAM module.
Certificate: Requisitions, consultation, signing and other activities of the Certificate Manager module
Task Manager: Creating and changing Task Manager module activities
Dashboards: Knowledge and consumption of the data printed on the dashboards.
A2A: Consultation and registration of A2A applications.
Determine the type of interaction level of client applications with the senhasegura modules in the PAM resource permission field.
cautionThis field is only required if you have selected the PAM module in the Authorized resources
It is important to remember that if the configuration grants read-only permission users will not be able to attempt to make a change, in which case the following error will be displayed:
{
"response": {
"status": 400,
"mensagem": "1039: Without PAM Configuration Access permission",
"erro": true,
"message": "1039: Without PAM Configuration Access permission",
"error": true
},
"exception": {
"code": 1039,
"message": "1039: Without PAM Configuration Access permission",
"detail": ""
}
}In the *Enable encryption of sensitive information?** field, indicate whether additional encryption will be used to access the application.
Then in the field Allowed IPs you can indicate from which IP's the application can access. To do this click on the button with the add icon and enter the addresses.
In the Referers allowed field you can determine that only referrals with the indicated content will be allowed. To do so, click on the add icon button and enter the allowed contents.
In the field Certificate Validation you can link an SSL certificate fingerprint to authorization.
If linked, the senhasegura will validate the CA of the client's SSL certificate with each certificate authentication process.
cautionUsing the certificate does not replace the validation of the other methods, the certificate will be used in conjunction with OAuth 1 or 2.
This way in addition to authentication with OAuth the user has to send the certificate and key as in the example:
curl --cert /path/to/certificate.crt --key /path/to/certificate.key
--connect-timeout 5 -s --show-error --fail -X POST
-d ${POSTDATA}
"${SENHASEGURA_URL}/iso/oauth2/token"To finish click Save.
Back to the report click again on the action button of the application and choose the option Authorizations. The newly created authorization will be displayed, click on its respective action button and choose the option View. A screen with the Client ID and Client Secret will be displayed, to view each of the information click on the icon as in the image integracao-0005-enus.
Authorizations for the application
In order see a list of all authorizations per application, go to menu A2A ➔ Authorizations for the application. In this screen besides being able to see the authorization details, it is also possible to edit it and create a new one.
The screen will only show the authorizations for the applications that have already been created and saved successfully.
We recommend the use of this screen in order to see a list of authorizations per application in one place, without the need to enter each application individually to check its authorizations.
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.
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. |
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. | Obs. |
|---|---|---|---|---|
| hostname | String | mydevice02 | Yes | |
| ip | String | 22.13.50.71 | Yes | |
| identifier | String | 5 | Yes | |
| username | String | credential05 | Yes |
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
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
HTTP/1.1 200 OK
{
"response": {
"status": 200,
"mensagem": "Information 20",
"erro": false,
"message": "Information 20",
"error": false
},
"info": {
"id": "20",
"tag": "INFOID5",
"type": "Access credential",
"content": "INFOCONTENTNDIGH"
}
}
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 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"
}
}
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
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/remote/session/\[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
}
}
Dashboard Methods
The senhasegura WebService A2A has methods of consulting the information copilated by the Dashboard module.
To use these methods the Dashboards resource must be selected in the application authorization.
Proxy session dashboard
GET /iso/dash/sessions/*
This method will return the number of proxy sessions that have occurred and are still running. Next to the URI path, you must be informed which protocol you want. The other parameters must be provided as a URI query.
Protocols supported
jumpserver: Only proxy sessions that occurred through the senhasegura Terminal Proxy
rdpgate: Only proxy sessions that occurred through senhasegura RDP Proxy
ssh: Only SSH protocol proxy sessions regardless of which proxy technology was used
rdp: Only RDP protocol proxy sessions regardless of what proxy technology was used
rdpweb: Only RDP protocol proxy sessions that occurred through the senhasegura Web Proxy
sshweb: Only SSH protocol proxy sessions that occurred through the senhasegura Web Proxy
all: All sessions performed
Each protocol will return a dictionary containing different nodes representing the proxy technology used. As additional filters, the following parameters can be provided:
| Field | Type | Example | Req. | Obs. |
|---|---|---|---|---|
| ativo | Integer | 1 | No | Provide 1 to indicate that only active sessions should be returned |
| data1 | String | 2020-01-30 | No | Start date of the query period. Format YYYY-MM-DD (ISO 8601) |
| data2 | String | 2020-03-30 | No | End date of the query period. Format YYYYY-MM-DD (ISO 8601) |
| hostname | String | mysrv | No | Hostname of the device to be queried. It must be the same as the hostname registered in the senhasegura . |
| userCredencial | String | mycredusr | No | Username of the credential used to be queried. |
| username | String | myssusr | No | Username of the user passwords that performed the session. |
See the following examples for different queries.
See all sessions
GET /iso/dash/sessions/all
Expected response
HTTP/1.1 200 OK
{
"response": {
"status": 200,
"mensagem": "Sessions",
"erro": false,
"message": "Sessions",
"error": false
},
"sessions": {
"enabled": {
"Jump_Server": "1"
},
"historic": {
"SQL": "1",
"RDP_Web": "35",
"RDP_Gate": "44",
"SSH/Telnet": 76,
"Jump_Server": 411,
"HTTP_VNC": "70"
}
}
}
Response to query of sessions with invalid values
In this example no session will be returned because the data provided are invalid.
{
"response": {
"status": 200,
"mensagem": "Sessions",
"erro": false,
"message": "Sessions",
"error": false
},
"sessions": {
"ativas": [],
"historico": []
}
}
Response to query SSH sessions
In this example only SSH protocol sessions that have occurred, or have started within the period provided, will be returned.
{
"response": {
"status": 200,
"mensagem": "Sessions",
"erro": false,
"message": "Sessions",
"error": false
},
"sessoes": {
"historico": {
"SSH/Telnet": "2",
"Jump_Server": "1"
},
"ativas": {
"Jump_Server": 1
}
}
}
Threat Dashboard
GET /iso/coge/risco/*
This method will return proxy sessions and password custodies that are suspicious. Next to the URI path, you should be informed which type of operation you want. The other parameters must be provided as a URI query.
Queries Modes
all: Returns both the list of suspicious queries and suspicious accesses
queries: Returns only the list of suspicious queries
access: Returns only the list of suspicious accesses
As additional filters, the following parameters may be provided:
date1: Query start date period. Format YYYY-MM-DD (ISO 8601)
date2: Query end date period. Format YYYYY-MM-DD (ISO 8601)
hostname: Hostname of the device to be queried. It must be the same as the hostname registered in the senhasegura.
userCredential: Username of the credential used to be queried.
username: Username of the user senhasegura that you have performed the session
protocol: Set a protocol variable if you need to filter for a particular protocol.
rdp: RDP Proxy Sessions via senhasegura RDP Proxy and senhasegura Web Proxy
rdpweb: RDP proxy sessions via senhasegura Web Proxy
ssh: SSH Sessions from senhasegura Terminal Proxy or senhasegura Web Proxy
sshweb: SSH Sessions from the senhasegura Web Proxy
telnet: Telnet sessions from senhasegura Terminal Proxy or senhasegura Web Proxy
vnchttp: Sessions to websites via senhasegura Web Proxy
rdpgate: RDP Proxy Sessions via senhasegura RDP Proxy
jumpserver: SSH Sessions from the senhasegura senhasegura Terminal Proxy
sql: Database Sessions via senhasegura Web Proxy
all: All proxy options
See the following examples for different queries.
Query all threats
GET /iso/coge/risco/all
Expected response
HTTP/1.1 200 OK
{
"response": {
"status": 200,
"mensagem": "HigherRisk",
"erro": false,
"message": "HigherRisk",
"error": false
},
"higher_risk": {
"queries": [
{
"query_Cod": "2",
"risk": "0",
"query_date": "2021-03-05 10:00:07",
"user_Cod": "87",
"username": "Jose Pedro",
"credential_cod": "1",
"credential": "accounts",
"additional_Info": "",
"device": "Google (google.com)"
},
...
],
"access": [
{
"session_cod": "1",
"host": "172.10.15.20",
"port": "3389",
"protocol": "rdp",
"credential": "usrloclmtd",
"risk": "0",
"start_date": "2021-03-17 02:44:00",
"end_date": "2021-03-17 02:44:34",
"duration": "00:00:34",
"user_Cod": "117",
"username": "usrlmtd"
},
...
]
}
}
Expected response when the query is made with dates reversed
GET /iso/coge/risco/all?data1=2021-01-28&data2=2020-01-29
{
"response": {
"status": 400,
"mensagem": "Date1 greater than date2",
"erro": false,
"message": "Date1 greater than date2",
"error": false
}
}
Expected response when the query is made by providing credential and omitting hostname
GET /iso/coge/risco/all?userCredencial=CREDENTIALDC783
{
"response": {
"status": 400,
"mensagem": "hostname parameter is missing",
"erro": false,
"message": "hostname parameter is missing",
"error": false
}
}
Expected response when the query is made by providing hostname and omitting credential
GET /iso/coge/risco/all?hostname=HOSTNAMEIROHP
{
"response": {
"status": 400,
"mensagem": "userCredencial parameter is missing",
"erro": false,
"message": "userCredencial parameter is missing",
"error": false
}
}
Expected response when the query is made by providing an invalid protocol
GET /iso/coge/risco/all?protocolo=PROTOCOLOO4TZ5
{
"response": {
"status": 400,
"mensagem": "Invalid protocol",
"erro": false,
"message": "Invalid protocol",
"error": false
}
}
Query all suspicious credentials request
GET /iso/coge/risco/queries
Expected response
HTTP/1.1 200 OK
{
"response": {
"status": 200,
"mensagem": "MaiorRisco",
"erro": false,
"message": "MaiorRisco",
"error": false
},
"maior_risco": {
"consultas": [
{
"Cod_Consulta": "1",
"Risco": "0",
"Data_Consulta": "2021-01-11 10:18:32",
"Cod_Usuario": "102",
"Nome_Usuario": "Peter Robinson Green",
"Cod_Credencial": "5",
"Credencial": "fakermainframeuser",
"Info_Adicional": null,
"Dispositivo": "fakeserver (10.20.10.15)"
},
...
]
}
}
Query all suspicious accesses
GET /iso/coge/risco/access
Resposta esperada
HTTP/1.1 200 OK
{
"response": {
"status": 200,
"mensagem": "MaiorRisco",
"erro": false,
"message": "MaiorRisco",
"error": false
},
"maior_risco": {
"acessos": [
{
"Cod_Sessao": "1",
"Host": "10.20.10.18",
"Porta": "3389",
"Protocolo": "rdp",
"Credencial": "usrdomlmtd",
"Risco": "0",
"Data_Inicio": "2020-11-20 16:07:30",
"Data_Fim": "2020-11-20 16:08:09",
"Duracao": "00:00:39",
"Cod_Usuario": "102",
"Nome_Usuario": "Peter Robinson Greenr"
},
...
]
}
}
Credentials Dashboard
GET /iso/dash/credentials/*
This method returns the status of the credentials managed by the senhasegura . To perform the query it is necessary to provide the desired status:
all: All states
expired: Expiry count only
using: Credential count only that are in use
Query all credentials
GET /iso/coge/credentials/all
Expected response
HTTP/1.1 200 OK
{
"response": {
"status": 200,
"mensagem": "Credentials",
"erro": false,
"message": "Credentials",
"error": false
},
"credentials": {
"expired": "1",
"using": "12"
}
}
Query expired credentials
GET /iso/dash/credentials/expired
Expected response
HTTP/1.1 200 OK
{
"response": {
"status": 200,
"mensagem": "Credenciais",
"erro": false,
"message": "Credenciais",
"error": false
},
"credenciais": {
"expiradas": "1"
}
}
Query credentials in use
GET /iso/dash/credentials/using
{
"response": {
"status": 400,
"mensagem": "Invalid request",
"erro": false,
"message": "Invalid request",
"error": false
}
}
Expected response when an invalid state is provided
GET /iso/dash/credentials/expired
{
"response": {
"status": 400,
"mensagem": "Invalid request",
"erro": false,
"message": "Invalid request",
"error": false
}
}
Expected response when no status is provided
GET /iso/dash/credentials/
{
"response": {
"status": 404,
"mensagem": "Resource/sub-resource not found",
"erro": true,
"cod_erro": 1,
"message": "Resource/sub-resource not found",
"error": true,
"error_code": 1
}
}
Certificate Management Methods
To use these methods the Certificates resource must be selected in the application authorization.
Introduction
The senhasegura Certificate Management provide centralized management of the digital certificate lifecycle within the organization, from Discovery through automatic scanning of websites, directories and web servers, to automated Certificate renewal through external or internal Certificate Authorities.
The purpose of this document is to provide guidance for users using Certificate Management administrator roles, and to discuss details about their use, benefits, concepts, and procedures.
How the Certificate Management works
senhasegura Certificate Management manages the entire digital Certificate lifecycle, working with Certificate through request generation, manual importation of existing Certificates, or Discovery of Certificates across Devices, Domains or Containers. In addition to monitoring certificate validity and facilitating renewal, Certificate Management also allows you to view logs and reports on all operations performed through the solution.
Definitions
The senhasegura uses specific terminology for its functions and features. Thus, some terms must be understood before starting to use the solution:
User: Own employees, interns or third parties who use or may need access to company systems;
Digital Certificate: Digital certificates are files that contain public and private key information that is used for secure communication over the Internet, as well as to certify the sender's authenticity
Certification Authority: Certification Authority is an entity duly registered with the responsible bodies and which has the function of issuing digital certificates.
Activities
In this section, the following passwords functions will be covered: make requests, receive answers and senhasegura Certificate Management method.
Method
The senhasegura integration webservice has some methods to query, create or change information stored in the application.
Create / Modify a Request
POST https://vault_url/iso/certificate/request/\[request_code\]
The Create / Modify Request method creates or modifies a certificate request in senhasegura
Parameters
| Field | Type | Description | Required |
|---|---|---|---|
| code_request | Int | Code of an already created request. If the code is not included in the parameter, a new Request will be created. | No |
| certificate_type | Int | Type of certificate. The possible values are: | |
| 1 = DV SSL - Domain SSL; | |||
| 2 = OV SSL - Organization SSL; | |||
| 3 = EV SSL - Extended SSL | Yes | ||
| domain_type | String | Type of the certificate domain. The possible values are: | |
| SING = Single domain | |||
| MULT = Multiple domains | |||
| WILD = Wildcard | Yes | ||
| organization | Int | Code of the organization. The code of an organization registered in passwords must be informed. | Yes |
| common_name | String | Certificate common name | Yes |
| san | Array | Subject Alternative Name. It will be filled with common_name if san is not informed. | No |
| tags | Array | Certificate identification tags. New tags will be registered if the reported ones do not exist | No |
| encryption | String | encryption. The possible values are: RSA | |
| DSA | Yes | ||
| encryption_key_size | Int | Size of the encryption key. The possible values are: | |
| 4096 | |||
| 2048 | |||
| 1024 | Yes | ||
| certificate_algorithm | String | Signature Algorithm. The possible values are: | |
| SHA256 | |||
| SHA384 | |||
| SHA512 | |||
| If the encryption chosen is DSA, then only SHA256 may be used. | Yes | ||
| validity | Int | Certificate validity time, in days. | Yes |
| key_password | String | Password if the certificate key. | No |
| password_revogation | String | Certificate revocation password. | No |
| environments | Array | Certificate environments. New certificate environments will be registered if the informed ones do not exist. | No |
| systems | Array | Certificate systems. New certificate systems will be registered if the informed ones do not exist. | No |
| project | String | Certificate project in request. | No |
| external_ip | String | External IP of the certificate in the request. | No |
| hostname_ip | String | IP or certificate hostname in request. | No |
| justification | String | Request justification of up to 1024 characters. | No |
| responsible | Int | Code of the requester and the certificate. Must be a registered username account in senhasegura . | No |
| description | String | Description of the request up to 512 characters. | No |
Response to certificates
If the method succeeds or fails, the response consists of a certified block with the fields:
| Field | Type | Success | Error |
|---|---|---|---|
| status | Int | , for certificate creation | |
| 200, for certificate editing | 4xx | ||
| message | Text | Created for certificate creation | |
| OK, for certificate editing | Could not create request | ||
| error | N/A | false | true |
| code_request | Int | Request code. | The request code entered is invalid |
| type_certified | Int | Type of the entered certificate. | The certificate type you entered is invalid. |
| type_domain | String | Type of certificate domain entered. | The certificate domain type you entered is invalid. |
| organization | Int | Organization code entered. | The organization code you entered is invalid |
| common_name | String | Common name entered. | Certificate common name not entered |
| san | Array | SAN informed. | |
| tags | Array | Tags informed. | |
| encryption | String | Encryption Algorithm entered. | Encryption algorithm entered is invalid |
| encryption_key_size | Int | Size of encryption key entered. | The encryption key length entered is invalid. |
| certificate_algorithm | String | Signature Algorithm entered. | The signature algorithm entered is invalid. |
| validity | Int | Expiry time of the entered certificate. | Invalid certificate expiration time. |
| password_key | String | Sensitive Information. | Password for certificate key entered is invalid. |
| password_revocation | String | Sensitive Information. | The certificate revocation password you entered is invalid. |
| environments | Array | Informed Environments. | |
| systems | Array | Informed Systems. | |
| design | String | Design informed. | |
| ip_external | String | IP entered. | |
| ip_hostname | String | IP or hostname entered. | |
| justification | String | Informed Justification. | Justification must be a maximum of 1024 characters. |
| responsible | Int | Responsible Code informed. | The parental code you entered is invalid. |
| description | String | Description entered. | Description must be a maximum of 512 characters. |
Query / List Request
GET https://vault_url/iso/certificate/request/list\[request_code\]
The Query / List Request method queries one or more certificate requests on senhasegura .
Parameters
| Field | Type | Description | Required |
|---|---|---|---|
| code_request | Int | Code of an already created Request. | No |
| status request | Int | Code of a status of a request. | No |
| type_certificate | Int | Type of certificate. The possible values are: | |
| 1 = DV SSL - Domain SSL; | |||
| 2 = OV SSL - Organization SSL; | |||
| 3 = EV SSL - Extended SSL | No | ||
| type_domain | String | Type of certificate domain. The possible values are: | |
| SING = Single domain | |||
| MULT = Multiple domains | |||
| WILD = Wildcard | No | ||
| organization | Int | Code of the organization registered in senhasegura . | No |
| common_name | String | Common name of certificate. | No |
| san | String | Subject Alternative Names, separated by comma | No |
| tags | String | Certificate ID tags, comma separated | No |
| encryption | String | Encryption algorithm. The possible values are: | |
| RSA, DSA | No | ||
| encryption_key_size | Int | Size of encryption key. The possible values are: | |
| 4096, 2048, 1024 | No | ||
| algorithm_certified | String | Signature algorithm. The possible values are: | |
| SHA256, SHA384, SHA512 | No | ||
| validity | Int | Certificate validity time in days. | No |
| password_key | String | Certificate key password. | No |
| password_revocation | String | Certificate revocation password. | No |
| environments | String | Certificate Environments, Comma Separated | No |
| systems | String | Certificate Systems, Comma Separated | No |
| design | String | Certificate Design on request. | No |
| ip_external | String | external certificate IP on request. | No |
| ip_hostname | String | IP or certificate hostname on request. | No |
| responsible | Int | Code of the responsible for the request and the certificate. | No |
| offset | Int | Base number of record count by pagination. | No |
| limit | Int | Number of records in pagination. | No |
Response to certificate
If the method succeeds or fails, the response consists of a certified block with the fields:
| Field | Type | Success | Error |
|---|---|---|---|
| status | 4xx | ||
| message | OK | Could not find requests with the information provided | |
| error | false | true | |
| code_request | Int | Request Code. | There is no request with the given code. The request code you entered is invalid. |
| status_request | Request status code and name. | There are no requests with the status entered. The status code you entered is invalid. | |
| type_certified | Int | Type of certificate entered. | There are no requests with the type of certificate entered. The certificate type you entered is invalid. |
| type_domain | String | Type of certificate domain entered. | There are no requests with the domain type you entered. The certificate type domain you entered is invalid. |
| organization | Int | Organization code entered. | There are no requests with the organization code entered. The organization code you entered is invalid. |
| common_name | String | Common name entered. | There are no requests with the given common name. |
| san | Array | SAN informed. | There are no requests with the informed SAN. |
| tags | Array | Tags entered. | There are no requests with the given Tag. |
| encryption | String | Encryption algorithm entered. | There are no requests with the encryption algorithm entered. The encryption algorithm entered is invalid. |
| encryption_key_size | Int | Encryption key size entered. | There are no requests with the encryption key size entered. The encryption key length you entered is invalid. |
| certified_algorithm | String | Signature Algorithm entered. | There are no requests with the signature algorithm entered. The signature algorithm you entered is invalid. |
| validity | Int | Certificate expiration time entered. | There are no requests with the expiration date entered. Invalid certificate expiration time is invalid. |
| password_key | String | Sensitive Information. | There are no requests with the password of the entered key. The certificate key password you entered is invalid. |
| password_revocation | String | Sensitive Information. | There are no requests with the revocation password entered. The certificate revocation password you entered is invalid. |
| environments | Array | Informed environments. | There are no requests with the informed environments. |
| systems | Array | Informed systems. | There are no requests with the informed systems. |
| project | String | Project entered. | There are no requests with the project entered. |
| ip_external | String | IP entered. | No requests with external IP entered. |
| ip_hostname | String | IP or hostname entered. | No requests with IP or hostname entered |
| justification | String | Informed Justification. | |
| Responsible | Int | Code and name of the informed responsible. | There are no requests with the informed responsible’s code.The responsable’s code you entered is invalid. |
| description | String | Description entered. |
Sign Request
GET https://vault_url/iso/certificate/request/sign\[request_code\]
The Sign Request method signs an existing request on senhasegura .
Parameters
| Field | Type | Description | Required |
|---|---|---|---|
| code_request | Int | Code of request to be signed. | Yes |
| self_signed | Int | Indicates whether it is self-signed. The options will be: | |
| 1 = true, 0 = false | Yes | ||
| ca | Int | CA Code responsible for signing request. Required if self_signed is false. | Conditional |
| justification | String | Text up to 1024 characters for justification. | No |
| reason | Int | Subscription Reason Code. You should enter a reason code for a reason entered in senhasegura . | Yes |
| itsm_code | String | characters to determine ITSM code. Required if in the certificate access group the parameter "Governance code required when justifying" is enabled. Perform ITSM validations in the same way as the web interface. | Conditional |
Response to certificate
If the method succeeds or fails, the response consists of a certified block with the fields:
| Field | Type | Success | Error |
|---|---|---|---|
| status | 4xx | ||
| message | OK | Could not sign request. | |
| error | false | true | |
| code_request | Int | Request Code. | Enter a request code.The request code you entered is invalid |
| self_signed | Int | Value entered. | There are no requests for this entered self-signed value.The value for self-signed entered is invalid. |
| ca | Int | CA code and CA name entered. | There are no requests with the CA code entered. The CA code you entered is invalid. |
| justification | String | Informed Justification. | Justification must be a maximum of 1024 characters |
| reason | Int | Reason code and name entered. | Reason code entered is invalid. |
| ITSM code | String | ITSM code entered. | Enter the ITSM code. |
Query / List Certificates
GET https://vault_url/iso/certificate/list/\[request_code\]
The Query / List Certificates method queries one or more certificates in passwords.
Parameters
| Field | Type | Description | Required |
|---|---|---|---|
| code_ certificate | Int | Code of a certificate already created in passwords. | No |
| status_certificate | Int | Code of a status of a certificate. The options will be: | |
| 1 = Valid | |||
| 2 = Revoked | |||
| 3 = Renewal pending | |||
| 4 = Expired | No | ||
| active | Int | Certificate Status on senhasegura . The options will be: | |
| 1 = Active, 0 = Inactive | No | ||
| start_validity | String | Expiry start date | No |
| end_validity | String | Expiry date | No |
| origin_certificate | Int | Certificate origin on senhasegura . The options will be: | |
| SCAN = Scan and Discovery | |||
| REQU = Request | |||
| IMPO = Imported manually | No | ||
| type_certificate | Int | Type of certificate. The options will be: | |
| 1 = DV SSL - Domain SSL | |||
| 2 = OV SSL - Organization SSL | |||
| 3 = EV SSL - Extended SSL | No | ||
| type_domain | String | Type of certificate domain. The options will be: | |
| SING = Single domain | |||
| MULT = Multiple domains | |||
| WILD = Wildcard | No | ||
| organization | Int | Organization code. | No |
| common_name | String | Common name of certificate. | No |
| san | String | Subject Alternative Name. You may enter more than 1 separated by a comma. | No |
| tags | String | Certificate ID Tags. You may enter more than 1 separed by comma. | No |
| encryption | String | Encryption Algorithm. The options will be: | |
| RSA, DSA | No | ||
| encryption_key_size | Int | Size of encryption key. The options will be: | |
| 4096, 2048, 1024 | No | ||
| algorithm_certified | String | Signature Algorithm The options will be: | |
| sha256, sha384, sha512 | No | ||
| Validity | Int | Certificate validity time in number of days. | No |
| password_key | String | Password of certificate key. | No |
| password_revocation | String | Certificate revocation password. | No |
| Environments | String | Certificate Environments. You may enter more than 1 separated by commas. | No |
| Systems | String | Certificate Systems. You may enter more than 1 separated by commas. | No |
| project | String | Certificate project on request. | No |
| ip_external | String | external certificate IP on request. | No |
| ip_hostname | String | IP or certificate hostname on request. | No |
| self_signed | Int | Indicates whether it is self-signed. The options will be: | |
| 1 = true | |||
| 0 = false | No | ||
| ca | Int | CA Code responsible for signing request. | No |
| responsible | Int | Code of the responsible for the request and the certificate. | No |
| offset | Int | Base number of record count by pagination. | No |
| limit | Int | Number of records in pagination. | No |
Response to certificates
If the method succeeds or fails, the response consists of a certified block with the fields:
| Field | Type | Success | Error |
|---|---|---|---|
| status | 4xx | ||
| message | OK | Could not sign request. | |
| error | false | true | |
| code_request | Int | Request Code. | Enter a request code.The request code you entered is invalid |
| status_certified | Int | Code and name of certificate status | There are no certificates with the entered status. The status code you entered is invalid. |
| active | Int | Code and name of the certificate status on senhasegura | There is no certificate with the entered state. The state code you entered is invalid. |
| start_validity | String | Expiry start date | There are no certificates with the stated expiration date. The expiration start date you entered is invalid. |
| end_validity | String | Expiry date | There are no certificates with the stated expiration date. The expiration date entered is invalid. |
| origin_certificate | Int | Certificate origin in passwords secure | There are no certificates with the informed source. The source you entered is invalid. |
| type_certificate | Int | Type of certificate | There are no certificates of the type entered. The certificate type you entered is invalid. |
| type_domain | String | Type of certificate domain | There are no certificates with the domain type you entered. The certificate type domain you entered is invalid. |
| organization | Int | Code and name of the organization you entered | There are no certificates with the organization code entered. The organization code you entered is invalid |
| common_name | String | Common name of certificate | There are no certificates with the common name entered. |
| encryption_key_size | Int | Size of the certificate encryption key | There are no certificates with the encryption key length entered. The encryption key length you entered is invalid. |
| algorithm_certified | String | Certificate Signing Algorithm | There are no certificates with the signature algorithm entered.The signature algorithm you entered is invalid. |
| validity | Int | Certificate validity time | There are no certificates with the entered expiration time. Invalid certificate expiration time is invalid. |
| password_key | String | Certificate key password. | There are no certificates with the entered key password. The certificate key password you entered is invalid. |
| password_revocation | String | Certificate revocation password. | There are no certificates with the revocation password entered. The certificate revocation password you entered is invalid. |
| Environments | String | Certificate Environments | There are no certificates with the environment (s) entered. |
| systems | String | Certificate Systems | There are no certificates with the system (s) entered. |
| project | String | Certificate Design. Eg project 1 | There are no certificates with the project informed. |
| ip_external | String | external certificate IP. | No certificates with external IP entered. |
| ip_hostname | String | IP or certificate hostname | There are no certificates with the given IP or hostname. |
| self_signed | Int | Info if the certificate is self-signed | No certificates exist for this self-signed value entered. The value for self-signed entered is invalid. |
| ca | Int | CA code and CA name entered | There are no certificates with the CA code you entered. The CA code you entered is invalid. |
| Responsible | Int | Code and name of responsible person informed | There are no certificates with the responsible’s code entered. The responsible’s code you entered is invalid. |
| Description | Description of the certificate | ||
| publish_info | Additional information for publication | ||
| device | Devices code attached with certificate |
Functions
The senhasegura webservice has some functionality to perform operations on the application.
Publish Certificate
POST https://vault_url/iso/cert/publish
Publish Certificate functionality prompts you to publish a certificate on one or more devices.
Parameters
| Field | Type | Description | Required |
|---|---|---|---|
| code_certificate | Int | Code of a certificate to be publish. | Yes |
| code_profile_publication | Int | Publish profile code.A publication profile previously registered on senhasegura will be used. | Yes |
| justification | String | Justification of publication up to 1024 characters. | No |
| reason | Int | Publication reason code.You must enter a code for a reason entered on senhasegura . | Yes |
| itms_code | String | characters to determine ITSM code.Required if in the certificate access group the parameter "Governance code required when justifying" is enabled. Perform ITSM validations in the same way as the web interface. | Conditional |
| devices | Array | Array with the codes of the devices where the certificate is to be published | |
| Devices must exist on senhasegura . | Yes |
Response to certificates
If the functions succeeds or fails, the response consists of a certified block with the fields:
| Field | Type | Success | Error |
|---|---|---|---|
| status | 4xx | ||
| message | Created | Invalid certificate code. | |
| error | false | true | |
| code_publishing | Posting scheduling code | ||
| reason | Code and name of reason for publication | Reason code entered is invalid. | |
| itms_code | String | ITSM code entered | Enter the ITSM code. ITSM code does not exist on senhasegura integrated ITSM system. The code must be a maximum of 30 characters. |
| devices | Array | Device Codes for Publishing |
Query / List Publications
GET https://vault_url/iso/cert/publish/\[code_request\]
The Query / List Publications feature queries one or more publications on senhasegura .
Parameters
| Field | Type | Description | Required |
|---|---|---|---|
| code_publication | Int | Publication code. | No |
| code_certified | Int | Code of certificate to be published. | No |
| code_profile_publication | Int | Publish Profile Code. | No |
| creation_date | String | Date of registration | No |
| processed | Int | Publication processing status.The options will be: | |
| 1 = Yes | |||
| 0 = No | No | ||
| error | Int | Publication Error Status.The options will be: | |
| 1 = Yes | |||
| 0 = No | No | ||
| reason | Int | Publication reason code. | No |
| itms_code | String | ITSM code Text reported. | No |
| device | Int | Device code of the publication. | No |
| offset | Int | Base number of record count by pagination. | No |
| limit | Int | Number of records in pagination. | No |
Response to certificates
If the function succeeds or fails, the response consists of a certified block with the fields:
| Field | Type | Success | Error |
|---|---|---|---|
| status | 4xx | ||
| message | Created | Invalid certificate code. | |
| error | false | true | |
| code_publishing | Posting scheduling code | ||
| reason | Code and name of reason for publication | Reason code entered is invalid. | |
| itms_code | String | ITSM code entered | Enter the ITSM code. ITSM code does not exist on senhasegura integrated ITSM system. The code must be a maximum of 30 characters. |
| code_credential | Publishing credential code | The credential code you entered is invalid. | |
| username | Username for credential search | ||
| quantity_devices | Number of devices in the publication |
Create/Edit Apache Publication Profile
POST https://vault_url/iso/cert/profile/apache
Create / Edit Apache Publishing Profile function creates or edits an Apache plugin publishing profile.
Parameters
| Field | Type | Description | Required |
|---|---|---|---|
| code_profile | Int | Code of an already created profile.If the code is not passed, the system will interpret it as creating a profile. | No |
| name_profile | String | Name of profile to create. | Yes |
| site | String | Site where the certificate is to be installed. | |
| If not entered, the certificate will be installed on the default Apache site. | No | ||
| config_path | String | Address of the configuration.Standard: | |
| /etc/apache2/sites-available/default.com.conf | No | ||
| port | Int | Port. | |
| Default:443 | No | ||
| code_credential | Int | Credential code to be used in the publication. A credential previously registered in the vault will be used.This information is required if a username is not entered. | Conditional |
| username | String | Username that will be used to find credentials for the publication. | |
| This information is required if you do not enter a code_credential | Conditional | ||
| devices | Array | Array with the codes of the devices where the certificate is to be published | Yes |
Response to certificates
If the function succeeds or fails, the response consists of a certified block with the fields:
| Field | Type | Success | Error |
|---|---|---|---|
| status | - Created | ||
| 200 - Edit | 4xx | ||
| message | Created | Invalid certificate code. | |
| error | false | true | |
| code_path | String | Profile name | The code of profile informed is invalid |
| name_profile | String | Profile name | |
| site | String | Informed Text | |
| config_path | String | Configured Path | |
| port | Int | Port | |
| code_credential | Int | Credential code to publication | The credential code informed is invalid |
| username | String | Username to search credentials | |
| devices | Array | Devices’ code to publication |
Create/Edit IIS Publication Profile
POST https://vault_url/iso/cert/profile/iis
Create/Edit IIS Publication Profile function creates or edits an Apache plugin publishing profile.
Parameters
| Field | Type | Description | Required |
|---|---|---|---|
| code_profile | Int | Code of an already created profile.If the code is not passed, the system will interpret it as creating a profile. | No |
| name_profile | String | Name of profile to create. | Yes |
| site | String | Site where the certificate is to be installed. | |
| If not entered, the certificate will be installed on the default IIS site. | No | ||
| cert_store | String | IIS certificate management repository.Default: MY | No |
| port | Int | Port. | |
| Default:443 | No | ||
| code_credential | Int | Credential code to be used in the publication. A credential previously registered in the vault will be used.This information is required if a username is not entered. | Conditional |
| username | String | Username that will be used to find credentials for the publication. | |
| This information is required if you do not enter a code_credential | Conditional | ||
| devices | Array | Array with the codes of the devices where the certificate is to be published | Yes |
Response to certificates
If the function succeeds or fails, the response consists of a certified block with the fields:
| Field | Type | Success | Error |
|---|---|---|---|
| status | - Created | ||
| 200 - Edit | 4xx | ||
| message | Created | Invalid certificate code. | |
| error | false | true | |
| code_path | String | Profile name | The code of profile informed is invalid |
| name_profile | String | Profile name | |
| site | String | Informed Text | |
| cert_store | String | IIS certificate management repository | |
| port | Int | Port | |
| code_credential | Int | Credential code to publication | The credential code informed is invalid |
| username | String | Username to search credentials | |
| devices | Array | Devices’ code to publication |
Create/Edit F5 Big IP Publication Profile
POST https://vault_url/iso/cert/profile/bigip
Create/Edit F5 Big IP Publication Profile function creates or edits an Apache plugin publishing profile.
Parameters
| Field | Type | Description | Required |
|---|---|---|---|
| code_profile | Int | Code of an already created profile.If the code is not passed, the system will interpret it as creating a profile. | No |
| name_profile | String | Name of profile to create. | Yes |
| name_partition | String | Name of the partition | No |
| name_cert | String | Name of the certificate. If a certificate with the same name is already configured, on publication it will be replaced. | No |
| profile_client_vips | Array | Array of SSL Client Profiles and their VIPs | No |
| profile_server_vips | Array | Array of SSL Server Profiles and their VIPs | No |
| code_credential | Int | Credential code to be used in the publication. A credential previously registered in the vault will be used.This information is required if a username is not entered. | Conditional |
| username | String | Username that will be used to find credentials for the publication. | |
| This information is required if you do not enter a code_credential | Conditional | ||
| devices | Array | Array with the codes of the devices where the certificate is to be published | Yes |
Response to certificates
If the function succeeds or fails, the response consists of a certified block with the fields:
| Field | Type | Success | Error |
|---|---|---|---|
| status | - Created | ||
| 200 - Edit | 4xx | ||
| message | Created | Invalid certificate code | |
| error | false | true | |
| code_profile | Int | Publish profile code | The code of profile informed is invalid |
| name_profile | String | Profile name | |
| name_partition | String | Name of the profile | |
| name_certificate | String | Name of the certificate that is shown on the web application | |
| profile_client | Array | Complete name of the profile | |
| profile_server | Array | Complete name of the profile | |
| code_credential | Int | Credential code to publication | The credential code informed is invalid |
| username | String | Username to search credentials | |
| devices | Array | Device’s code to publication |
Create/Edit WebSphere WAS Profile Publication
POST https://vault_url/iso/cert/profile/was
Create/Edit WebSphere WAS Profile Publication function creates or edits an Apache plugin publishing profile.
Parameters
| Field | Type | Description | Required |
|---|---|---|---|
| code_profile | Int | Code of an already created profile. If the code is not passed, the system will interpret it as creating a profile. | No |
| name_profile | String | Name of profile to create. | Yes |
| key_db_path | String | Path of the Key database name | Yes |
| key_db_password | String | Server’s password | Yes |
| label | String | Server’s label | Yes |
| code_credential | Int | Credential code to be used in the publication. A credential previously registered in the vault will be used.This information is required if a username is not entered. | Conditional |
| username | String | Username that will be used to find credentials for the publication. | |
| This information is required if you do not enter a code_credential | Conditional | ||
| devices | Array | Array with the codes of the devices where the certificate is to be published | Yes |
Response to certificates
| Field | Type | Success | Error |
|---|---|---|---|
| status | - Created | ||
| 200 - Edit | 4xx | ||
| message | Created | Invalid certificate code. | |
| error | false | true | |
| code_profile | Int | Publish profile code | The code of profile informed is invalid |
| name_profile | String | Profile name | |
| key_db_path | String | Path of the Key database name | |
| label | String | Server’s label | |
| code_credential | Int | Credential code to publication | The credential code informed is invalid |
| username | String | Username to search credentials | |
| devices | Array | Devices’ code to publication |
DevSecOps Methods
Introduction
The senhasegura DevOps Secret Management (DSM) offers a rapid and secure way for tools and applications to request confidential information such as secrets, credentials and other sensitive data that are used on DevOps lifecycle.
The purpose of this section is to provide guidance for DevOps teams that need integration with senhasegura to manage all secrets used on their pipeline.
In this section, the following DevOps functions will be covered:
Request a secret to be used on an application
Provision a new credential to be used on an applications
Deprovision a credential
Method
The senhasegura web integration service has a method for query secrets stored in the application.
Query secret
GET https://vault_url/iso/dapp/application
The application method queries all secrets linked to an application authorization.
Response
| Field | Type | Description |
|---|---|---|
| name | String | Application name |
| description | String | Application description |
| tags | String | Tags that identify the application |
| system | String | Secret system |
| environment | String | Secret environment |
| secret _id | Integer | Secret ID |
| secret_name | String | Secret Name |
| identity | String | Secret identifier |
| version | String | Secret version |
| expiration_date | Date/Time | Secret expiration date |
| engine | String | Secret engine |
| data | String | Secret values |
| Field | Type | Description |
|---|---|---|
| nome | String | Application name. |
| descrição | String | Application description. |
| tags | String | Application tags to be used as filters inside senhasegura . |
| sistema | String | Secret system. |
| ambiente | String | Secret environment. |
| secret _id | Integer | Secret ID. |
| secret_name | String | Secret name. |
| identificador | String | Secret identification. Free for use. |
| versão | String | Secret version number. |
| expiration_date | Date/Time | Secret expiration time. |
| motor | String | Secret engine. |
| valores | String | Secret values. |
{
"response": {
"status": 200,
"mensagem": "Application 5",
"erro": false,
"message": "Application 5",
"error": false
},
"application": {
"name": "postman",
"description": null,
"tags": [
""
],
"system": "back",
"environment": "test",
"secrets": [
{
"secret_id": "106",
"secret_name": "application5",
"identity": "application5",
"version": "",
"expiration_date": "",
"engine": "Kubernetes",
"data": [
{
"hostname": "application5_v_test",
"username": "ADMIN_V_USR",
"password": "ADMIN_V_PW",
"additional_information": "ADMIN_V_SCHEMA"
},
{
"access_key_id": "LKU5YC6QWAT487S4KEK",
"secret_access_key": "sack10821du07f9sacfsdaasdf",
"TTL": null
},
{
"my_key_name": "my_key_value",
"my_key_name_2": "my_key_value_2"
}
]
}
]
}
}
Provision a credential
POST https://vault_url/iso/coe/dapp/provision
Create a new credential secret to be used on a container
Parameters
| Field | Type | Description | Required |
|---|---|---|---|
| pod_name | String | Name of the pod that will use the credential | Yes |
| deploy | String | Name of the deploy that will use the credential | Yes |
| namespace | String | Namespace of the container that will use the credential | Yes |
Response
| Field | Type | Description |
|---|---|---|
| name | String | Application name |
| description | String | Application description |
| tags | String | Tags that identify the application |
| system | String | Secret system |
| environment | String | Secret environment |
| secret_id | Integer | Secret ID |
| secret_name | String | Secret Name |
| identity | String | Secret identifier |
| version | String | Secret version |
| expiration_date | Date/Time | Secret expiration date |
| engine | String | Secret engine |
| data | String | Secret values |
{
"response": {
"status": 200,
"mensagem": "Application 6",
"erro": false
},
"application": {
"name": "runb",
"description": null,
"tags": [
""
],
"system": "senhasegura",
"environment": "lab",
"secrets": [
{
"secret_id": "3",
"secret_name": "secure-demo",
"identity": "secure-demo",
"version": "",
"expiration_date": "",
"engine": "Kubernetes",
"data": {
"APP_VAR1": "fX6v8vh7TADY",
"APP_VAR2": "vlln0XkBNWIk",
"APP_VAR3": "7qWgm1EBFnQb",
"APP_DB_PASSWORD": "4i8Vm0khqTWs",
"APP_SECRET": "GSePWjXyd91K"
}
}
]
}
}
Deprovision a credential
POST https://vault_url/iso/coe/dapp/deprovision
Deprovision a credential secret to be used on a container
Parameters
| Field | Type | Description | Required |
|---|---|---|---|
| pod_name | String | Name of the pod that will use the credential | Yes |
| deploy | String | Name of the deploy that will use the credential | Yes |
| namespace | String | Namespace of the container that will use the credential | Yes |
| secret_id | Integer | Secret ID | Yes |
External agents
WebService A2A Java Agent
The purpose of this section is to assist users with administrator privileges to install the WebService A2A agent and provide a communication interface for performing passwords routines. In this document we will use the Java library as an example. All libraries use the same REST channel to communicate with senhasegura , making it easy to develop in any language that supports REST webservice.
This SDK grants to applications, access to privileged informations (using cache feature) and also database connection objects.
The supported DBMS technologies are: MySQL, Oracle and PostGreSQL.
With this agent applications can connect with databases without need to manage authentication and get the access credential.
Activities
In this section, the following senhasegura functions will be covered:
Java Lib Agent Operation
Agent Compatible Java Versions
senhasegura settings
Example of use
Compatible Java version
The Java Lib 0.1.5 agent is compatible with Java version 1.5 or higher, which allows you to cache passwords on the agent, thus avoiding queries in the vault.
Agent version 0.1.4 is compatible with lower versions of Java 1.5, but does not provide password caching.
Native Java cache
Using the WebService A2A Java Agent, the client application will use a protected local cache to store all requested credentials. This feature grants to the application a better performance and a safe local backup for situations when senhasegura is out of reach.
If the target credential has change. The WebService A2A Java Agent will failure to contruct the database object and will request again the credential password for senhasegura . And if the new password retrived fail too, an exception will be triggered to warn the client application.
Creating a database connection
With this example it is possible to create a connection with a database using a specific credential vaulted by senhasegura without the need to share the user and password with the application.
The Consumer Key and Consumer Secret values are used to enable the customer to consume senhasegura features:
package br.com.mt4.senhasegura;
import java.io.IOException;
import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
//#########################################################
// senhasegura connection class
import br.com.mt4.senhasegura.sql.ConnectionFactory;
//#########################################################
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
public class QueryServlet extends HttpServlet {
public void doPost(HttpServletRequest request,
HttpServletResponse response) throws IOException, ServletException {
try {
String url = request.getParameter("url");
String consumerKey = request.getParameter("consumerkey");
String consumerSecret = request.getParameter("consumersecret");
String tokenKey = request.getParameter("tokenkey");
String tokenSecret = request.getParameter("tokensecret");
if (url.endsWith("/") == false) {
url = url + "/";
}
// clear cache flag
Boolean isClearCache = false;
isClearCache = request.getParameter("clearCache").equals("clear");
// ###################
// SENHASEGURA - START
// Connection factory
ConnectionFactory factory = new ConnectionFactory(url,
consumerKey, consumerSecret, tokenKey, tokenSecret);
factory.setReferer(request.getRequestURL().toString());
// Clear the cache if needed
if (isClearCache)
factory.clearCacheById(
Integer.parseInt(request.getParameter("id")));
// Get database connection with specified password
Connection con = factory.getConnection(
Integer.parseInt(request.getParameter("id")));
// SENHASEGURA - END
// ###################
// Prepare statement with query
PreparedStatement stmt = con.prepareStatement(
request.getParameter("query"));
// Run a query
ResultSet rs = stmt.executeQuery();
// Table
response.getWriter().println(
"<table class='table table-condensed table-bordered'>");
// Header
response.getWriter().println("<thead><tr>");
for (int i = 1; i <= rs.getMetaData().getColumnCount(); i++) {
response.getWriter().println(
"<th>" + rs.getMetaData().getColumnName(i) + "</th>");
}
response.getWriter().println("</tr></thead>");
// iterate on the ResultSet
response.getWriter().println("<tbody>");
while (rs.next()) {
response.getWriter().println("<tr>");
for (int i = 1; i <= rs.getMetaData().getColumnCount(); i++) {
response.getWriter().println(
"<td>" + rs.getString(i) + "</td>");
}
response.getWriter().println("</tr>");
}
response.getWriter().println("</tbody>");
response.getWriter().println("</table>");
rs.close();
stmt.close();
con.close();
} catch (Exception e) {
response.getWriter().println(
"<div class='alert alert-danger'><b>Error: </b>"
+ e.getMessage() + "</div>");
response.getWriter().println("<pre>");
e.printStackTrace(response.getWriter());
response.getWriter().println("</pre>");
}
}
}
Traceability
In a productive environment, changes are constants and essential to improving the process. However, knowing "why, how, and by who" the changes have been made is needed.
The purpose of these reports is to display information on all changes made to data registered in senhasegura .
API logs
In Orbit ➔ Logs ➔ API the API logs report will print the following information:
ID: is the unique request identifier
Client ID: is the application identifier
Client: is the application name
Authorization ID: is the authorization identifier
Authorization: is the Authorization word followed by authorization identifier
IP: is the request IP address
Resource: is the used resource name
Event: is the event type
Method: used in the request (GET, POST, DELETE)
Status: is the HTTP response code
URL: is the method address
Error: of the request
Time: is the duration of the request
Date Time: of the request
Best Practices for Use
In this chapter you will find a list of best practices for the safe use of the WebService A2A module. If you have any questions, please contact our support team.
Set only one credential per WebService A2A authorization. In this way, this practice will reduce the risk surface since the authorization will be tied to only one credential; thus, the tracking of activities is centralized. In case of vulnerability, the response will be faster by disabling one credential instead of several.
Define that WebService A2A authorization has the origin IP restriction set only for the Servers (and their redundancies) that manage the applications that need access to the credentials of senhasegura . Be aware that the principle of least privilege should also be applied to machines, defining a policy that grants access only to servers that performing their tasks need to use the credentials managed by senhasegura .
Give preference to using the Oauth 2.0 signature (more secure) over using Oauth 1.0. Always opt for the most up-to-date standards that correspond to more robust security levels and are compatible with your asset technology.
Enable the Enable encryption of sensitive information functionality for queries through the senhasegura API, and segment that the credential query module and the sensitive information decryption module, be performed by different developers, so that none of them has access to the complete information (Credential query and decryption);
Implement the query for the credentials needed by the application, so that they are brought in during application execution, and no need to store them in any file. Storing the credential information in a file outside of your senhasegura management will leave the credential vulnerable to unauthorized access, and your queries cannot be traced, resulting in irresponsible use of the credentials.
Instruct the programmer to make a local cache of the credential, with lifetime control. This way, if the senhasegura is unavailable, momentary or not, the application will not stop running because it will have the local cache to query. This practice can prevent tasks from being paralyzed and causing the unavailability of a vital service.
Match the lifetime of the local cache with the password rotation time of the senhasegura . This way, the password stored in the local cache will not be outdated compared to the credential managed by senhasegura , making authentication impossible in case of unavailability since the password will be different. Advise the programmer that in case the password returns a connectivity error to query the senhasegura again to verify that the password in question has not already been rotated. Remember that depending on the settings applied to the senhasegura the passwords may rotate frequently, so the local cache may become out of date.