Skip to main content
Version: 3.21

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

caution

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

caution

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

caution

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.

info

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.

info

It is possible to link devices and/or protected information to a WebService A2A authorization.

To perform a provisioning follow the instructions:

  1. Access the menu A2A ➔ Applications and click on the action button of the report, choose the option New

  2. 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**

  3. Indicate if this application is Active for use

  4. If you want to insert Tags of identification and a Description about the application.

  5. Click Save.

Application Form

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:

  1. Select the System and the Environment that the application will access

  2. 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.

  3. Go to the tab Security

  4. 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.

  5. Determine the type of interaction level of client applications with the senhasegura modules in the PAM resource permission field.

    caution

    This 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": ""
    }
    }
  6. In the *Enable encryption of sensitive information?** field, indicate whether additional encryption will be used to access the application.

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

  8. 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.

  9. 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.

    caution

    Using 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"
  10. To finish click Save.

Application Authorization Form

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.

Visualization of application authorizations

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.

caution

The screen will only show the authorizations for the applications that have already been created and saved successfully.

info

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.

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:

FieldTypeExampleReq.Obs.
hostnameStringmydevice02Yes
ipString22.13.50.71Yes
siteStringAWSYes
modelStringCentOS 7Yes
vendorStringCentOSYes
typeStringServerYesShould 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:

FieldTypeExampleReq.Obs.
hostnameStringmydevice02Yes
ipString22.13.50.71Yes
identifierString5Yes
usernameStringcredential05Yes
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
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:

FieldTypeExampleReq.Obs.
contentStringMy secret dataYesSecret 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:

FieldTypeExampleReq.Obs.
contentStringMy scret dataYesPlain-text content to be protected. File upload is not available.
identifierStringINFO1298NoUnique identificator used to request this data.
nameStringMy protected infoNoInformation name to be presented into senhasegura pages.
typeStringAccess credentialNoInformation 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:

FieldTypeExampleReq.Obs.
userStringsenhasegura-userYesUsername for authentication on senhasegura . It must exist on the solution.
credentialStringadminYesCredential username to be used for web session.
deviceString172.12.32.14YesHostname or IP from the target device.
protocolStringSSHYesNetwork protocol (SSH, RDP, HTTPS...).
remotedeviceString123NoDevice ID, IP ou Hostname for web session. Necessary only for sessions that use domain credentials.
remoteAddrstring201.13.25.61NoUser connection IP address. The session will works online troghtout this IP address.
portInt22NoPort to be used on the session. If not informed, the default port set on the device will be used.
remoteappInt123NoRemoteApp 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/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.

caution

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:

FieldTypeExampleReq.Obs.
ativoInteger1NoProvide 1 to indicate that only active sessions should be returned
data1String2020-01-30NoStart date of the query period. Format YYYY-MM-DD (ISO 8601)
data2String2020-03-30NoEnd date of the query period. Format YYYYY-MM-DD (ISO 8601)
hostnameStringmysrvNoHostname of the device to be queried. It must be the same as the hostname registered in the senhasegura .
userCredencialStringmycredusrNoUsername of the credential used to be queried.
usernameStringmyssusrNoUsername 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

