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 log¹ 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 5849².

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 6749³ 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:

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

info

To update a record you must use this same resource. The device will be queried by the hostname. That is, if you find a device, the registry will be updated. If it does not, then the registry will be created.

Expected response

HTTP/1.1 200 OK 

{
    "response": {
        "status": 201,
        "mensagem": "Device successfully registered!",
        "erro": false,
        "message": "Device successfully registered!",
        "error": false
    },
    "device": {
        "id": "9",
        "hostname": "mydevice02",
        "ip": "22.13.50.71",
        "site": "AWS"
    }
}

Expected response when registering without providing some required data

HTTP/1.1 400 Bad Request 

{
      "response": {
          "status": 400,
          "mensagem": "1004: The device's hostname was not informed",
          "erro": true,
          "message": "1004: The device's hostname was not informed",
          "error": true
      },
      "exception": {
          "code": 1004,
          "message": "1004: The device's hostname was not informed",
          "detail": null
      }
  }

Credentials

Query credential list

GET /iso/pam/credential 

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

Expected response

HTTP/1.1 200 OK 

{
    "response": {
        "status": 200,
        "mensagem": "2 credentials found",
        "erro": false,
        "message": "2 credentials found",
        "error": false
    },
    "credentials": [
        {
            "id": "1",
            "identifier": "fakeuser01ws",
            "username": "fakeuser01",
            "expiration": null,
            "change": "2020-11-17 16:14:35",
            "view": null,
            "hostname": "fakedevice01",
            "management_ip": "172.10.20.30",
            "type": "Local User",
            "type_code": "1",
            "device_model": "Fake Product",
            "device_type": "Server",
            "device_vendor": "Fake Vendor",
            "automatic_change": "0",
            "connectivity": "",
            "connectivity_code": ""
        },
        {
            "id": "2",
            "identifier": "fakeuser02ws",
            "username": "fakeuser02",
            "expiration": null,
            "change": "2020-11-17 16:14:35",
            "view": null,
            "hostname": "fakedevice01",
            "management_ip": "172.10.20.30",
            "type": "Local User",
            "type_code": "1",
            "device_model": "Fake Product",
            "device_type": "Server",
            "device_vendor": "Fake Vendor",
            "automatic_change": "0",
            "connectivity": "",
            "connectivity_code": ""
        }
    ]
}

Query a single credential

GET /iso/pam/credential/* 

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

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

Expected response

HTTP/1.1 200 OK 

{
    "response": {
        "status": 200,
        "mensagem": "Credential 5",
        "erro": false,
        "message": "Credential 5",
        "error": false
    },
    "credential": {
        "id": "5",
        "tag": "robot-test-5",
        "username": "credential_5",
        "password": "secret@2504",
        "content": "secret@2504",
        "hostname": "destktop-91.com",
        "parent_credential_cod": null,
        "parent_credential": null,
        "additional": "CREDADD01",
        "domain": "",
        "ip": "172.10.10.90",
        "port": "22",
        "model": "Ubuntu",
        "expiration_time": "2021-01-16T17:31:39"
    }
}

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

HTTP/1.1 400 Bad Request 

{
    "response": {
        "status": 400,
        "mensagem": "1007: Credential not found",
        "erro": true,
        "message": "1007: Credential not found",
        "error": true
    },
    "exception": {
        "code": 1007,
        "message": "1007: Credential not found",
        "detail": null
    }
}

Inativating a credential

DELETE /iso/pam/credential/* 

You can also inativating a credential using WebService A2A methods.

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

Expected response

HTTP/1.1 200 OK 

{
    'response': {
        'status': 200,
        'mensagem': 'Credential successfully deactivated',
        'erro': False,
        'message': 'Credential successfully deactivated',
        'error': False
    }
}

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

HTTP/1.1 400 Bad Request 

{
    'response': {
        'status': 400,
        'mensagem': '1007: Credential not found',
        'erro': True,
        'message': '1007: Credential not found',
        'error': True
    },
    'exception': {
        'code': 1007,
        'message': '1007: Credential not found',
        'detail': None
    }
}

Updating a credential

POST /iso/pam/credential 

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

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

info

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

Expected response

HTTP/1.1 200 OK 

{
    "response": {
        "status": 201,
        "mensagem": "Credential updated successfully!",
        "erro": false,
        "message": "Credential updated successfully!",
        "error": false
    },
    "credential": {
        "id": "5",
        "tag": "robot-test-5"
    }
}

Expected response when one of the required data is not provided

HTTP/1.1 400 Bad Request 

info

The following error codes may occur if the required data is not provided:

• 1004: The device's hostname was not informed

• 1005: The device's IP was not informed

• 1007: Credential not found

{
    "response": {
        "status": 400,
        "mensagem": "1004: The device's hostname was not informed",
        "erro": true,
        "message": "1004: The device's hostname was not informed",
        "error": true
    },
    "exception": {
        "code": 1004,
        "message": "1004: The device's hostname was not informed",
        "detail": null
    }
}

Release the custody of a credential

DELETE /iso/pam/credential/custody/* 

When a password request is performed via API, the credential remains in custody of the applicant. To release the custody it is necessary to use this method.

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

Expected response

HTTP/1.1 200 OK 

{
    "response": {
        "status": 200,
        "mensagem": "Credential custody 1 released",
        "erro": false,
        "message": "Credential custody 1 released",
        "error": false
    }
}

In the example above the number "1" is the ID of the credential

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

HTTP/1.1 400 Bad Request 

{
    "response": {
        "status": 400,
        "mensagem": "1007: Credential not found",
        "erro": true,
        "message": "1007: Credential not found",
        "error": true
    },
    "exception": {
        "code": 1007,
        "message": "1007: Credential not found",
        "detail": null
    }
}

Protected Information

Query a single protected information

GET /iso/pam/info/* 

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

Expected response

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

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:

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

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

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>");
        }
    }
}

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.

---

1. Orbit ➔ Logs ➔ API↩

2. https://tools.ietf.org/html/rfc5849

   ↩

3. https://tools.ietf.org/html/rfc6749#section-2.3

   ↩