A2A

Integração

Integração via Webservice

A API de integração do senhasegura permite outras aplicações a criar, consultar, modificar e inativar credenciais, chaves, usuários e suas permissões e outras informações protegidas via webservices. O webservices segue uma arquitetura REST e utiliza autenticação pelo método OAuth v2.0.

Cada requisição ao serviço é registrada com a data, tempo, IP de origem, e identificação de qual aplicação cliente API. Dados sensíveis como senhas e chaves, serão removidas desta mensagem de log¹.

Cada acesso proveniente de aplicação cliente é controlada, em adição ao método de autenticação OAuth v1.0, pelo IP do requisitante.

Cada cliente tem acesso apenas as credenciais registradas por ele próprio ou direcionada através de configuração na aplicação.

Senhas podem ser Credenciais para acesso a Dispositivos como servidores e roteadores, tanto quanto chaves RSA utilizadas para acesso SSH. Senhas são automaticamente alteradas pela aplicação conforme as políticas configuradas.

Informação protegida é um tipo de informação que não é alterada pelo senhasegura . Pode ser utilizado para armazenar informações sensíveis como as chaves de certificados SSH ou chaves de API.

Uso de requisições padrão

Cada requisição no WebService A2A deve ter o OAuth Consumer Key e o OAuth Token do cliente. Desta forma, cada URI de requisição apresenta-se aproximadamente como seguinte exemplo:

https://senhasegura/iso/*MODULO*/*FUNCAO* 

• MODULO: Módulo senhasegura WebService A2A

• FUNCAO: Função do módulo

A partir deste ponto, você deve entender qual método de autenticação irá usar.

Sem autenticação OAuth

caution

Este método não é recomendado pelo senhasegura . Evite-o se o OAuth v2.0 puder ser usado.

Cada solicitação no WebService A2A deve ter o cliente OAuth Consumer Key e o cliente OAuth Token. Por esta via, cada pedido URI se parece com o seguinte exemplo.

https://senhasegura/iso/*MODULO*/*FUNCAO*?oauth_consumer_key=*KEY*& oauth_token=*TOKEN* 

• MODULO: Módulo senhasegura WebService A2A

• FUNCAO: Função do módulo

• KEY: OAuth Key do cliente

• TOKEN: OAuth Token do cliente

caution

Quando utilizado o método GET, não esqueça de adicionar oauth_consumer_key e oauth_token antes dos demais argumentos. Quando utilizado o método POST, ambos parâmetros deve estar preenchidos na URL como se faz nos métodos GET.

Usando autenticação OAuth v1.0

caution

Este método não é recomendado pelo senhasegura . Evite-o se o OAuth v2.0 puder ser usado.

Usando OAuth v1.0, certifique-se de que oauth_signature_method usado é HMAC-SHA1 e oauth_version está definido para 1.0.

oauth_timestamp, oauth_nonce e oauth_signature são obrigatórios.

Você pode encontrar a especificação completa sobre o OAuth v1.0 no RFC 5849²

Usando autenticação OAuth v2.0

Usando OAuth v2.0, o seu pedido deve renovar o token de autorização quando este expirar. Por padrão, o senhasegura criará este token válido por um dia.

Usando a Client Key e Client Secret registrados e aprovados, solicite um novo token para o WebService A2A usando o seguinte URI:

[POST https://senhasegura/iso/oauth2/token](POST https://senhasegura/iso/oauth2/token){.uri}

Esta solicitação deve ter o cabeçalho Autorização Básica. Veja a seção "Autenticação de Cliente" no RFC 6749³ para entender melhor.

A sua aplicação receberá um dicionário JSON semelhante ao exemplo a seguir:

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "
    eyJ0eXAiOiJKV1QiL0IjoxNTgwNDM2NTk4LCJuYmYiOjE1ODA0MzY1OTgsImV4cCI
    6MTU4MDQ0MDE5OCwic3ViIjoiTVRNeE1qQWtTRGRPUVRWV1ozcEVSI6Ijg0OWYwZm
    VhNDI0ZDc5NWUwYTg2MjVlMTdiZWE2YTAyNTQyMzAxNjQzYmRmYTc5ZjYzZDNhM2U
    3ZmI5ZjQzbGCJhjg0OWYwZmVhNDI0ZDc5NWUwYTg2MjVlMTdiZWE2YTAyNTQyMzAx
    NjQzYmRmYTc5ZjYzZDNhM2U3ZmI5ZjQzYmM2MjRhYzg5YmVhMzFhOGQwIiwiaWFci
    OiJSUzI1NiIsImp0ahYzg5YmVhMzFhOGQwIn0.eyJhdWQiOiIzY2E4YTk4ZDkwNzU
    0MzgxMjMzNGY3ZjVkYmFmY2E2NTA1ZTMzMTlmYiIsImp0aSI6IYmM2MjRTRzB6ZFZ
    ONlZXVXhhVWN2Y1RKdFRXNTVhM05sZGtOd1JHeHllbXR5VEV3eE5EMD0iLCJzY29w
    ZXMiOltdfQ.efqHZdlij6sQcj_l9RbNNKxDbf81CbIoTFwdIkooT5bK14N5iUazrT
    8jpB_JsgQdQ8RyD5xF_ReKSj4Al7hp1uRXIiuErlKv1FpxY9oNC44kldlumjyevu8
    7GJ0qzem0RYNc3930UbT-XEYqnQijg0se8_GdzdLkxyMn0kxApkAkv-to9EUdbbrv
    vno_pmqiZGyamw6J2BL1aCqwne3S8CCG34TXRyJyqkGrPrDO-NPi2fj25PRbX8Ci1
    iIqXdYvEkefg-g-i0A_Hp9E3s585c5wqxreSBAIwiaGtnTkxw0D14JPzqWf48hbvV
    RPGMj_-KXJTnu-zXkkEPNYs8oWpA"
}

Reserve o access_token. Ele deve ser usado em cada próxima chamada de método. Preencha o cabeçalho da solicitação Autorização com o token_type e os valores access_token. Você pode verificar a RFC 6749 "Tipos de Token de Acesso" para mais detalhes.

Provisionando uma nova aplicação

Para o acesso a credenciais por parte de aplicações, de forma separada, dos usuários comuns, o senhasegura possui a funcionalidade A2A onde cada aplicação terá seu próprio grupo de acesso. Também implementando o princípio do privilégio único onde um aplicativo não terá acesso às mesmas informações que outro aplicativo.

info

É possível vincular dispositivos e/ou informações protegidas a uma autorização WebService A2A .

Para realizar um provisionamento siga as instruções:

1. Acesse o menu A2A ➔ Aplicações e clique no botão de ação do relatório, escolha a opção Novo

2. No formulário insira o nome da aplicação que será provisionada e o tipo de assinatura que usará no campo *Utilizar assinatura OAuth**

3. Indique se esta aplicação estará Ativa para uso

4. Se desejar insira Tags de identificação e uma Descrição sobre a aplicação.

5. Clique em Salvar

Formulário de Aplicação

Com a configuração realizada aguarde a tela ser atualizada ou use o botão de atualização localizado na barra superior do relatório. Quando a aplicação criada estiver disponível no relatório clique no botão de ação respectivo e escolha a opção Autorizações. Neste formulário você irá definir quais credenciais a aplicação criada terá permissão de acesso, preencha as informações

1. Selecione o Sistema e o Ambiente que a aplicação acessará

2. Em seguida indique as credenciais que a aplicação terá acesso no campo Credencial de acesso e clique no botão Adicionar, realize esse processo para todas as credenciais que desejar incluir. Você também pode selecionar a caixa Cadastrar uma nova credencial no cofre para indicar uma credencial que ainda não esteja cadastrada no senhasegura , mas para isso será necessário selecionar o dispositivo, que já deve estar cadastrado no sistema, em que esta credencial concede acesso, em seguida indique o username e senha da credencial. Clique no botão Adicionar, realize esse processo para todas as credenciais que desejar incluir. As credenciais e os respectivos dispositivos, que a aplicação terá acesso serão listados na tabela abaixo.

3. Siga para a aba Segurança

4. Indique quais recursos a aplicação terá acesso:

   • PAM: Provisionamento e consulta de credenciais, chaves SSH e demais informações protegidas do módulo PAM.

   • Certificados: Requisições, consulta, assinatura e demais atividades do módulo Certificate Manager

   • Task Manager: Criação e alteração de atividades do módulo Task Manager

   • Dashboards: Conhecimento e consumo dos dados impressos nos dashboards.

   • A2A: Consulta e cadastro de aplicações A2A.