caution

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
FieldTypeDescriptionRequired
code_requestIntCode of an already created request. If the code is not included in the parameter, a new Request will be created.No
certificate_typeIntType of certificate. The possible values are:
1 = DV SSL - Domain SSL;
2 = OV SSL - Organization SSL;
3 = EV SSL - Extended SSLYes
domain_typeStringType of the certificate domain. The possible values are:
SING = Single domain
MULT = Multiple domains
WILD = WildcardYes
organizationIntCode of the organization. The code of an organization registered in passwords must be informed.Yes
common_nameStringCertificate common nameYes
sanArraySubject Alternative Name. It will be filled with common_name if san is not informed.No
tagsArrayCertificate identification tags. New tags will be registered if the reported ones do not existNo
encryptionStringencryption. The possible values are: RSA
DSAYes
encryption_key_sizeIntSize of the encryption key. The possible values are:
4096
2048
1024Yes
certificate_algorithmStringSignature Algorithm. The possible values are:
SHA256
SHA384
SHA512
If the encryption chosen is DSA, then only SHA256 may be used.Yes
validityIntCertificate validity time, in days.Yes
key_passwordStringPassword if the certificate key.No
password_revogationStringCertificate revocation password.No
environmentsArrayCertificate environments. New certificate environments will be registered if the informed ones do not exist.No
systemsArrayCertificate systems. New certificate systems will be registered if the informed ones do not exist.No
projectStringCertificate project in request.No
external_ipStringExternal IP of the certificate in the request.No
hostname_ipStringIP or certificate hostname in request.No
justificationStringRequest justification of up to 1024 characters.No
responsibleIntCode of the requester and the certificate. Must be a registered username account in senhasegura .No
descriptionStringDescription 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:

FieldTypeSuccessError
statusInt, for certificate creation
200, for certificate editing4xx
messageTextCreated for certificate creation
OK, for certificate editingCould not create request
errorN/Afalsetrue
code_requestIntRequest code.The request code entered is invalid
type_certifiedIntType of the entered certificate.The certificate type you entered is invalid.
type_domainStringType of certificate domain entered.The certificate domain type you entered is invalid.
organizationIntOrganization code entered.The organization code you entered is invalid
common_nameStringCommon name entered.Certificate common name not entered
sanArraySAN informed.
tagsArrayTags informed.
encryptionStringEncryption Algorithm entered.Encryption algorithm entered is invalid
encryption_key_sizeIntSize of encryption key entered.The encryption key length entered is invalid.
certificate_algorithmStringSignature Algorithm entered.The signature algorithm entered is invalid.
validityIntExpiry time of the entered certificate.Invalid certificate expiration time.
password_keyStringSensitive Information.Password for certificate key entered is invalid.
password_revocationStringSensitive Information.The certificate revocation password you entered is invalid.
environmentsArrayInformed Environments.
systemsArrayInformed Systems.
designStringDesign informed.
ip_externalStringIP entered.
ip_hostnameStringIP or hostname entered.
justificationStringInformed Justification.Justification must be a maximum of 1024 characters.
responsibleIntResponsible Code informed.The parental code you entered is invalid.
descriptionStringDescription 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
FieldTypeDescriptionRequired
code_requestIntCode of an already created Request.No
status requestIntCode of a status of a request.No
type_certificateIntType of certificate. The possible values are:
1 = DV SSL - Domain SSL;
2 = OV SSL - Organization SSL;
3 = EV SSL - Extended SSLNo
type_domainStringType of certificate domain. The possible values are:
SING = Single domain
MULT = Multiple domains
WILD = WildcardNo
organizationIntCode of the organization registered in senhasegura .No
common_nameStringCommon name of certificate.No
sanStringSubject Alternative Names, separated by commaNo
tagsStringCertificate ID tags, comma separatedNo
encryptionStringEncryption algorithm. The possible values are:
RSA, DSANo
encryption_key_sizeIntSize of encryption key. The possible values are:
4096, 2048, 1024No
algorithm_certifiedStringSignature algorithm. The possible values are:
SHA256, SHA384, SHA512No
validityIntCertificate validity time in days.No
password_keyStringCertificate key password.No
password_revocationStringCertificate revocation password.No
environmentsStringCertificate Environments, Comma SeparatedNo
systemsStringCertificate Systems, Comma SeparatedNo
designStringCertificate Design on request.No
ip_externalStringexternal certificate IP on request.No
ip_hostnameStringIP or certificate hostname on request.No
responsibleIntCode of the responsible for the request and the certificate.No
offsetIntBase number of record count by pagination.No
limitIntNumber of records in pagination.No
Response to certificate

If the method succeeds or fails, the response consists of a certified block with the fields:

FieldTypeSuccessError
status4xx
messageOKCould not find requests with the information provided
errorfalsetrue
code_requestIntRequest Code.There is no request with the given code. The request code you entered is invalid.
status_requestRequest status code and name.There are no requests with the status entered. The status code you entered is invalid.
type_certifiedIntType of certificate entered.There are no requests with the type of certificate entered. The certificate type you entered is invalid.
type_domainStringType of certificate domain entered.There are no requests with the domain type you entered. The certificate type domain you entered is invalid.
organizationIntOrganization code entered.There are no requests with the organization code entered. The organization code you entered is invalid.
common_nameStringCommon name entered.There are no requests with the given common name.
sanArraySAN informed.There are no requests with the informed SAN.
tagsArrayTags entered.There are no requests with the given Tag.
encryptionStringEncryption algorithm entered.There are no requests with the encryption algorithm entered. The encryption algorithm entered is invalid.
encryption_key_sizeIntEncryption key size entered.There are no requests with the encryption key size entered. The encryption key length you entered is invalid.
certified_algorithmStringSignature Algorithm entered.There are no requests with the signature algorithm entered. The signature algorithm you entered is invalid.
validityIntCertificate expiration time entered.There are no requests with the expiration date entered. Invalid certificate expiration time is invalid.
password_keyStringSensitive Information.There are no requests with the password of the entered key. The certificate key password you entered is invalid.
password_revocationStringSensitive Information.There are no requests with the revocation password entered. The certificate revocation password you entered is invalid.
environmentsArrayInformed environments.There are no requests with the informed environments.
systemsArrayInformed systems.There are no requests with the informed systems.
projectStringProject entered.There are no requests with the project entered.
ip_externalStringIP entered.No requests with external IP entered.
ip_hostnameStringIP or hostname entered.No requests with IP or hostname entered
justificationStringInformed Justification.
ResponsibleIntCode and name of the informed responsible.There are no requests with the informed responsible’s code.The responsable’s code you entered is invalid.
descriptionStringDescription entered.

Sign Request

GET https://vault_url/iso/certificate/request/sign\[request_code\] 

The Sign Request method signs an existing request on senhasegura .

Parameters
FieldTypeDescriptionRequired
code_requestIntCode of request to be signed.Yes
self_signedIntIndicates whether it is self-signed. The options will be:
1 = true, 0 = falseYes
caIntCA Code responsible for signing request. Required if self_signed is false.Conditional
justificationStringText up to 1024 characters for justification.No
reasonIntSubscription Reason Code. You should enter a reason code for a reason entered in senhasegura .Yes
itsm_codeStringcharacters 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:

FieldTypeSuccessError
status4xx
messageOKCould not sign request.
errorfalsetrue
code_requestIntRequest Code.Enter a request code.The request code you entered is invalid
self_signedIntValue entered.There are no requests for this entered self-signed value.The value for self-signed entered is invalid.
caIntCA code and CA name entered.There are no requests with the CA code entered. The CA code you entered is invalid.
justificationStringInformed Justification.Justification must be a maximum of 1024 characters
reasonIntReason code and name entered.Reason code entered is invalid.
ITSM codeStringITSM 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
FieldTypeDescriptionRequired
code_ certificateIntCode of a certificate already created in passwords.No
status_certificateIntCode of a status of a certificate. The options will be:
1 = Valid
2 = Revoked
3 = Renewal pending
4 = ExpiredNo
activeIntCertificate Status on senhasegura . The options will be:
1 = Active, 0 = InactiveNo
start_validityStringExpiry start dateNo
end_validityStringExpiry dateNo
origin_certificateIntCertificate origin on senhasegura . The options will be:
SCAN = Scan and Discovery
REQU = Request
IMPO = Imported manuallyNo
type_certificateIntType of certificate. The options will be:
1 = DV SSL - Domain SSL
2 = OV SSL - Organization SSL
3 = EV SSL - Extended SSLNo
type_domainStringType of certificate domain. The options will be:
SING = Single domain
MULT = Multiple domains
WILD = WildcardNo
organizationIntOrganization code.No
common_nameStringCommon name of certificate.No
sanStringSubject Alternative Name. You may enter more than 1 separated by a comma.No
tagsStringCertificate ID Tags. You may enter more than 1 separed by comma.No
encryptionStringEncryption Algorithm. The options will be:
RSA, DSANo
encryption_key_sizeIntSize of encryption key. The options will be:
4096, 2048, 1024No
algorithm_certifiedStringSignature Algorithm The options will be:
sha256, sha384, sha512No
ValidityIntCertificate validity time in number of days.No
password_keyStringPassword of certificate key.No
password_revocationStringCertificate revocation password.No
EnvironmentsStringCertificate Environments. You may enter more than 1 separated by commas.No
SystemsStringCertificate Systems. You may enter more than 1 separated by commas.No
projectStringCertificate project on request.No
ip_externalStringexternal certificate IP on request.No
ip_hostnameStringIP or certificate hostname on request.No
self_signedIntIndicates whether it is self-signed. The options will be:
1 = true
0 = falseNo
caIntCA Code responsible for signing request.No
responsibleIntCode of the responsible for the request and the certificate.No
offsetIntBase number of record count by pagination.No
limitIntNumber of records in pagination.No
Response to certificates