5. Determine o tipo de nível de interação das aplicações clientes com os módulos do senhasegura no campo Permissão do recurso PAM.

   caution

   Esse campo é apenas obrigatório caso você tenha selecionado o módulo PAM no campo Recursos customizados

   É importante lembrar que se a configuração concede permissão apenas de leitura os usuário não poderão tentar realizar uma alteração, caso isso ocorra o seguinte erro será exibido:

   {
       "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. No campo *Ativar a criptografia de informações sensíveis?** indique se uma criptografia adicional será utilizada para o acesso da aplicação.

7. Em seguida no campo IPs Permitidos você poderá indicar partindo de quais IP's a aplicação poderá realizar o acesso. Para isso clique no botão com ícone de adição e insira os endereços. Utilize o caractere curinga "*" para cadastrar seguimentos de rede.

8. No campo Referers permitidos você poderá determinar que apenas os refereres com o conteúdo indicado será permitido. Para isso clique no botão com ícone de adição e insira os conteúdos permitidos.

9. No campo Validação de certificados será possível vincular um fingerprint de certificado SSL a autorização.

   Se estiver vinculado, o senhasegura irá validar a CA do certificado SSL do cliente a cada processo de autenticação com certificados.

   caution

   O uso do certificado não substitui a validação dos outros métodos, o certificado será usado em conjunto com o OAuth 1 ou 2.

   Desta forma além da autenticação com OAuth o usuário tem que enviar o certificado e a chave como no exemplo:

   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. Para finalizar clique em Salvar.

Formulário de Autorização da aplicação

De volta ao relatório clique novamente no botão de ação da aplicação e escolha a opção Autorizações. A autorização recém criada será exibida, clique em seu botão de ação respectivo e escolha a opção Visualizar. Uma tela com o ID do Cliente e Client Secret será exibida, para visualizar cada uma das informacões clique no ícone como na imagem integracao-0005-ptbr.

Visualização de autorizações da aplicação

Autorizações por aplicação

Para poder ver uma lista completa com todas as autorizações por aplicação, acesse o menu A2A ➔ Autorizações por aplicação. Nesta tela, além de poder visualizar os detalhes de cada autorização por aplicação, também é possível editar uma autorização já existente e criar uma nova.

caution

A tela só irá mostrar as autorizações de aplicações que já foram criadas e salvas com sucesso.

info

Recomendamos o uso desta tela para facilitar a visualização de todas as autorizações por aplicação em um só lugar, evitando a necessidade de ter que entrar em cada aplicação separadamente para que assim seja possível visualizar respectivas autorizações.

Métodos PAM

O senhasegura WebService A2A possui métodos de consulta, criação e alteração de informações armazenadas na aplicação como: adicionar, alterar e inativar dispositivos e credenciais, além de outros.

caution

Para utilizar esses métodos o recurso PAM deve ser selecionado na autorização da aplicação.

Dispositivos

Consultar a lista de dispositivos

GET /iso/pam/device 

Resposta esperada

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

Consultar um único dispositivo

Você também pode consultar um único dispositivo usando os métodos WebService A2A .

Você deve substituir o wildchar * pelo número de identificação do dispositivo ou identificador de webservice desejado.

GET /iso/pam/device/* 

Resposta esperada

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

Resposta esperada quando o dispositivo não é encontrado

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

Inativar um dispositivo

Você também pode inativar um dispositivo usando os métodos WebService A2A . Quando um dispositivo é inativo, todas as suas credenciais serão desativadas no senhasegura automaticamente também.

Você deve substituir o wildchar * pelo número de identificação do dispositivo ou identificador desejado.

DELETE iso/pam/device/* 

Resposta esperada

HTTP/1.1 200 OK 

{
    "response": {
        "status": 200,
        "mensagem": "Device successfully deactivated",
        "erro": false,
        "message": "Device successfully deactivated",
        "error": false
    }
}

Resposta esperada ao inativar um dispositivo que não existe

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

Criação e Atualização de um dispositivo

POST /iso/pam/device 

A tabela a seguir é um exemplo dos parâmetros de entrada necessários:

Campo	Tipo	Exemplo	Obrig.	Obs.
hostname	String	mydevice02	Sim
ip	String	22.13.50.71	Sim
site	String	AWS	Sim
model	String	CentOS 7	Sim
vendor	String	CentOS	Sim
type	String	Server	Sim	Deve ser um tipo já cadastrado.

info

Para atualizar um registro você deve utilizar este mesmo método. A consulta do registro será feita pelo nome da hostname. Ou seja, se você encontrar um dispositivo, o registro será atualizado. Se não encontrar, então o registro será criado.

Resposta esperada

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

Resposta esperada ao registrar um dispositivo sem fornecer alguns dados necessários

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

Credenciais

Consultar lista de credenciais

GET /iso/pam/credential 

Este método retorna a lista de credenciais às quais o cliente A2A pode ter acesso.

Resposta esperada

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

Consultar uma única credencial

GET /iso/pam/credential/* 

Você também pode consultar uma única credencial usando os métodos WebService A2A .

Você deve substituir o wildchar * pelo número Credential ID ou ID Identificator desejado.

Resposta esperada

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

Resposta esperada quando uma credencial não existe ou não é permitido o acesso

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

Inativar uma credencial

DELETE /iso/pam/credential/* 

Você também pode inativar uma credencial usando os métodos WebService A2A .

Você deve substituir o wildchar * pelo número da Credencial ou ID identificador desejado.

Resposta esperada

HTTP/1.1 200 OK 

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

Resposta esperada quando não é permitido ao cliente A2A o acesso à credencial, ou quando a credencial já está inativa

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

Atualizar uma credencial

POST /iso/pam/credential 

Este método só permite atualizar uma credencial que já existe no senhasegura e à qual o cliente A2A já tem acesso. A tabela a seguir é um exemplo dos parâmetros de entrada necessários:

Campo	Tipo	Exemplo	Obrig.	Obs.
hostname	String	mydevice02	Sim
ip	String	22.13.50.71	Sim
identifier	String	5	Sim
username	String	credential05	Sim

info

Para atualizar um registro você deve usar este mesmo método. Se o ID numérico (ID credencial) não for fornecido, a credencial será alterada por IP, Hostname e Username. Ou seja, se você encontrar um dispositivo, o registro será atualizado. Se não encontrar, então o registro será criado.

Resposta esperada

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

Resposta esperada quando um dos dados necessários não é fornecido

HTTP/1.1 400 Bad Request 

info

Os seguintes códigos de erro podem ocorrer se os dados necessários não forem fornecidos:

• 1004: O hostname do dispositivo não foi informado

• 1005: O IP do dispositivo não foi informado

• 1007: Credencial não encontrado

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

Liberar a custódia de uma credencial

DELETE /iso/pam/credential/custody/* 

Quando um saque de senha é realizado via API, a credencial permanece sob custódia do solicitante. Para liberar a custódia, é necessário utilizar este método.

Você deve substituir o wildchar * pelo número da Credential ou ID identificador desejado.

Resposta esperada

HTTP/1.1 200 OK 

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

No exemplo acima, o número "1" é a identificação da credencial

Resposta esperada quando você não tem acesso à credencial ou a credencial não existe

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

Informações Protegidas

Consultar uma única informação protegida

GET /iso/pam/info/* 

Este método só permite que você consulte uma única informação protegida. Você deve substituir o wildchar * pelo número de identificação da Informação Protegida ou identificado desejado.

Resposta esperada

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

Resposta esperada quando você não tem acesso à informação ou ela não existe

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

Resposta esperada quando você tem acesso à informação, mas ela está inativa

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

Inativar uma informação protegida

DELETE /iso/pam/info/* 

Você também pode inativar uma informação protegida usando os métodos WebService A2A .

Você deve substituir o wildchar * pelo número de identificação da Informação Protegida ou identificador desejado.

Resposta esperada

HTTP/1.1 200 OK 

{
    "response": {
        "status": 200,
        "mensagem": "Information successfully deactivated",
        "erro": false,
        "message": "Information successfully deactivated",
        "error": false
    }
}

Resposta esperada quando você não tem acesso à informação ou ela não existe

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

Resposta esperada quando a informação já está inativa

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

Criação de informações protegidas

Nova informação protegida

POST /iso/pam/info 

Permite registrar uma nova informação protegida.

Campo	Tipo	Exemplo	Obrig.	Obs.
content	String	Meu conteúdo secreto	Sim	Conteúdo em texto a ser protegido. Não é possível realizar upload de arquivos.

Resposta esperada

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

Alterar uma informação protegida

Campo	Tipo	Exemplo	Obrig.	Obs.
content	String	Meu conteúdo secreto	Sim	Conteúdo em texto a ser protegido. Não é possível realizar upload de arquivos.
identifier	String	INFO1298	Não	Identificador único da informação utilizada para identificação posterior.
name	String	Minha informação	Não	Nome da informação que será apresentada nas telas do senhasegura .
type	String	Access credential	Não	Tipo de informação. Deve ser um tipo já cadastrado

Resposta esperada

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

Resposta esperada quando o conteúdo da informação não é fornecido

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 de sessões

Criação de URL autenticada para sessão web

POST /iso/remote/session 

Este método permite criar uma URL autenticada para incio de sessão web em dispositivos previamente cadastrados na solução através do senhasegura Web Proxy.

A tabela a seguir contém exemplos dos parâmetros de entrada:

Campo	Tipo	Exemplo	Obrig.	Obs.
user	String	senhasegura-user	Yes	Usuário para autenticação no senhasegura . Ela deve existir na solução.
credential	String	admin	Yes	Usuário da credencial que será utilizada na sessão.
device	String	172.12.32.14	Yes	Hostname ou IP do dispositivo relacionado a credencial da sessão.
protocol	String	SSH	Yes	Protocolo de conexão no dispositivo. (SSH, RDP, HTTPS.).
remotedevice	String	123	No	Código, IP ou Hostname do dispositivo, caso esteja utilizando credencial de domínio e queira realizar a sessão em dispositivo diferente do relacionado a credencial.
remoteAddr	string	201.13.25.61	No	IP de conexão do usuário que irá utilizar a URL de sessão. Só será possível iniciar a sessão a partir deste endereço de IP.
port	Int	22	No	Porta da conexão no dispositivo. Quando não informado, é utilizada a porta padrão do protocolo.
remoteapp	Int	123	No	Código do RemoteApp. Utilizado para sessões com RemoteApp.

Resposta esperada

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

A URL de sessão é valida por 30 segundos. Após esse período será necessário o provisionamento de uma nova.

Resposta esperada quando o conteúdo da informação não é fornecido

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

Encerramento compulsório de sessão proxy

DELETE /iso/remoto/sessao/\[identificador\] 

Encerra a sessão proxy indicando o motivo do encerramento. Utilize essa funcionalidade para que sistemas externos como SIEM possam encerrar sessões baseadas nos alertas emitidos pelo próprio senhasegura .

Resposta

{
    "response": {
        "status": 200,
        "mensagem": "Sessao encerrada",
        "erro": false
    }
}

Métodos Dashboard

O senhasegura WebService A2A possui métodos de consulta das informações copiladas pelo módulo Dashboard.

caution

Para utilizar esses métodos o recurso Dashboards deve ser selecionado na autorização da aplicação.

Dashboard de sessões proxy

GET /iso/coge/sessoes/* 

Este método irá retornar a quantidade de sessões proxy que ocorreram e que ainda estão em execução. Junto da path da URI, deve ser informado qual protocolo desejado. Os demais parâmetros devem ser fornecidos como query da URI.

Protocolos suportados:

• jumpserver: Apenas sessões proxy que ocorreram através do senhasegura Terminal Proxy

• rdpgate: Apenas sessões proxy que ocorreram através do senhasegura RDP Proxy

• ssh: Apenas sessões proxy de protocolo SSH independente de qual tecnologia proxy foi utilizada

• rdp: Apenas sessões proxy de protocolo RDP independente de qual tecnologia proxy foi utilizada

• rdpweb: Apenas sessões proxy de protocolo RDP que ocorreram através do senhasegura Web Proxy

• sshweb: Apenas sessões proxy de protocolo SSH que ocorreram através do senhasegura Web Proxy

• all: Todas sessões executadas

Cada protocolo irá retornar um dicionário contendo diferentes nós representando a tecnologia proxy utilizada. Como filtros adicionais, os seguintes parâmetros podem ser fornecidos:

Campo	Tipo	Exemplo	Obrig.	Obs.
ativo	Integer	1	Não	Forneça 1 para indicar que apenas sessões ativas deva ser retornado.
data1	String	2020-01-30	Não	Data de início do período de consulta. Formato YYYY-MM-DD (ISO 8601).
data2	String	2020-03-30	Não	Data de término do período de consulta. Formato YYYY-MM-DD (ISO 8601).
hostname	String	mysrv	Não	Hostname do dispositivo a ser consultado. Deve ser igual ao hostname cadastrado no senhasegura .
userCredencial	String	mycredusr	Não	Username da credencial utilizada a ser consultada..
username	String	myssusr	Não	Username do usuário senhasegura que realizou a sessão

Veja os exemplos a seguir para diferentes consultas.

Consultar todas as sessões

GET iso/coge/sessoes/all 

Resposta esperada

HTTP/1.1 200 OK 

{
    "response": {
        "status": 200,
        "mensagem": "Sessoes",
        "erro": false,
        "message": "Sessoes",
        "error": false
    },
    "sessoes": {
        "historico": {
            "SQL": 4,
            "RDP_Web": "3",
            "RDP_Gate": "1",
            "SSH/Telnet": 4,
            "Jump_Server": 2,
            "HTTP_VNC": "2"
        },
        "ativas": {
            "RDP_Gate": "2",
            "Jump_Server": 1
        }
    }
}

Resposta para consulta de sessões com valores inválidos

Se utilizarmos os argumentos de consulta com dados inválidos, nenhum dado deve ser retornado.

{
    "response": {
        "status": 200,
        "mensagem": "Sessoes",
        "erro": false,
        "message": "Sessoes",
        "error": false
    },
    "sessoes": {
        "ativas": [],
        "historico": []
    }
}

Resposta para consultar sessões SSH

Neste exemplo apenas sessões de protocolo SSH que ocorreram, ou que tenham iniciado dentro do período fornecido, serão retornadas.

{
    "response": {
        "status": 200,
        "mensagem": "Sessoes",
        "erro": false,
        "message": "Sessoes",
        "error": false
    },
    "sessoes": {
        "historico": {
            "SSH/Telnet": "2",
            "Jump_Server": "1"
        },
        "ativas": {
            "Jump_Server": 1
        }
    }
}

Dashboard de ameaças

GET /iso/coge/risco/* 

Este método irá retornar as sessões proxy e custódias de senha que sejam suspeitas. Junto da path da URI, deve ser informado qual tipo de operação desejado. Os demais parâmetros devem ser fornecidos como query da URI.

Modos de consulta

• all: Retorna tanto a lista de consultas suspeitas quanto acessos suspeitos

• consultas: Retorna apenas a lista de consultas suspeitas

• acessos: Retorna apenas a lista de acessos suspeitos

Como filtros adicionais, os seguintes parâmetros podem ser fornecidos:

• data1: Data de início do período de consulta. Formato YYYY-MM-DD (ISO 8601)

• data2: Data de término do período de consulta. Formato YYYY-MM-DD (ISO 8601)

• hostname: Hostname do dispositivo a ser consultado. Deve ser igual ao hostname cadastrado no senhasegura .

• userCredencial: Username da credencial utilizada a ser consultada.

• username: Username do usuário senhasegura que realizou a sessão

• protocolo: Utilize se desejar filtrar por um protocolo específico

  • rdp: Sessões proxy RDP via senhasegura Web Proxy e senhasegura RDP Proxy

  • rdpweb: Sessões proxy RDP via senhasegura Web Proxy

  • ssh: Sessões SSH provenientes do senhasegura Terminal Proxy ou senhasegura Web Proxy

  • sshweb: Sessões SSH provenientes do senhasegura Web Proxy

  • telnet: Sessões Telnet provenientes do senhasegura Terminal Proxy ou senhasegura Web Proxy

  • vnchttp: Sessões a websites via senhasegura Web Proxy

  • rdpgate: Sessões proxy RDP via senhasegura RDP Proxy

  • jumpserver: Sessões SSH provenientes do senhasegura Terminal Proxy

  • sql: Sessões a banco de dados via senhasegura Web Proxy

  • all: Todas opções de proxy

Veja os exemplos a seguir para diferentes consultas.

Consultar todas as ameaças

GET /iso/coge/risco/all 

Resposta esperada

HTTP/1.1 200 OK 

{
    "response": {
        "status": 200,
        "mensagem": "Sessoes",
        "erro": false,
        "message": "Sessoes",
        "error": false
    },
    "sessoes": {
        "historico": {
            "SSH/Telnet": "2",
            "Jump_Server": "1"
        },
        "ativas": {
            "Jump_Server": 1
        }
    }
}

Resposta esperada quando a consulta é feita com datas invertidas

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

Resposta esperada quando a consulta é feita fornecendo credencial e omitindo 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
    }
}

Resposta esperada quando a consulta é feita fornecendo hostname e omitindo credencial

GET /iso/coge/risco/all?hostname=HOSTNAMEIROHP 

{
    "response": {
        "status": 400,
        "mensagem": "userCredencial parameter is missing",
        "erro": false,
        "message": "userCredencial parameter is missing",
        "error": false
    }
}

Resposta esperada quando a consulta é feita fornecendo um protocolo inválido

GET /iso/coge/risco/all?protocolo=PROTOCOLOO4TZ5 

{
    "response": {
        "status": 400,
        "mensagem": "Invalid protocol",
        "erro": false,
        "message": "Invalid protocol",
        "error": false
    }
}

Consultar todas as consultas suspeitas por credenciais

GET /iso/coge/risco/consultas 

Resposta esperada

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

            ...
        ]
    }
}

Consultar todos os acessos suspeitos

GET /iso/coge/risco/acessos 

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

            ...
        ]
    }
}

Dashboard de credenciais

GET /iso/coge/credenciais/* 

Este método retorna o status das credenciais geridas pelo senhasegura . Para realizar a consulta é necessário fornecer o estado desejado:

• all: Todos estados

• expiradas: Apenas contagem de expiradas. Quantidade de credenciais que tem configuração de troca de senha automática e que já expiraram o prazo para executar a troca.

• utilizacao: Apenas contagem de credenciais em utilização. Quantidade de credenciais em custódia no momento.

Consultar todas as credenciais

GET /iso/coge/credenciais/all 

Resposta esperada

HTTP/1.1 200 OK 

{
    "response": {
        "status": 200,
        "mensagem": "Credenciais",
        "erro": false,
        "message": "Credenciais",
        "error": false
    },
    "credenciais": {
        "expiradas": "1",
        "utilizacao": "3"
    }
}

Consultar credenciais expiradas

GET /iso/coge/credenciais/expiradas 

Resposta esperada

HTTP/1.1 200 OK 

{
    "response": {
        "status": 200,
        "mensagem": "Credenciais",
        "erro": false,
        "message": "Credenciais",
        "error": false
    },
    "credenciais": {
        "expiradas": "1"
    }
}

Consultar credenciais em utilização

GET /iso/coge/credenciais/utilizacao 

Resposta esperada

HTTP/1.1 200 OK 

{
    "response": {
        "status": 400,
        "mensagem": "Invalid request",
        "erro": false,
        "message": "Invalid request",
        "error": false
    }
}

Resposta esperado quando é fornecido um estado inválido

GET /iso/coge/credenciais/invalido 

{
    "response": {
        "status": 400,
        "mensagem": "Invalid request",
        "erro": false,
        "message": "Invalid request",
        "error": false
    }
}

Resposta esperado quando não é fornecido um estado

GET /iso/coge/credenciais/ 

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

Métodos Task Manager

caution

Para utilizar esses métodos o recurso Task Manager deve ser selecionado na autorização da aplicação.

Criação ou Alteração de Task Privilegiada

POST /iso/tkmn/task/\[identifier\] 

Crie ou altere um task privilegiada

Parametros

Campo	Tipo	Exemplo	Obrig.	Obs.
name	String	Automation01	Sim	Nome de identificação da task.
environment	String	Production	Sim	Ambiente da task.
system	String	SystemT91	Sim	Sistema da task.
template	Integer		Sim	Id do template a ser utilizado.
tags	String	T91,AUTO	Não	Tags da task separadas por vírgula.
variables	JSON		Não	Variáveis da task. Identificador + Valor.
credential	Integer		Não	Credencial utilizada para conexão.
devices	String		Não	Dispositivos separados por vírgula.
schedules	JSON		Não	Horários das tasks. Para montar o JSON.

Certificate Management - Integração

caution

Para utilizar esses métodos o recurso Certificados deve ser selecionado na autorização da aplicação.

Introdução

O senhasegura Certificate Management fornece gerenciamento centralizado do ciclo de vida do certificado digital dentro da organização, desde o Discovery através da verificação automática de sites, diretórios e servidores da web, até a renovação automática do Certificado por meio de Autoridades Certificadoras externa ou interna .

O objetivo desse documento é prover um guia para usuários utilizando o Certificate Management como administradores, e explicar sobre detalhes de uso, benefícios e procedimentos.

Como o Certificate Management funciona

O senhasegura Certificate Management gerencia todo o ciclo de vida dos certificados digitais, trabalhando com certificados através de geração por requisições, importação manual de certificados existentes, ou Discovery de certificados em dispositivos, domínios ou containers. Além de monitorar a validade dos certificados e possibilitar a renovação de maneira facilitada, o Certificate Management permite também a visualização de logs e relatórios sobre todas as operações realizadas através da solução.

Definições

O senhasegura utiliza uma terminologia específica para suas funções e funcionalidades. Assim, alguns termos devem ser compreendidos antes de iniciar o uso da solução:

• Usuário: Funcionários próprios, estagiários ou terceiros que usam ou podem precisar de acesso aos sistemas da empresa;

• Certificado Digital: Certificados digitais são arquivos que contêm informações, além de chaves, públicas e privadas, usadas para comunicação segura pela Internet. Na presente versão deste manual o senhasegura realiza o gerenciamento de certificados digitais utilizados em webservices.

• Autoridade Certificadora (CA): É uma empresa ou organização que valida a identidade de pessoas, empresas, endereços de e-mail, websites e emite os certificados digitais relacionados a essas identidades para garantir a autenticidade e integridade das comunicações.

Atividades

Nesta seção, serão abordadas as seguintes funções do senhasegura : realizar requisições, receber respostas e métodos do senhasegura Certificate Management.

Métodos

O webservice de integração senhasegura possui alguns métodos para realizar operações na aplicação.

Criar/Modificar Request

POST https://url_do_cofre/iso/certificado/request/\[codigo_request\] 

O método Criar/Modificar Request cria ou modifica um request de certificado no senhasegura .

Parâmetros

Campo	Tipo	Descrição	Obrig.
codigo_request	Inteiro	Código de um Request já criado. Caso o código não seja incluído no parâmetro, um novo Request será criado.	Não
tipo_certificado	Inteiro	Tipo do certificado. Os possíveis valores são: 1 = DV SSL - Domain SSL;
2 = OV SSL - Organization SSL;
3 = EV SSL - Extended SSL	Sim
tipo_domínio	Texto	Tipo do domínio do certificado. Os possíveis valores são:
SING = Single domain
MULT = Multiple domains
WILD = Wildcard	Sim
organização	Inteiro	Código da organização. Deverá ser informado o código de uma organização cadastrada no senhasegura .	Sim
nome_comum	Texto	Nome comum do certificado.	Sim
san	Array	Subject Alternative Name.
Será preenchido com o nome_comum caso o san não seja informado.	Não
tags	Array	Tags de identificação do certificado.
Será cadastrada novas tags caso as informadas não existam.	Não
criptografia	Texto	Algoritmo de criptografia. Os possíveis valores são:
RSA
DSA	Sim
tamanho_chave_criptografia	Inteiro	Tamanho da chave de criptografia. Os possíveis valores são:
4096
2048
1024	Sim
algoritmo_certificado	Texto	Algoritmo de assinatura Os possíveis valores são: SHA256
SHA384
SHA512
Se a criptografia escolhida for DSA, será permitido apenas o uso de SHA256.	Sim
validade	Inteiro	Tempo de validade do certificado, em dias.	Sim
senha_chave	Texto	Senha da chave do certificado.	Não
senha_revogacao	Texto	Senha de revogação do certificado.	Não
ambientes	Array	Ambientes do certificado.
Serão cadastrados novos ambientes de certificado caso os informados não existam.	Não
sistemas	Array	Sistemas do certificado.
Serão cadastrados novos sistemas de certificado caso os informados não existam.	Não
projeto	Texto	Projeto do certificado no request.	Não
ip_externo	Texto	IP externo do certificado no request.	Não
ip_hostname	Texto	IP ou hostname do certificado no request.	Não
justificativa	Texto	Justificativa do request com até 1024 caracteres.	Não
responsavel	Inteiro	Código do responsável pelo request e pelo certificado.
Deverá ser um usuário cadastrado no senhasegura .	Não
descricao	Texto	Descrição do request com até 512 caracteres.	Não

Resposta para certificados

Se o método for executado com sucesso ou com erro, a resposta consiste em um bloco certificado com os campos:

Campo	Tipo	Sucesso	Erro
status	Inteiro	, para a criação de certificados
200, para a edição de certificados	4xx
messagem	Texto	Created, para a criação de certificados
OK, para a edição de certificados	Não foi possível criar o request.
erro	Boolean	false	true
codigo_request	Inteiro	Código do request.	O código de request informado é inválido
tipo_certificado	Inteiro	Tipo do certificado informado.	O tipo de certificado informado é inválido.
tipo_domínio	Texto	Tipo do domínio do certificado informado.	O tipo do domínio do certificado informado é inválido.
organizacao	Inteiro	Código da organização informado.	O código da organização informado é inválido
nome_comum	Texto	Nome comum informado.	O nome comum do certificado não foi informado.
san	Array	SAN informado(s).	N/A
tags	Array	Tags informadas.	N/A
criptografia	Texto	Algoritmo de criptografia informado.	O algoritmo de criptografia informado é inválido.
tamanho_chave_criptografia	Inteiro	Tamanho da chave de criptografia informado.	O tamanho da chave de criptografia informado é inválido.
algoritmo_certificado	Texto	Algoritmo de assinatura informado.	O algoritmo de assinatura informado é inválido.
validade	Inteiro	Tempo de validade do certificado informado.	O tempo de validade do certificado informado é inválido.
senha_chave	Texto	Informação sensível.	A senha da chave do certificado informada é inválida.
senha_revogacao	Texto	Informação sensível.	A senha da chave do certificado informada é inválida.
ambientes	Array	Ambientes informados.	N/A
sistemas	Array	Sistemas informados.	N/A
projeto	Texto	Projeto informado.	N/A
ip_externo	Texto	IP informado.	N/A
ip_hostname	Texto	IP ou hostname informado.	N/A
justificativa	Texto	Justificativa informada.	A justificativa deve ter no máximo 1024 caracteres.
responsavel	Inteiro	Código do responsável informado.	O código do responsável informado é inválido.
descricao	Texto	Descrição informada.	A descrição deve ter no máximo 512 caracteres.

Consultar/Listar Request

GET https://url_do_cofre/iso/certificado/request/listar/\[codigo_request\] 

O método Consultar/Listar Request consulta uma ou mais requests de certificado no senhasegura .

Parâmetros

Campo	Tipo	Descrição	Obrig.
codigo_request	Inteiro	Código de um Request já criado.	Não
status_request	Inteiro	Código de um status de um request.	Não
tipo_certificado	Inteiro	Tipo do certificado. As opções serão:
1 = DV SSL - Domain SSL
2 = OV SSL - Organization SSL
3 = EV SSL - Extended SSL	Não
tipo_domínio	Texto	Tipo do domínio do certificado. As opções serão:
SING = Single domain
MULT = Multiple domains
WILD = Wildcard	Não
organizacao	Inteiro	Código da organização cadastrada no senhasegura .	Não
nome_comum	Texto	Nome comum do certificado.	Não
san	Texto	Subject Alternative Names, separados por vírgula	Não
tags	Texto	Tags de identificação do certificado, separados por vírgula	Não
criptografia	Texto	Algoritmo de criptografia. As opções serão:
RSA
DSA	Não
tamanho_chave_criptografia	Inteiro	Tamanho da chave de criptografia. As opções serão:
4096
2048
1024	Não
algoritmo_certificado	Texto	Algoritmo de assinatura As opções serão:
SHA256
SHA384
SHA512	Não
validade	Inteiro	Tempo de validade do certificado em dias.	Não
senha_chave	Texto	Senha da chave do certificado.	Não
senha_revogacao	Texto	Senha de revogação do certificado.	Não
ambientes	Texto	Ambientes do certificado, separados por vírgula	Não
sistemas	Texto	Sistemas do certificado, separados por vírgula	Não
projeto	Texto	Projeto do certificado no request.	Não
ip_externo	Texto	IP externo do certificado no request.	Não
ip_hostname	Texto	IP ou hostname do certificado no request.	Não
responsavel	Inteiro	Código do responsável pelo request e pelo certificado.	Não
offset	Inteiro	Número base da contagem de registros pela paginação.	Não
limit	Inteiro	Número de registros na paginação.	Não

Resposta para certificados

Se o método for executado com sucesso ou erro, a resposta consiste em um bloco certificado com os campos:

Campo	Tipo	Sucesso	Erro
status	Inteiro		4xx
messagem	Texto	OK	Não foi possível encontrar requests com as informações fornecidas
erro	Boolean	false	true
codigo_request	Inteiro	Código do request.	Não existe um request com o código informado.O código de request informado é inválido.
status_request	Inteiro	Código e nome do status do request.	Não existem requests com o status informado.O código de status informado é inválido
tipo_certificado	Inteiro	Tipo do certificado informado.	Não existem requests com o tipo do certificado informado.O tipo de certificado informado é inválido.
tipo_domínio	Texto	Tipo do domínio do certificado informado.	Não existem requests com o tipo do domínio informado.O tipo do domínio do certificado informado é inválido.
organizacao	Inteiro	Código da organização informado.	Não existem requests com o código da organização informado.O código da organização informado é inválido.
nome_comum	Texto	Nome comum informado.	Não existem requests com o nome comum informado.
san	Array	SAN informado(s).	Não existem requests com o(s) SAN(s) informado(s).
tags	Array	Tags informadas.	Não existem requests com a(s) Tag(s) informada(s).
criptografia	Texto	Algoritmo de criptografia informado.	Não existem requests com o algoritmo de criptografia informado.O algoritmo de criptografia informado é inválido.
tamanho_chave_criptografia	Inteiro	Tamanho da chave de criptografia informado.	Não existem requests com o tamanho da chave de criptografia informado. O tamanho da chave de criptografia informado é inválido.
algoritmo_certificado	Texto	Algoritmo de assinatura informado.
	Não existem requests com o algoritmo de assinatura informado. O algoritmo de assinatura informado é inválido.
validade	Inteiro	Tempo de validade do certificado informado.	Não existem requests com o tempo de validade informado. O tempo de validade do certificado informado é inválido.
senha_chave	Texto	Informação sensível.	Não existem requests com a senha da chave informada. A senha da chave do certificado informada é inválida.
senha_revogacao	Texto	Informação sensível.	Não existem requests com a senha de revogação informada. A senha de revogação do certificado informada é inválida.
ambientes	Array	Ambientes informados.	Não existem requests com os ambientes informados.
sistemas	Array	Sistemas informados.	Não existem requests com os sistemas informados.
projeto	Texto	Projeto informado.	Não existem requests com o projeto informado.
ip_externo	Texto	IP informado.	Não existem requests com o IP externo informado.
ip_hostname	Texto	IP ou hostname informado.	Não existem requests com o IP ou hostname informado.
justificativa	Texto	Justificativa informada.
responsavel	Inteiro	Código e nome do responsável informado.	Não existem requests com o código de responsável informado. O código do responsável informado é inválido.
descricao	Texto	Descrição informada.

Assinar Request

GET https://url_do_cofre/iso/certificado/request/assinar/\[codigo_request\] 

O método Assinar Request assina um request existente no senhasegura .

Parâmetros

Campo	Tipo	Descrição	Obrigatório
codigo_request	Inteiro	Código do request a ser assinado..	Sim
auto_assinado	Inteiro	Indica se é auto-assinado.
As opções serão:
1 = true
0 = false	Sim
ca	Inteiro	Código da CA responsável pela assinatura request.
Obrigatório, caso auto_assinado seja false.	Condicional
justificativa	Texto	Texto de até 1024 caracteres para justificativa.	Não
motivo	Inteiro	Código do motivo da assinatura.
Deverá informar um código de um motivo cadastrado no senhasegura	Sim
gmud	Texto	caracteres para determinar o código do ITSM.
Obrigatório caso no grupo de acesso do certificado o parâmetro "Código de governança obrigatório ao justificar" esteja habilitado.
Realizar as validações no ITSM da mesma forma que é feito na interface web.	Condicional

Resposta para certificados

Se o método for executado com sucesso, a resposta consiste em um bloco certificado com os campos:

Campo	Tipo	Sucesso	Erro
status	Inteiro		4xx
messagem	Texto	OK	Não foi possível assinar o request.
erro	Boolean	false	true
codigo_request	Inteiro	Código da request.	Informe um código de request. O código da request informado é inválido.
auto_assinado	Inteiro	Valor informado.	Não existem requests para este valor de auto-assinado informado. O valor para auto-assinado informado é inválido.
ca	Inteiro	Código e nome da CA informado.	Não existem requests com o código da CA informado. O código da CA informado é inválido
justificativa	Texto	Justificativa informada.	A justificativa deve ter no máximo 1024 caracteres.
motivo	Inteiro	Código e nome do motivo informado.	O código do motivo informado é inválido.
gmud	Texto	Código da GMUD informado.	Informe o código da GMUD.

Consultar/Listar Certificados

GET https://url_do_cofre/iso/certificado/listar/\[codigo_certificado\] 

O método Consultar/Listar Certificados consulta uma ou mais certificados no senhasegura.

Parameters

Campo	Tipo	Descrição	Obrig.
codigo_certificado	Inteiro	Código de um certificado já criado no senhasegura.	Não
status_certificado	Inteiro	Código de um status de um certificado.
As opções serão:
1 = Válido
2 = Revogado
3 = Renovação pendente
4 = Expirado	Não
ativo	Inteiro	Estado do certificado no senhasegura.
As opções serão:
1 = Ativo
0 = Inativo	Não
inicio_validade	Texto	Data de início da validade.	Não
fim_validade	Texto	Data de fim da validade.	Não
origem_certificado	Inteiro	Origem do certificado no senhasegura .
As opções serão:
SCAN = Scan e Discovery
REQU = Request
IMPO = Importado manualmente	Não
tipo_certificado	Inteiro	Tipo do certificado.
As opções serão:
1 = DV SSL - Domain SSL
2 = OV SSL - Organization SSL
3 = EV SSL - Extended SSL	Não
tipo_domínio	Texto	Tipo do domínio do certificado. As opções serão:
SING = Single domain
MULT = Multiple domains
WILD = Wildcard	Não
organizacao	Inteiro	Código da organização.	Não
nome_comum	Texto	Nome comum do certificado.	Não
san	Texto	Subject Alternative Name.
Poderá informar mais de 1 separados por vírgula.	Não
tags	Texto	Tags de identificação do certificado.
Poderá informar mais de 1 separados por vírgula.	Não
criptografia	Texto	Algoritmo de criptografia.
As opções serão:
RSA
DSA	Não
tamanho_chave_criptografia	Inteiro	Tamanho da chave de criptografia.
As opções serão:
4096
2048
1024	Não
algoritmo_certificado	Texto	Algoritmo de assinatura
As opções serão:
sha256
sha384
sha512	Não
validade	Inteiro	Tempo de validade do certificado em quantidade de dias.	Não
senha_chave	Texto	Senha da chave do certificado.	Não
senha_revogacao	Texto	Senha de revogação do certificado.	Não
ambientes	Texto	Ambientes do certificado.
Poderá informar mais de 1 separados por vírgula.	Não
sistemas	Texto	Sistemas do certificado.
Poderá informar mais de 1 separados por vírgula.	Não
projeto	Texto	Projeto do certificado no request.	Não
ip_externo	Texto	IP externo do certificado no request.	Não
ip_hostname	Texto	IP ou hostname do certificado no request.	Não
auto_assinado	Inteiro	Indica se é auto-assinado.
As opções serão:
1 = true
0 = false	Não
ca	Inteiro	Código da CA responsável pela assinatura request.	Não
responsável	Inteiro	Código do responsável pelo request e pelo certificado.	Não
offset	Inteiro	Número base da contagem de registros pela paginação.	Não
limit	Inteiro	Número de registros na paginação.	Não

Resposta para certificados

Se o método for executado com sucesso ou erro, a resposta consiste em um bloco certificado com os campos:

Campo	Tipo	Sucesso	Erro
status	Inteiro		4xx
messagem	Texto	OK	Não foi possível encontrar certificados com as informações fornecidas.
erro	Boolean	false	true
codigo_certificado	Inteiro	Código da request.	Não existe um certificado com o código informado. O código do certificado informado é inválido.
status_certificado	Inteiro	Código e nome do status do certificado.	Não existem certificados com o status informado. O código de status informado é inválido.
ativo	Inteiro	Código e nome do estado do certificado no senhasegura.	Não existe nenhum certificado com o estado informado. O código do estado informado é inválido.
inicio_validade	Texto	Data de início da validade.	Não existem certificados com a data de início da validade informada. A data de início da validade informada é inválida.
fim_validade	Texto	Data de fim da validade.	Não existem certificados com a data de fim da validade informada. A data de fim da validade informada é inválida.
origem_certificado	Inteiro	Origem do certificado no senhasegura.	Não existem certificados com a origem informada. A origem informada é inválida.
tipo_certificado	Inteiro	Tipo do certificado	Não existem certificados com o tipo informado. O tipo de certificado informado é inválido.
tipo_domínio	Texto	Tipo do domínio do certificado	Não existem certificados com o tipo do domínio informado. O tipo do domínio do certificado informado é inválido.
organizacao	Inteiro	Código e nome da organização informado	Não existem certificados com o código da organização informado. O código da organização informado é inválido.
nome_comum	Texto	Nome comum do certificado	Não existem certificados com o nome comum informado.
san	Texto	SAN do certificado	Não existem certificados com o(s) SAN(s) informado(s).
tags	Texto	Tags do certificado	Não existem certificados com a(s) Tag(s) informada(s).
criptografia	Texto	Algoritmo de criptografia do certificado	Não existem certificados com o algoritmo de criptografia informado.O algoritmo de criptografia informado é inválido.
tamanho_chave_criptografia	Inteiro	Tamanho da chave de criptografia do certificado	Não existem certificados com o tamanho da chave de criptografia informado. O tamanho da chave de criptografia informado é inválido.
algoritmo_certificado	Texto	Algoritmo de assinatura do certificado	Não existem certificados com o algoritmo de assinatura informado. O algoritmo de assinatura informado é inválido.
validade	Inteiro	Tempo de validade do certificado	Não existem certificados com o tempo de validade informado. O tempo de validade do certificado informado é inválido.
senha_chave	Texto	Senha da chave do certificado.	Não existem certificados com a senha da chave informada. A senha da chave do certificado informada é inválida.
senha_revogacao	Texto	Senha de revogação do certificado.	Não existem certificados com a senha de revogação informada. A senha de revogação do certificado informada é inválida.
ambientes	Texto	Ambientes do certificado	Não existem certificados com o(s) ambiente(s) informado(s).
sistemas	Texto	Sistemas do certificado	Não existem certificados com o(s) sistema(s) informado(s).
projeto	Texto	Projeto do certificado	Não existem certificados com o projeto informado.
ip_externo	Texto	IP externo do certificado	Não existem certificados com o IP externo informado.
ip_hostname	Texto	IP ou hostname do certificado	Não existem certificados com o IP ou hostname informado.
auto_assinado	Inteiro	Informação se o certificado é auto-assinado	Não existem certificados para este valor de auto-assinado informado. O valor para auto-assinado informado é inválido.
ca	Inteiro	Código e nome da CA informado	Não existem certificados com o código da CA informado.O código da CA informado é inválido.
responsavel	Inteiro	Código e nome do responsável informado	Não existem certificados com o código de responsável informado.O código do responsável informado é inválido.
descricao	Texto	Descrição do certificado
informacoes_publicacao	Array	Informações adicionais para publicação
dispositivos	Array	Código dos dispositivos atrelados ao certificado

Funcionalidades

O webservice de integração senhasegura possui algumas funcionalidades para realizar operações na aplicação.

Publicar Certificado

POST https://url_do_cofre/iso/cert/publicar/ 

A funcionalidade Publicar Certificado solicita a publicação de um certificado em um ou mais dispositivos

Parâmetros

Campo	Tipo	Descrição	Obrigatório
codigo_certificado	Inteiro	Código do certificado a ser publicado.	Sim
codigo_perfil_publicacao	Inteiro	Código do perfil de publicação.
Será utilizado um perfil de publicação previamente cadastrado no senhasegura .	Sim
justificativa	Texto	Justificativa da publicação com até 1024 caracteres.	Não
motivo	Inteiro	Código do motivo da publicação.
Deverá informar um código de um motivo cadastrado no senhasegura .	Sim
gmud	Texto	caracteres para determinar o código do ITSM.
Obrigatório caso no grupo de acesso do certificado o parâmetro "Código de governança obrigatório ao justificar" esteja habilitado.
Realizar as validações no ITSM da mesma forma que é feito na interface web.	Condicional
dispositivos	Array	Array com os códigos dos dispositivos onde o certificado deverá ser publicado	Sim

Resposta para certificados

Se a funcionalidade for executado com sucesso ou erro, a resposta consiste em um bloco certificado com os campos:

Campo	Tipo	Sucesso	Erro
status	Inteiro		4xx
messagem	Texto	Created	Código de certificado inválido.
erro	Boolean	false	true
codigo_publicação	Inteiro	Código do agendamento da publicação
motivo	Inteiro	Código e nome do motivo da publicação	O código do motivo informado é inválido.
gmud	Texto	Código da GMUD informado	Informe o código da GMUD.Código de GMUD não existe no sistema de ITSM integrado ao senhasegura . O código deve ter no máximo 30 caracteres.
dispositivos	Array	Códigos de dispositivos para publicação

Consultar/Listar Publicações

GET https://url_do_cofre/iso/cert/publicar/listar/\[codigo_publicacao\] 

A funcionalidade Consultar/Listar Publicações consulta uma ou mais publicações no senhasegura .

Parâmetros

Campo	Tipo	Descrição	Obrigatório
codigo_publicacao	Inteiro	Código da publicação.	Não
codigo_certificado	Inteiro	Código do certificado a ser Publicado.	Não
codigo_perfil_publicacao	Inteiro	Código do perfil de publicação.	Não
data_criacao	Texto	Data de cadastro da publicação	Não
processado	Inteiro	Status do processamento da publicação.
As opções serão:
1 = Sim
0 = Não	Não
erro	Inteiro	Status de erro da publicação.
As opções serão:
1 = Sim
0 = Não	Não
motivo	Inteiro	Código do motivo da publicação.	Não
gmud	Texto	Texto da GMUD informada.	Não
dispositivo	Inteiro	Código do dispositivo da publicação.	Não
offset	Inteiro	Número base da contagem de registros pela paginação.	Não
limit	Inteiro	Número de registros na paginação.	Não

Resposta para certificados

Se a funcionalidade for executado com sucesso ou erro, a resposta consiste em um bloco certificado com os campos:

Campo	Tipo	Sucesso	Erro
status	Inteiro		4xx
messagem	Texto	OK	Não foi possível encontrar publicações com as informações fornecidas.
erro	Boolean	false	true
codigo_publicação	Inteiro	Código do agendamento da publicação	Não existe uma publicação com o código informado. O código da publicação informado é inválido.
processado	Inteiro	Status do processamento da publicação
erro	Inteiro	Status de erro da publicação
motivo	Inteiro	Código e nome do motivo da publicação	O código do motivo informado é inválido.
gmud	Texto	Código da GMUD informado	Informe o código da GMUD. Código de GMUD não existe no sistema de ITSM integrado ao senhasegura . O código deve ter no máximo 30 caracteres.
codigo_credencial	Inteiro	Código da credencial para publicação	O código da credencial informado é inválido.
username	Texto	Username para busca de credenciais
qtd_dispostivos	Inteiro	Quantidade de dispositivos da publicação
dispositivos	Array	Códigos de dispositivos da publicação

Criar/Editar Perfil de Publicação Apache

POST https://url_do_cofre/iso/cert/perfil/apache/ 

A funcionalidade Criar/Editar Perfil de Publicação Apache cria ou edita um perfil de publicação do plugin Apache.

Parâmetros

Campo	Tipo	Descrição	Obrigatório
codigo_perfil	Inteiro	Código de um perfil já criado.
Caso o código não seja passado, o sistema interpretará como a criação de um perfil.	Não
nome_perfil	Texto	Nome do perfil a ser criado.	Sim
site	Texto	Site onde o certificado deverá ser instalado.
Se não for informado, o certificado será instalado no site padrão do Apache.	Não
config_path	Texto	Endereço da configuração.
Padrão:
/etc/apache2/sites-available/default.com.conf	Não
porta	Inteiro	Porta.
Padrão: 443	Não
codigo_credencial	Inteiro	Código da credencial a ser utilizada na publicação.
Será utilizada uma credencial previamente cadastrada o cofre.
Esta informação será obrigatória caso não seja informado um username.	Condicional
username	Texto	Username que será utilizado para localizar credenciais para a publicação.
Esta informação será obrigatória caso não seja informado um codigo_credencial	Condicional
dispositivos	Array	Array com os códigos dos dispositivos onde o certificado deverá ser publicado	Sim

Resposta para certificados

Se a funcionalidade for executada com sucesso ou erro, a resposta consiste em um bloco certificado com os campos:

Campo	Tipo	Sucesso	Erro
status	Inteiro	- Criar
200 - Editar	4xx
messagem	Texto	Created
OK	Não foi possível criar o perfil.
erro	Boolean	false	true
codigo_perfil	Inteiro	Código do perfil de publicação	O código do perfil informado é inválido.
nome_perfil	Texto	Nome do perfil.
site	Texto	Site informado
config_path	Texto	Endereço da configuração
porta	Inteiro	Porta
codigo_credencial	Inteiro	Código da credencial para publicação	O código da credencial informado é inválido.
username	Texto	Username para busca de credenciais
dispositivos	Array	Códigos de dispositivos para publicação

Criar/Editar Perfil de Publicação IIS

POST https://url_do_cofre/iso/cert/perfil/iis/ 

A funcionalidade Criar/Editar Perfil de Publicação IIS cria ou edita um perfil de publicação do plugin IIS.

Parâmetros

Campo	Tipo	Descrição	Obrigatório
codigo_perfil	Inteiro	Código de um perfil já criado.
Caso o código não seja passado, o sistema interpretará como a criação de um perfil.	Não
nome_perfil	Texto	Nome do perfil a ser criado.	Sim
site	Texto	Site onde o certificado deverá ser instalado.
Se não for informado, o certificado será instalado no site padrão do IIS.	Não
cert_store	Texto	Repositório de gerenciamento de certificados do IIS.
Padrão:
MY	Não
porta	Inteiro	Porta.
Padrão:
443	Não
codigo_credencial	Inteiro	Código da credencial a ser utilizada na publicação.
Será utilizada uma credencial previamente cadastrada o cofre.
Esta informação será obrigatória caso não seja informado um username.	Condicional
username	Texto	Username que será utilizado para localizar credenciais para a publicação.
Esta informação será obrigatória caso não seja informado um codigo_credencial.	Condicional
dispositivos	Array	Array com os códigos dos dispositivos onde o certificado deverá ser publicado
Os dispositivos devem existir no senhasegura	Sim

Resposta para certificados

Se a funcionalidade for executada com sucesso, a resposta consiste em um bloco certificado com os campos:

Campo	Tipo	Sucesso	Erro
status	Inteiro	- Criar
200 - Editar	4xx
messagem	Texto	Created
OK	Não foi possível criar o perfil.
erro	Boolean	false	true
codigo_perfil	Inteiro	Código do perfil de publicação	O código do perfil informado é inválido.
nome_perfil	Texto	Nome do perfil
site	Texto	Site informado
cert_store	Texto	Repositório de gerenciamento de certificados do IIS
porta	Inteiro	Porta
codigo_credencial	Inteiro	Código da credencial para publicação	O código da credencial informado é inválido.
username	Texto	Username para busca de credenciais
dispositivos	Array	Códigos de dispositivos para publicação

Criar/Editar Perfil de Publicação F5 BigIP

POST https://url_do_cofre/iso/cert/perfil/bigip/ 

A funcionalidade Criar/Editar Perfil de Publicação F5 BigIP cria ou edita um perfil de publicação do plugin F5 BigIP.

Parâmetros

Campo	Tipo	Descrição	Obrigatório
codigo_perfil	Inteiro	Código de um perfil já criado.
Caso o código não seja passado, o sistema interpretará como a criação de um perfil.	Não
nome_perfil	Texto	Nome do perfil a ser criado.	Sim
nome_particao	Texto	Nome da partição.	Não
nome_certificado	Texto	Nome do certificado.
Se já existir um certificado com o mesmo nome configurado, na publicação ele será substituído.	Não
perfis_client_vips	Array	Array de Perfis SSL Client e seus VIPs
Ex: [ "MEU_CLIENT_1"=>"VIP_1",
"MEU_CLIENT_2"=>"VIP_2" ]	No
perfis_server_vips	Array	Array de Perfis SSL Server e seus VIPs.
Ex: [ "MEU_SERVER_1"=>"VIP_1",
"MEU_SERVER_2"=>"VIP_2" ]	Não
codigo_credencial	Inteiro	Código da credencial a ser utilizada na publicação.
Será utilizada uma credencial previamente cadastrada o cofre. Esta informação será obrigatória caso não seja informado um username.	Condicional
username	Texto	Username que será utilizado para localizar credenciais para a publicação.
Esta informação será obrigatória caso não seja informado um codigo_credencial.	Condicional
dispositivos	Array	Array com os códigos dos dispositivos onde o certificado deverá ser publicado	Sim

Resposta para certificados

Se a funcionalidade for executada com sucesso, a resposta consiste em um bloco certificado com os campos:

Campo	Tipo	Sucesso	Error
status	Inteiro	- Criar
200 - Editar	4xx
messagem	Texto	Created
OK	Não foi possível criar o perfil.
erro	Boolean	false	true
codigo_perfil	Inteiro	Código do perfil de publicação	O código do perfil informado é inválido.
nome_perfil	Texto	Nome do perfil
nome_particao	Texto	Nome da partição
nome_certificado	Texto	Nome do certificado que será exibido na aplicação web
perfis_client	Array	Nome completo do perfil. Ex:
[ "MEU_CLIENTE_1"=>"VIP_1",
"MEU_CLIENTE_2"=>"VIP_2"
]
perfis_server	Array	Nome completo do perfil. Ex:
[ "MEU_SERVER_1"=>"VIP_1",
"MEU_SERVER_2"=>"VIP_2"
]
codigo_credencial	Inteiro	Código da credencial para publicação	O código da credencial informado é inválido.
username	Texto	Username para busca de credenciais
dispositivos	Array	Códigos de dispositivos para publicação

Criar/Editar Perfil de Publicação WebSphere WAS

POST https://url_do_cofre/iso/cert/perfil/was/ 

A funcionalidade Criar/Editar Perfil de Publicação WebSphere Was cria ou edita um perfil de publicação do plugin WebSphere WAS.

Parâmetros

Campo	Tipo	Descrição	Obrigatório
codigo_perfil	Inteiro	Código de um perfil já criado.
Caso o código não seja passado, o sistema interpretará como a criação de um perfil.	Não
nome_perfil	Texto	Nome do perfil a ser criado.	Sim
key_db_path	Texto	Endereço e nome da Key Database.	Sim
key_db_password	Texto	Senha do servidor.	Sim
label	Texto	Label do servidor.	Sim
codigo_credencial	Inteiro	Código da credencial a ser utilizada na publicação.
Será utilizada uma credencial previamente cadastrada o cofre. Esta informação será obrigatória caso não seja informado um username.	Condicional
username	Texto	Username que será utilizado para localizar credenciais para a publicação.
Esta informação será obrigatória caso não seja informado um codigo_credencial.	Condicional
dispositivos	Array	Array com os códigos dos dispositivos onde o certificado deverá ser publicado.	Sim

Resposta para certificados

Se a funcionalidade for executada com sucesso ou erro, a resposta consiste em um bloco certificado com os campos:

Campo	Tipo	Sucesso	Erro
status	Inteiro	- Criar
200 - Editar	4xx
messagem	Texto	Created
OK	Não foi possível criar o perfil.
erro	Boolean	false	true
codigo_perfil	Inteiro	Código do perfil de publicação	O código do perfil informado é inválido.
nome_perfil	Texto	Nome do perfil
key_db_path	Texto	Endereço e nome da Key Database
key_db_password	Texto	Senha do servidor
label	Texto	Label do servidor.
codigo_credencial	Inteiro	Código da credencial para publicação.	O código da credencial informado é inválido.
username	Texto	Username para busca de credenciais.
dispositivos	Array	Códigos de dispositivos para publicação.

Métodos DevSecOps

Introdução

O senhasegura DevOps Secret Management (DSM) oferece uma forma rápida e segura de ferramentas e aplicações para solicitar informações confidenciais tais como segredos, credenciais e outros dados sensíveis que são utilizados no ciclo de vida do DevOps.

O objectivo desta seção é fornecer orientação às equipes DevOps que necessitam de integração com o senhasegura para gerir todos os segredos utilizados no seu pipeline.

Nesta seção, serão abordadas as seguintes funções DevOps:

• Solicitar um secret para ser usado em um aplicativo

• Disponibilizar uma nova credencial para ser utilizada em um pedido

• Deprovisionar uma credencial

Método

O serviço web de integração senhasegura possui um método para consultar secrets armazenados na aplicação.

Consultar secret

GET https://vault_url/iso/dapp/application 

O método de aplicação consulta todos os segredos ligados a uma autorização de aplicação.

Resposta

Campo	Tipo	Descrição
nome	String	Nome da aplicação
descrição	String	Descrição da aplicação
tags	String	Tags que identificam a aplicação
sistema	String	Sistema Secret
ambiente	String	ambiente secret
secret _id	Inteiro	ID do secret
secret_name	String	Nome do secret
identificador	String	Identificador do secret
versão	String	Versão do Secret
expiration_date	Dia/Hora	Data de validade do secret
motor	String	Secret engine
valores	String	Valores do Secret

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

Provisão de uma credencial

POST https://vault_url/iso/coe/dapp/provision 

Criar um novo segredo de credencial para ser usado em um recipiente.

Parametros

Campo	Tipo	Descrição	Obrig.
pod_nome	String	Nome da cápsula que irá usar a credencial	Sim
deploy	String	Nome do deploy que irá usar a credencial	Sim
namespace	String	Namespace do contentor que irá utilizar a credencial	Sim

Resposta

Campo	Tipo	Descrição
nome	String	Nome da aplicação
descrição	String	Descrição da aplicação
tags	String	Tags que identificam a aplicação
sistema	String	Secret system
ambiente	String	ambiente secret
secret_id	Inteiro	ID do secret
secret_nome	String	Nome secret
identificador	String	Identificador do secret
versão	String	Versão do Secret
expiration_date	Data/Hora	Data de validade do secret
motor	String	Secret engine
Valor	String	Valor da secret

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

Desprovisionar uma credencial

POST https://vault_url/iso/coe/dapp/deprovision 

Remove a credencial a ser utilizada por um container.

Parâmetros

Campo	Tipo	Descrição	Obrig.
pod_nome	String	Nome da cápsula que irá usar a credencial	Sim
deploy	String	Nome do deploy que irá usar a credencial	Sim
namespace	String	Namespace do contentor que usará a credencial	Sim
secret_id	Inteiro	Secret ID	Sim

Agentes externos

Agente Java WebService A2A

Neste documento utilizaremos a biblioteca Java como exemplo. Todas bibliotecas utilizam do mesmo canal REST para comunicação com o senhasegura , facilitando o desenvolvimento em qualquer linguagem que tenha suporte a webservice REST.

Este SDK disponibiliza acesso a credenciais (com recurso de cache) e conexão de banco de dados.

Os bancos de dados suportados para conexão atualmente são: MySQL, Oracle e PostgreSQL.

Os dados retornados pela API são os dados do Dispositivo e Credencial.

Atividades

Nesta seção, iremos abordar as seguintes funções do senhasegura :

• Operação da biblioteca Java

• Versões Java compatíveis com o agente

• Configurações do senhasegura

• Exemplos de uso

• Chamada de API via WebService

Versões compatíveis do Java

O agente Java Lib 0.1.5 é compatível com a versão Java 1.5 ou superior, o que permite o cache das senhas do agente, evitando assim consultas no cofre.

A versão 0.1.4 do agente é compatível com versões inferiores do Java 1.5, mas não fornece cache de senhas.

Java cache nativo

Utilizando o Agente Java WebService A2A , a aplicação cliente irá utilizar um cache local protegido para armazenar todas credenciais requisitadas. Essa funcionalidade garante a aplicação uma melhor performance e um backup local seguro para situaçõe sonde o senhasegura está inalcançável.

Se a credencial alvo sofrer alterações, o Agente Java WebService A2A irá falhar em construir o objeto de conexão de banco de dados e irá requisitar novamente a senha para o senhasegura . E se a nova senha retornada também falhar, uma exceção será lançada para alertar a aplicação cliente.

Usando o token para acessar os recursos

O seguinte script exemplifica o uso do recurso WebService A2A entre um cliente e o senhasegura :

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

Rastreabilidade

Em um ambiente produtivo, as mudanças são constantes e importantes para melhorar o processo. No entanto, é importante saber "por que, como e por quem" as mudanças foram realizadas.

O objetivo desses relatórios é exibir informações sobre todas as alterações feitas nos dados registrados em senhasegura .

Logs da API

Em Orbit ➔ Logs ➔ API este relatório incluí os registros de uso das APIs senhasegura.

O Relatório de logs imprimirá as seguintes informações:

• Código: é o código único da requisição

• ID do Cliente: é código da aplicação

• Cliente: é o nome da aplicação

• ID da Autorização: é o código da autorização

• Autorização: é a palavra Autorização segunda do código da mesma

• IP: de origem da requisição

• Recuso: é o nome do recurso utilizado

• Evento: é o tipo de evento

• Método: é o método utilizado (GET, POST, DELETE)

• Status: é o código HTTP da requisição

• URL: de método utilizado

• Erro: indica se ocorreu erro na requisição

• Tempo: de processamento da requisição

• Data Hora: da requisição

Boas Práticas de Uso

Neste capítulo você encontrará uma lista de boas práticas para que o uso do módulo WebService A2A seja feito de forma segura, qualquer dúvida consulte nossa equipe de suporte.

• Definir apenas uma credencial por autorização WebService A2A . Desta forma se diminui a superfície de risco, já que, a autorização estará atrelada apenas a uma única credencial, assim o rastreio das atividades é centralizado, e em caso de vulnerabilidade a resposta será mais rápida ao desabilitar uma credencial ao invés de várias.

• Definir que a autorização de WebService A2A tenha a restrição de IP de origem configurada apenas para os Servidores (e suas redundâncias) que gerenciam as aplicações que precisam de acesso às credenciais do senhasegura . Tenha consciência que o principio do privilégio mínimo também deve ser aplicado a máquinas, desta forma defina uma política que conceda acesso apenas aos servidores, que para realizar suas tarefas necessitam das credenciais gerenciadas pelo senhasegura .

• Dar preferência em utilizar a assinatura Oauth 2.0 (mais segura) à utilizar Oauth 1.0. Sempre opte por padrões mais atualizados que correspondem a níveis de segurança mais robustos e são compatíveis a tecnologia de seus ativos.

• Habilitar a funcionalidade de "Ativar a criptografia de informações sensíveis" para consultas por meio da API do senhasegura , e segmentar que o módulo de consulta de credencial e o módulo de decriptografia da informação sensível, seja realizada por desenvolvedores diferentes, para que nenhum deles tenha acesso a informação completa (Consulta e decriptografia da credencial);

• Implementar a consulta às credenciais necessárias à aplicação, para que elas sejam trazidas durante a execução da aplicação, e não haja a necessidade de armazená-las em nenhum arquivo. Armazenar as informações das credenciais em arquivo fora do gerenciamento do senhasegura deixará a credencial vulnerável a acessos não autorizados e as suas consultas não poderão ser rastreadas resultando em seu no uso irresponsável das credenciais.

• Orientar o programador a fazer um cache local da credencial, com controle de tempo de vida. Dessa maneira, se houver indisponibilidade do cofre, momentânea ou não, a aplicação não para de rodar, pois terá o cache local para consulta. Esta pratica pode evitar que as tarefas sejam paralisadas e causem indisponibilidade de um serviço importante.

• Conciliar o tempo de vida do cache local com o tempo de rotacionamento da senha pelo senhasegura . Desta forma a senha armazenada no cache local não ficará desatualizada em relação a credencial gerenciada pelo senhasegura , impossibilitando a autenticação em caso de indisponibilidade, já que a senha será outra. Aconselhe o programador que em caso da senha retornar um erro de conectividade fazer uma nova consulta ao senhasegura para verificar se a senha em questão já não foi rotacionada. Lembre-se que dependendo das configurações aplicadas no senhasegura as senhas podem rotacionar com frequência, por isso o cache local pode ficar desatualizado.

---

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

   ↩

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

   ↩