If the method succeeds or fails, the response consists of a certified block with the fields:

FieldTypeSuccessError
status4xx
messageOKCould not sign request.
errorfalsetrue
code_requestIntRequest Code.Enter a request code.The request code you entered is invalid
status_certifiedIntCode and name of certificate statusThere are no certificates with the entered status. The status code you entered is invalid.
activeIntCode and name of the certificate status on senhaseguraThere is no certificate with the entered state. The state code you entered is invalid.
start_validityStringExpiry start dateThere are no certificates with the stated expiration date. The expiration start date you entered is invalid.
end_validityStringExpiry dateThere are no certificates with the stated expiration date. The expiration date entered is invalid.
origin_certificateIntCertificate origin in passwords secureThere are no certificates with the informed source. The source you entered is invalid.
type_certificateIntType of certificateThere are no certificates of the type entered. The certificate type you entered is invalid.
type_domainStringType of certificate domainThere are no certificates with the domain type you entered. The certificate type domain you entered is invalid.
organizationIntCode and name of the organization you enteredThere are no certificates with the organization code entered. The organization code you entered is invalid
common_nameStringCommon name of certificateThere are no certificates with the common name entered.
encryption_key_sizeIntSize of the certificate encryption keyThere are no certificates with the encryption key length entered. The encryption key length you entered is invalid.
algorithm_certifiedStringCertificate Signing AlgorithmThere are no certificates with the signature algorithm entered.The signature algorithm you entered is invalid.
validityIntCertificate validity timeThere are no certificates with the entered expiration time. Invalid certificate expiration time is invalid.
password_keyStringCertificate key password.There are no certificates with the entered key password. The certificate key password you entered is invalid.
password_revocationStringCertificate revocation password.There are no certificates with the revocation password entered. The certificate revocation password you entered is invalid.
EnvironmentsStringCertificate EnvironmentsThere are no certificates with the environment (s) entered.
systemsStringCertificate SystemsThere are no certificates with the system (s) entered.
projectStringCertificate Design. Eg project 1There are no certificates with the project informed.
ip_externalStringexternal certificate IP.No certificates with external IP entered.
ip_hostnameStringIP or certificate hostnameThere are no certificates with the given IP or hostname.
self_signedIntInfo if the certificate is self-signedNo certificates exist for this self-signed value entered. The value for self-signed entered is invalid.
caIntCA code and CA name enteredThere are no certificates with the CA code you entered. The CA code you entered is invalid.
ResponsibleIntCode and name of responsible person informedThere are no certificates with the responsible’s code entered. The responsible’s code you entered is invalid.
DescriptionDescription of the certificate
publish_infoAdditional information for publication
deviceDevices 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
FieldTypeDescriptionRequired
code_certificateIntCode of a certificate to be publish.Yes
code_profile_publicationIntPublish profile code.A publication profile previously registered on senhasegura will be used.Yes
justificationStringJustification of publication up to 1024 characters.No
reasonIntPublication reason code.You must enter a code for a reason entered on senhasegura .Yes
itms_codeStringcharacters 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
devicesArrayArray 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:

FieldTypeSuccessError
status4xx
messageCreatedInvalid certificate code.
errorfalsetrue
code_publishingPosting scheduling code
reasonCode and name of reason for publicationReason code entered is invalid.
itms_codeStringITSM code enteredEnter the ITSM code. ITSM code does not exist on senhasegura integrated ITSM system. The code must be a maximum of 30 characters.
devicesArrayDevice 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
FieldTypeDescriptionRequired
code_publicationIntPublication code.No
code_certifiedIntCode of certificate to be published.No
code_profile_publicationIntPublish Profile Code.No
creation_dateStringDate of registrationNo
processedIntPublication processing status.The options will be:
1 = Yes
0 = NoNo
errorIntPublication Error Status.The options will be:
1 = Yes
0 = NoNo
reasonIntPublication reason code.No
itms_codeStringITSM code Text reported.No
deviceIntDevice code of the publication.No
offsetIntBase number of record count by pagination.No
limitIntNumber of records in pagination.No
Response to certificates

If the function succeeds or fails, the response consists of a certified block with the fields:

FieldTypeSuccessError
status4xx
messageCreatedInvalid certificate code.
errorfalsetrue
code_publishingPosting scheduling code
reasonCode and name of reason for publicationReason code entered is invalid.
itms_codeStringITSM code enteredEnter the ITSM code. ITSM code does not exist on senhasegura integrated ITSM system. The code must be a maximum of 30 characters.
code_credentialPublishing credential codeThe credential code you entered is invalid.
usernameUsername for credential search
quantity_devicesNumber 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
FieldTypeDescriptionRequired
code_profileIntCode of an already created profile.If the code is not passed, the system will interpret it as creating a profile.No
name_profileStringName of profile to create.Yes
siteStringSite where the certificate is to be installed.
If not entered, the certificate will be installed on the default Apache site.No
config_pathStringAddress of the configuration.Standard:
/etc/apache2/sites-available/default.com.confNo
portIntPort.
Default:443No
code_credentialIntCredential 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
usernameStringUsername that will be used to find credentials for the publication.
This information is required if you do not enter a code_credentialConditional
devicesArrayArray with the codes of the devices where the certificate is to be publishedYes
Response to certificates

If the function succeeds or fails, the response consists of a certified block with the fields:

FieldTypeSuccessError
status- Created
200 - Edit4xx
messageCreatedInvalid certificate code.
errorfalsetrue
code_pathStringProfile nameThe code of profile informed is invalid
name_profileStringProfile name
siteStringInformed Text
config_pathStringConfigured Path
portIntPort
code_credentialIntCredential code to publicationThe credential code informed is invalid
usernameStringUsername to search credentials
devicesArrayDevices’ 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
FieldTypeDescriptionRequired
code_profileIntCode of an already created profile.If the code is not passed, the system will interpret it as creating a profile.No
name_profileStringName of profile to create.Yes
siteStringSite where the certificate is to be installed.
If not entered, the certificate will be installed on the default IIS site.No
cert_storeStringIIS certificate management repository.Default: MYNo
portIntPort.
Default:443No
code_credentialIntCredential 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
usernameStringUsername that will be used to find credentials for the publication.
This information is required if you do not enter a code_credentialConditional
devicesArrayArray with the codes of the devices where the certificate is to be publishedYes
Response to certificates

If the function succeeds or fails, the response consists of a certified block with the fields:

FieldTypeSuccessError
status- Created
200 - Edit4xx
messageCreatedInvalid certificate code.
errorfalsetrue
code_pathStringProfile nameThe code of profile informed is invalid
name_profileStringProfile name
siteStringInformed Text
cert_storeStringIIS certificate management repository
portIntPort
code_credentialIntCredential code to publicationThe credential code informed is invalid
usernameStringUsername to search credentials
devicesArrayDevices’ 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
FieldTypeDescriptionRequired
code_profileIntCode of an already created profile.If the code is not passed, the system will interpret it as creating a profile.No
name_profileStringName of profile to create.Yes
name_partitionStringName of the partitionNo
name_certStringName of the certificate. If a certificate with the same name is already configured, on publication it will be replaced.No
profile_client_vipsArrayArray of SSL Client Profiles and their VIPsNo
profile_server_vipsArrayArray of SSL Server Profiles and their VIPsNo
code_credentialIntCredential 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
usernameStringUsername that will be used to find credentials for the publication.
This information is required if you do not enter a code_credentialConditional
devicesArrayArray with the codes of the devices where the certificate is to be publishedYes
Response to certificates

If the function succeeds or fails, the response consists of a certified block with the fields:

FieldTypeSuccessError
status- Created
200 - Edit4xx
messageCreatedInvalid certificate code
errorfalsetrue
code_profileIntPublish profile codeThe code of profile informed is invalid
name_profileStringProfile name
name_partitionStringName of the profile
name_certificateStringName of the certificate that is shown on the web application
profile_clientArrayComplete name of the profile
profile_serverArrayComplete name of the profile
code_credentialIntCredential code to publicationThe credential code informed is invalid
usernameStringUsername to search credentials
devicesArrayDevice’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
FieldTypeDescriptionRequired
code_profileIntCode of an already created profile. If the code is not passed, the system will interpret it as creating a profile.No
name_profileStringName of profile to create.Yes
key_db_pathStringPath of the Key database nameYes
key_db_passwordStringServer’s passwordYes
labelStringServer’s labelYes
code_credentialIntCredential 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
usernameStringUsername that will be used to find credentials for the publication.
This information is required if you do not enter a code_credentialConditional
devicesArrayArray with the codes of the devices where the certificate is to be publishedYes
Response to certificates
FieldTypeSuccessError
status- Created
200 - Edit4xx
messageCreatedInvalid certificate code.
errorfalsetrue
code_profileIntPublish profile codeThe code of profile informed is invalid
name_profileStringProfile name
key_db_pathStringPath of the Key database name
labelStringServer’s label
code_credentialIntCredential code to publicationThe credential code informed is invalid
usernameStringUsername to search credentials
devicesArrayDevices’ 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

FieldTypeDescription
nameStringApplication name
descriptionStringApplication description
tagsStringTags that identify the application
systemStringSecret system
environmentStringSecret environment
secret _idIntegerSecret ID
secret_nameStringSecret Name
identityStringSecret identifier
versionStringSecret version
expiration_dateDate/TimeSecret expiration date
engineStringSecret engine
dataStringSecret values
FieldTypeDescription
nomeStringApplication name.
descriçãoStringApplication description.
tagsStringApplication tags to be used as filters inside senhasegura .
sistemaStringSecret system.
ambienteStringSecret environment.
secret _idIntegerSecret ID.
secret_nameStringSecret name.
identificadorStringSecret identification. Free for use.
versãoStringSecret version number.
expiration_dateDate/TimeSecret expiration time.
motorStringSecret engine.
valoresStringSecret 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

FieldTypeDescriptionRequired
pod_nameStringName of the pod that will use the credentialYes
deployStringName of the deploy that will use the credentialYes
namespaceStringNamespace of the container that will use the credentialYes

Response

FieldTypeDescription
nameStringApplication name
descriptionStringApplication description
tagsStringTags that identify the application
systemStringSecret system
environmentStringSecret environment
secret_idIntegerSecret ID
secret_nameStringSecret Name
identityStringSecret identifier
versionStringSecret version
expiration_dateDate/TimeSecret expiration date
engineStringSecret engine
dataStringSecret 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

FieldTypeDescriptionRequired
pod_nameStringName of the pod that will use the credentialYes
deployStringName of the deploy that will use the credentialYes
namespaceStringNamespace of the container that will use the credentialYes
secret_idIntegerSecret IDYes

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.