Utilização do CPQD iD ##################### Este documento tem por objetivo demonstrar como utilizar o CPQD iD (conjunto das APIs, Portal CPQD iD | Empresas e a carteira SOU iD) como fator de autenticação em aplicações e também na utilização de definição e emissão de múltiplas credenciais. Para realização da emissão de diferentes tipos de credenciais utilizando o ecossistema do CPQD iD, é necessário que a empresa emissora realize o seu cadastro no Portal CPQD iD | Empresas e realize em conjunto com as nossas APIs os passos descritos abaixo. À medida que os passos são realizados, o usuário poderá se conectar com a empresa emissora por meio do aplicativo SOU iD, receber ofertas de credenciais, aceitá-las ou recusá-las e compartilhá-las com outros agentes. Já para clientes que desejam utilizar o CPQD iD como fator de autenticação em suas aplicações, é necessário que esta empresa também realize seu cadastro no Portal CPQD iD | Empresas, registre suas aplicações e suas respectivas URLs e configure-as para contemplar o botão “Login com CPQD iD”. Sendo assim, o usuário que utiliza o SOU iD deverá possuir em sua carteira uma credencial de identidade básica para conseguir ler o QR Code e se autenticar na aplicação. **Informação:** Todas as APIs necessitam da chave (API key) para autenticação. Desta forma, utilize a chave disponibilizada pelo time CPQD iD a você. 1. Portal CPQD iD | Empresas **************************** A instituição que deseja ser emissora de credenciais ou utilizar o CPQD iD como fator de autenticação, deverá efetuar seu cadastro em nosso Portal CPQD iD | Empresas. Este portal é responsável pela criação de definição de credenciais e o seu gerenciamento, apoiando o emissor neste processo como também é responsável pelo cadastro das aplicações e o seu gerenciamento, apoiando a instituição a configurar o botão de “Login com o CPQD iD”. 1.1 Cadastro no Portal CPQD iD | Empresas ========================================= Para que a empresa emissora possa usufruir das funcionalidades do Portal CPQD iD | Empresas, o primeiro passo é realizar o cadastro. Esse é iniciado pelo CPQD e completado pelo administrador após receber um link por e-mail. **1.** Deve-se enviar ao time CPQD iD os seguintes dados: - Nome completo; - Nome da instituição; - E-mail corporativo do administrador do agente emissor. **2.** Após o envio dos dados, um link será enviado no e-mail do administrador; **3.** Faz-se necessário clicar nesse link para que o cadastro seja finalizado. .. note:: Por questões de segurança, o **link** para a finalização do cadastro expira em **5 minutos**. Caso ele expire, será preciso entrar em contato com o time CPQD iD para que um novo link seja enviado. Ao finalizar o cadastro no Portal CPQD iD | Empresas, o agente emissor é registrado e poderá: - Criar definições de credenciais; - Implementar o CPQD iD para autenticação; - Configurar webhooks. **Informação importante:** Quando o cadastro é realizado, é possível visualizar as informações do agente emissor, como o **Nome** e o **E-mail** no menu "Minha Conta", e a **Instituição** e o **Wallet Name** no menu “Minha Carteira”, onde também é possível editar a instituição. O **Wallet Name** é a informação que será utilizada para recuperar o token de acesso do agente emissor. .. figure:: /_images/cpqdidUseMyAccount.png :alt: text :align: center :width: 80% Menu "Minha conta" .. figure:: /_images/cpqdidUseMyWallet.png :alt: text :align: center :width: 80% Menu "Minha Carteira" .. _passo-1.2: 1.2 Redefinição de senha ======================== O recurso de redefinição de senha está disponível: - Na tela de login, em "Esqueci minha senha" - No menu "Minha conta", em "Alterar senha" Para redefinir a senha, deve-se informar o e-mail cadastrado no Portal CPQD iD Empresas e clicar em "Redefinir". Um e-mail com o link para redefinição de senha será enviado. .. note:: Por questões de segurança, o link para a finalização do cadastro expira em 5 minutos. Caso ele expire, será preciso refazer o processo. .. _passo-1.3: 1.3 Fluxo para recuperação do token =================================== Para acionar as APIs do ACA-Py nos passos :ref:`passo-1.4.3`, :ref:`passo-1.4.4`, :ref:`passo-1.5.1`, :ref:`passo-1.7.1`, :ref:`passo-1.7.2` e :ref:`passo-1.7.3`, é necessário a recuperação do token para que as solicitações sejam autenticadas. Para isso, siga os passos a seguir: .. _passo-1.3.1: 1.3.1 Obter o Wallet Name ------------------------- Acesse o Portal CPQD iD Empresas no Menu "Minha Carteira" e copie o **Wallet Name**: .. figure:: /_images/cpqdidUseMyWallet.png :alt: text :align: center :width: 80% Menu "Minha Carteira" .. _passo-1.3.2: 1.3.2 Recuperar o token ----------------------- Após recuperar o **Wallet Name**, no postman, insomnia ou qualquer ferramenta de sua preferência para gerar requisições HTTP, recupere o token da seguinte forma: **Tipo**: POST **URL**: \https://blockchain.cpqd.com.br/hmcpqdid/afa/v2/wallet/{wallet_name}/token **Observação:** O **wallet_name** é o valor recuperado no passo :ref:`passo-1.3.1`. **Header**: .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Chave - Valor - Descrição * - ApiKey - {API Key} - API Key para autenticação disponibilizada pelo time CPQD iD a você. Esta requisição não possui body e, caso ocorra com sucesso, retornará um conteúdo parecido com o exemplo abaixo: .. code-block:: json { "token": "eyJ0eXAiOiJKV1QiLCJhbGcpSoCRPwL1MiP5.eyK5TQvaLQTjpRIwEiWiMGI2MTBkNC0yNzA5LTQxM2ItOTdjMB1jRTEjGZY3Mjk3NjhueQ.lGylPFKeZ9QBKove3X0ycoRpiYOKBNJlQwiVSQMoPEk" } .. _passo-1.4: 1.4 Fluxo para emissão de múltiplas credenciais =============================================== Para cadastrar tipos de credenciais, poder emiti-las e gerenciá-las, é necessário realizar os passos abaixo no Portal CPQD iD | Empresas. 1.4.1 Definição de credencial: ------------------------------ Após o registro do agente, a empresa emissora poderá cadastrar suas definições de credenciais. A definição de credencial é como o emissor estrutura as informações que comporão uma determinada credencial. Desta forma, pode-se cadastrar as definições de credenciais por meio do menu “Credenciais”. .. figure:: /_images/cpqdidUseMyCredentials.png :alt: text :align: center :width: 75% Menu "Credenciais" Para cadastrar uma nova definição de credencial, o botão “Nova” deve ser acionado. Neste momento, o formulário de cadastro será apresentado e o usuário poderá preencher as informações que constituem essa definição, como o nome e os atributos, de acordo com a necessidade. .. figure:: /_images/cpqdidUseNewCredentialFilled.png :alt: text :align: center :width: 75% Cadastro de definição de credencial Após finalizar o preenchimento dos dados, o botão “Confirmar” deve ser acionado para concluir o cadastro. Neste momento, será gerado o identificador da definição de credencial (nomeado como **cred_def_id**). Esta informação juntamente com o **token** será utilizada para gerar ofertas de credenciais. Logo, realizado o registro das definições, também poderá gerar ofertas de credenciais, desde que exista conexão do agente com o usuário que receberá a oferta (veremos este item no passo :ref:`passo-1.4.3`). 1.4.2 Consultar credenciais --------------------------- Após a inclusão da definição de credencial, ela ficará disponível para consulta também no menu “Credenciais”. Para consultá-las, basta clicar nessa opção e será apresentada a lista de definições cadastradas. Caso queira visualizar os detalhes da credencial, clique sobre ela e logo serão apresentados os dados que a compõem. .. figure:: /_images/cpqdidUseConsultaAtributosCredencial.png :alt: text :align: center :width: 75% Detalhes da credencial Além de apresentar os dados registrados no Portal, também é possível visualizar os dados do schema que compõem a credencial. .. figure:: /_images/cpqdidUseConsultaAtributosCredencialDetalhesSchema.png :alt: text :align: center :width: 75% Detalhes do Schema Esta página é importante para consultar as informações necessárias para gerar ofertas de credenciais e também solicitar o compartilhamento de dados aos usuários portadores da carteira SOU iD, utilizando a API CPQD iD. .. _passo-1.4.3: 1.4.3 Gerar convite de conexão para o usuário --------------------------------------------- Para seguir com o fluxo de emissão das credenciais, após realizar o cadastro da instituição e das definições de credenciais no Portal CPQD iD | Empresas, o próximo passo será gerar um convite de conexão para o usuário. Este convite de conexão é necessário para localizar e conectar o usuário com o emissor. Somente após esta conexão, será possível gerar uma oferta de credencial ou solicitar o compartilhamento de dados a ele. Desta forma, para gerar o convite de conexão atualmente é necessário utilizar nossos microsserviços (API), até que tenhamos implementado essa funcionalidade no Portal CPQD iD | Empresas. Para gerar este convite, os seguintes passos serão necessários: - No postman, insomnia ou qualquer ferramenta de sua preferência para gerar requisições HTTP, crie um convite de conexão pelo agente emissor da seguinte forma: **Tipo**: POST **URL**: \https://blockchain.cpqd.com.br/hmcpqdid/agent-issuer-com/connections/create-invitation **Header**: .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Chave - Valor - Descrição * - Content-Type - application/json - Cabeçalho para o tipo do conteúdo a ser trafegado (no caso o tipo é JSON) * - Authorization - Bearer {token} - Token do agente emissor para autenticar as solicitações (passo :ref:`passo-1.3`) * - ApiKey - {API Key} - API Key para autenticação disponibilizada pelo time CPQD iD a você. **Body**: .. code-block:: json {} Esta requisição retornará um conteúdo parecido com o exemplo abaixo: .. code-block:: json { "connection_id": "a536a167-4ccc-47b0-ae75-96c45bb86dbe", "invitation": { "@type": "did:sov:BzCbsNYhMrjHiqZDTUASHg;spec/connections/1.0/invitation", "@id": "97821a43-8afa-47ad-bb7f-7c85bd3de0c1", "serviceEndpoint": "https://blockchain.cpqd.com.br/hmcpqdid/agent-issuer-endpoint-com", "recipientKeys": [ "4RYBd8vpN3XwXefhoX1AmMHGhfvKWi2VRGed2HAfNxUu" ], "label": "CPQD_iD_Issuer" }, "invitation_url": "https://blockchain.cpqd.com.br/hmcpqdid/agent-issuer-endpoint-com?c_i=eyJAdHlwZSI6ICJkaWQ6c292OkJ6Q2JzTlloTXJqSGlxWkRUVUFTSGc7c3BlYy9jb25uZWN0aW9ucy8xLjAvaW52aXRhdGlvbiIsICJAaWQiOiAiOTc4MjFhNDMtOGFmYS00N2FkLWJiN2YtN2M4NWJkM2RlMGMxIiwgInNlcnZpY2VFbmRwb2ludCI6ICJodHRwczovL2Jsb2NrY2hhaW4uY3BxZC5jb20uYnIvaG1jcHFkaWQvYWdlbnQtYmFja29mZmljZS1lbmRwb2ludC1jb20iLCAicmVjaXBpZW50S2V5cyI6IFsiNFJZQmQ4dnBOM1h3WGVmaG9YMUFtTUhHaGZ2S1dpMlZSR2VkMkhBZk54VXUiXSwgImxhYmVsIjogIkNQUURfaURfSXNzdWVyIn0=" } Nesta saída, utilizaremos apenas o conteúdo gerado em “invitation_url”. Este trecho gerado possui o link de convite de conexão entre usuário e o agente emissor. O aplicativo SOU iD realiza a leitura de QR Code para se conectar com os agentes. Desta forma, será necessário utilizar o link gerado no “invitation_url” para geração de um código QR Code (você pode utilizar uma plataforma gratuita para isso, como o `QR Code Generator`_). Assim que o QR Code estiver disponível, o usuário poderá realizar a leitura por meio do aplicativo SOU iD. Neste momento, a conexão com o agente emissor será criada e o aplicativo estará pronto para receber ofertas de credenciais disponibilizadas por este emissor. **Observação:** Este processo ainda não é automático, por isso é necessário enviar ao usuário o link do convite de conexão para que ele obtenha um QR Code e possa realizar a leitura por meio do aplicativo SOU iD. Assim a conexão acontecerá entre o usuário e o agente emissor. .. _passo-1.4.4: 1.4.4 Gerar oferta de credencial -------------------------------- Para que uma credencial seja emitida, é necessário que o agente emissor crie uma oferta para o usuário, a partir da sua conexão existente e utilizando uma definição de credencial cadastrada. Esta oferta será enviada ao aplicativo do usuário, onde ele poderá revisar esses dados e aceitar a oferta, dando o seu consentimento na emissão. Desta forma, para que a oferta seja gerada e o usuário a receba em sua carteira, será necessário utilizar nosso microsserviço (API), até que tenhamos essa funcionalidade implementada no Portal CPQD iD | Empresas. - No postman, insomnia ou qualquer ferramenta de sua preferência para gerar requisições HTTP, crie uma oferta de credencial com o agente emissor da seguinte forma: **Tipo**: POST **URL**: \https://blockchain.cpqd.com.br/hmcpqdid/agent-issuer-com/issue-credential/send-offer **Header**: .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Chave - Valor - Descrição * - Content-Type - application/json - Cabeçalho para o tipo do conteúdo a ser trafegado (no caso o tipo é JSON) * - Authorization - Bearer {token} - Token do agente emissor para autenticar as solicitações (passo :ref:`passo-1.3`) * - ApiKey - {API Key} - API Key para autenticação disponibilizada pelo time CPQD iD a você. **Body**: .. code-block:: javascript { "comment": "xxxxxxxxxxxxxxx", //Insira um comentário para a oferta de credencial "credential_preview": { "attributes": [ { "name": "xxxxxxxxxx", //Insira o nome do atributo da sua definição de credencial "value": "xxxxxxxxx" //Insira o valor para o campo }, { "name": "xxxxxxxxxx", //Insira o nome do atributo da sua definição de credencial "value": "xxxxxxxxx" //Insira o valor para o campo } ] }, "connection_id": "XXXXXXXXXXXXXXXXXXXXXX", //Insira o id da conexão retornado no passo 1.4.3 "cred_def_id": "XXXXXXXXXXXXXXXXXXXXXXXX" //Insira o id da definição de credencial disponível no item "Definição de credencial" (passo 1.4.1) } Caso a requisição ocorra com sucesso, o usuário receberá a notificação da nova oferta de credencial, para que ele possa aceitar ou recusar (passo :ref:`passo-2.3.2`). Importante ressaltar que a oferta de credencial somente será executada com sucesso, caso o usuário esteja conectado com o agente emissor. 1.5. Fluxo para solicitação de compartilhamento de dados ======================================================== Para solicitar que um usuário portador da carteira SOU iD compartilhe seus dados com o agente, é necessário que o agente solicite uma apresentação de prova desses dados. Essa requisição, assim como o envio de oferta, necessita que o agente já esteja conectado com o portador da carteira. Desta forma, a partir desta conexão é possível enviar a solicitação à carteira do portador, gerando uma notificação que será endereçada ao aplicativo do usuário. Para que a solicitação do compartilhamento aconteça, será necessário utilizar o nosso microsserviço (API CPQD iD), até que tenhamos essa funcionalidade implementada no Portal CPQD iD | Empresas. .. _passo-1.5.1: 1.5.1. Gerar solicitação de prova de credencial ----------------------------------------------- No postman, insomnia ou qualquer ferramenta de sua preferência para gerar requisições HTTP, crie uma solicitação de prova de credencial com o agente da seguinte forma: **Tipo**: POST **URL**: \https://blockchain.cpqd.com.br/hmcpqdid/agent-issuer-com/present-proof/send-request **Header**: .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Chave - Valor - Descrição * - Content-Type - application/json - Cabeçalho para o tipo do conteúdo a ser trafegado (no caso o tipo é JSON) * - Authorization - Bearer {token} - Token do agente emissor para autenticar as solicitações (passo :ref:`passo-1.3`) * - ApiKey - {API Key} - API Key para autenticação disponibilizada pelo time CPQD iD a você. **Body**: .. code-block:: javascript { "proof_request": { "version": "1.0", //Insira a versão do schema, disponível no item "Consultar Credenciais" (passo 1.4.2) "requested_attributes": { "attributeName": { //O attributeName deve ser substituído pelo nome do campo que solicita o compartilhamento (Ex.: "name") "name": "xxxxxxxxxx", //Informe o nome do campo que deseja solicitar o compartilhamento. Deve ser o mesmo nome do atributo determinado na criação da definição de credencial (passo 1.4.1) "restrictions": [{ "cred_def_id": "XXXXXXX" //Caso queira escolher uma definição de credencial específica, informe o cred_def_id aqui. Caso não queira determinar o cred_def_id, remova o bloco "restrictions" }] }, "attributeName": { "name": "xxxxx", //Informe o nome do campo que deseja solicitar o compartilhamento "restrictions": [{ "cred_def_id": "XXXXXXX" //Caso queira escolher uma definição de credencial específica, informe o cred_def_id aqui. Caso não queira determinar o cred_def_id, remova o bloco "restrictions" }] } }, "requested_predicates": {}, //Este campo vazio deve ser enviado vazio mesmo "name": "XXXXXXX" //Informe o nome do agente que está solicitando o compartilhamento. Essa informação aparecerá na notificação ao usuário. }, "connection_id": "XXXXXXXXXXXXXXXXXXXXXX" //Informe o identificador da conexão com o usuário que deseja solicitar a prova dos dados. (realizado no passo 1.4.3) } Caso a requisição ocorra com sucesso, o usuário receberá a notificação da solicitação de compartilhamento dos dados (ou seja, o pedido de prova das credenciais) para que ele possa aceitar ou recusar (passo :ref:`passo-2.3.2`). Importante ressaltar que a solicitação de prova somente será executada com sucesso, caso o usuário esteja conectado com o agente que está solicitando o compartilhamento. 1.6. Fluxo para autenticação com o CPQD iD ========================================== Para cadastrar aplicações e configurar o CPQD iD para autenticação, é necessário realizar os passos abaixo no Portal CPQD iD | Empresas. 1.6.1 Cadastrar aplicações -------------------------- Caso o cliente deseje utilizar a autenticação com o **CPQD iD** em suas aplicações, é necessário cadastrá-las no Portal. Neste cadastro, são geradas informações que serão utilizadas na configuração do CPQD iD nessas aplicações. Para isso, o usuário do **CPQD iD | Empresas** deverá acessar a opção “Aplicações” e clicar sobre o botão “Nova”. .. figure:: /_images/cpqdidUseMyApplications.png :alt: text :align: center :width: 75% Menu "Aplicações" Então a tela para o cadastro de uma aplicação será apresentada e o usuário deverá preencher o nome da aplicação e o ID da definição de credencial. **Informação:** O ID da definição de credencial deverá ser de autenticação e a lista com os IDs definidos pelo usuário está disponível no menu "Credenciais". .. figure:: /_images/cpqdidUseNewApplication.png :alt: text :align: center :width: 75% Cadastro de Nova Aplicação Para que o cadastro da nova aplicação seja concluído, é necessário clicar no botão "Salvar" e os seguintes dados serão gerados: .. figure:: /_images/cpqdidUseNewApplicationGenerated.png :alt: text :align: center :width: 75% Dados da Aplicação - Client Secret; - Client iD; Ambas as informações serão utilizadas para a configuração da aplicação, de acordo com o **guia rápido**. Além das informações geradas, o usuário poderá preencher quais são os endereços de redirecionamento quando houver a autenticação por meio do QR Code. Finalizado o cadastro, o usuário poderá prosseguir com o próximo passo para configurar o **CPQD iD** na aplicação cadastrada. 1.6.2 Configurar o CPQD iD na aplicação --------------------------------------- Após o registro da aplicação no Portal CPQD iD | Empresas, o usuário poderá acessar o menu **guia rápido**, disponível no Portal e seguir os passos necessários para configuração em sua aplicação. Neste roteiro, além dos passos necessários, também é mencionado o momento de utilizar as informações **Client secret** e **Client id** na implementação do botão de **login com o CPQD iD**. Finalizada a configuração, será o momento de validar se o fluxo de autenticação está ocorrendo corretamente. Sendo assim, para validar deve checar os seguintes passos: - Botão de “Login com o CPQD iD” disponível na aplicação; - Ao clicar no botão “Login com o CPQD iD”, uma nova página será visualizada do provedor de identidade com o QR Code disponível, informando o nome da aplicação e os dados que serão fornecidos pelo usuário do SOU iD, caso ele realize a leitura do QR Code; - Com o aplicativo SOU iD em mãos e com a credencial de identidade básica disponível na carteira, o usuário poderá realizar a leitura do QR Code para se autenticar; - Para que a autenticação aconteça, é importante ressaltar que o usuário precisa já estar cadastrado na aplicação que ele deseja se autenticar, pois no momento, ainda não fazemos cadastro por meio do QR Code; - Realizada a leitura do QR Code e exibindo a mensagem de sucesso no aplicativo, o provedor de identidade fará o redirecionamento para a página cadastrada no portal, concluindo o processo de autenticação. Caso ocorra falha neste processo, os passos deverão ser revisados até que ocorra sucesso neste fluxo. 1.7. Fluxo para revogação de credenciais com o CPQD iD ====================================================== Para que uma credencial seja revogada, é necessário que os passos :ref:`passo-1.4.3` e :ref:`passo-1.4.4` tenham sido realizados e que no passo :ref:`passo-2.3.2` o usuário tenha aceitado a oferta de credencial. .. _passo-1.7.1: 1.7.1 Consultar registro de troca de credencial entre agente emissor e usuário ------------------------------------------------------------------------------ O fluxo de revogação faz sentido somente para credenciais ativas. Na aplicação o status utilizado é o de **credential_acked**. Para verificar o status de uma credencial será necessário utilizar nosso microsserviço (API). - No postman, insomnia ou qualquer outra ferramenta para gerar requisições HTTP de sua preferência, é possível recuperar uma credencial e verificar seu status da seguinte forma: **Tipo**: GET **URL**: \https://blockchain.cpqd.com.br/hmcpqdid/agent-issuer-com/issue-credential/records/{cred_ex_id} .. list-table:: :widths: 15 30 :header-rows: 1 * - Parâmetro - Descrição * - cred_ex_id - Identificador de registro de troca de credencial na emissão da credencial **Header**: .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Chave - Valor - Descrição * - Content-Type - application/json - Cabeçalho para o tipo de conteúdo a ser trafegado (no caso o tipo é JSON) * - Authorization - Bearer {token} - Token do agente emissor para autenticar as solicitações (passo :ref:`passo-1.3`) * - ApiKey - {API Key} - API Key para autenticação disponibilizada pelo time CPQD iD a você. **Body**: .. code-block:: json {} Essa requisição retornará um conteúdo parecido com o exemplo abaixo: .. code-block:: json { "auto_issue": false, "auto_offer": false, "auto_remove": false, "connection_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "created_at": "2022-12-31 23:59:59Z", "credential": {}, "credential_definition_id": "WgWxqztrNooG92RXvxSTWv:3:CL:20:tag", "credential_exchange_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "credential_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "credential_offer": {}, "credential_offer_dict": {}, "credential_proposal_dict": {}, "credential_request": {}, "credential_request_metadata": {}, "error_msg": "Credential definition identifier is not set in proposal", "initiator": "self", "parent_thread_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "raw_credential": {}, "revoc_reg_id": "string", "revocation_id": "string", "role": "issuer", "schema_id": "WgWxqztrNooG92RXvxSTWv:2:schema_name:1.0", "state": "credential_acked", "thread_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "trace": true, "updated_at": "2022-12-31 23:59:59Z" } .. _passo-1.7.2: 1.7.2 Revogação de credencial ----------------------------- Para revogar uma credencial, será necessário utilizar nosso microsserviço (API). - No postman, insomnia ou qualquer outra ferramenta para gerar requisições HTTP de sua preferência, é possível revogar uma credencial da seguinte forma: **Tipo**: POST **URL**: \https://blockchain.cpqd.com.br/hmcpqdid/agent-issuer-com/revocation/revoke **Header**: .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Chave - Valor - Descrição * - Content-Type - application/json - Cabeçalho para o tipo de conteúdo a ser trafegado (no caso o tipo é JSON) * - Authorization - Bearer {token} - Token do agente emissor para autenticar as solicitações (passo :ref:`passo-1.3`) * - ApiKey - {API Key} - API Key para autenticação disponibilizada pelo time CPQD iD a você. **Body**: .. code-block:: javascript { "comment": "xxxxxxxxxxxxxxx", //Insira um comentário para a revoga da credencial "connection_id": "XXXXXXXXXXXXXXXXXXXXXX", //Informe o identificador da conexão com o usuário que deseja revogar a credencial "cred_ex_id": "XXXXXXXXXXXXXXXXXXXXXXXXX", //Informe o identificador de registro de troca de credencial "notify": true, "publish": true } Essa requisição retornará um conteúdo parecido com o exemplo abaixo: .. code-block:: json {} .. _passo-1.7.3: 1.7.3 Consultar registro de revoga de credenciais ------------------------------------------------- Toda revogação é registrada e pode ser consultada, basta utilizar nosso microsserviço (API). - No postman, insomnia ou qualquer outra ferramenta para gerar requisições HTTP de sua preferência, é possível recuperar uma revogação da seguinte forma: **Tipo**: GET **URL**: \https://blockchain.cpqd.com.br/hmcpqdid/agent-issuer-com/revocation/credential-record **Query Params**: .. list-table:: :widths: 15 30 :header-rows: 1 * - Parâmetro - Descrição * - cred_ex_id - Identificador de registro de troca de credencial na emissão da credencial **Header**: .. list-table:: :widths: 15 10 30 :header-rows: 1 * - Chave - Valor - Descrição * - Content-Type - application/json - Cabeçalho para o tipo de conteúdo a ser trafegado (no caso o tipo é JSON) * - Authorization - Bearer {token} - Token do agente emissor para autenticar as solicitações (passo :ref:`passo-1.3`) * - ApiKey - {API Key} - API Key para autenticação disponibilizada pelo time CPQD iD a você. **Body**: .. code-block:: json {} Essa requisição retornará um conteúdo parecido com o exemplo abaixo: .. code-block:: json { "result": { "created_at": "2021-12-31 23:59:59Z", "cred_def_id": "WgWxqztrNooG92RXvxSTWv:3:CL:20:tag", "cred_ex_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "cred_rev_id": "12345", "record_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "rev_reg_id": "WgWxqztrNooG92RXvxSTWv:4:WgWxqztrNooG92RXvxSTWv:3:CL:20:tag:CL_ACCUM:0", "state": "issued", "updated_at": "2021-12-31 23:59:59Z" } } 2. Aplicativo SOU iD ******************** A carteira digital SOU iD tem por finalidade armazenar todas as credenciais verificáveis do usuário, para que ele possa, de modo consensual e por meio de uma conexão segura com o destinatário, compartilhá-las com agentes verificadores em processos de validação de dados. O SOU iD pode também ser utilizado para efetuar autenticação em aplicações parceiras, por meio das credenciais disponíveis. 2.1 Instalação do aplicativo ============================ O primeiro passo para utilizar a carteira SOU iD é realizar a instalação do aplicativo no smartphone. Para isso, é necessário baixá-lo por meio das lojas de aplicativos: .. raw:: html É importante ter um smartphone com sistema operacional Android ou iOS e com acesso à internet. A conexão com a internet não é necessária em todos os passos do aplicativo, mas quando for o caso, se o dispositivo estiver desconectado, será apresentada uma mensagem de falta de conexão. .. centered:: |imgApp1| |imgApp2| .. |imgApp1| image:: /_images/cpqdidUseAppSplashScreen.png :width: 25% :height: 350 .. |imgApp2| image:: /_images/cpqdidUseAppDigital.jpg :width: 25% :height: 350 .. centered:: |imgApp3| |imgApp4| .. |imgApp3| image:: /_images/cpqdidUseAppAuthentication.jpg :width: 25% :height: 350 .. |imgApp4| image:: /_images/cpqdidUseAppDigitalCredentials.jpg :width: 25% :height: 350 2.2 Onboarding no aplicativo ============================ Após a instalação do aplicativo, o usuário realizará o seu primeiro acesso, conforme segue: * Ler e concordar ou não com a política de privacidade e com os termos de uso do SOU iD (no caso de discordância, o usuário não conseguirá acessar o aplicativo); * Seguir as regras para criação de um PIN de seis dígitos para a segurança da carteira; .. centered:: |imgApp5| |imgApp6| .. |imgApp5| image:: /_images/cpqdidUseAppTermsAndPrivacy.jpg :width: 25% :height: 350 .. |imgApp6| image:: /_images/cpqdidUseAppNewPassword.png :width: 25% :height: 350 * Optar ou não pelo uso dos recursos de biometria do smartphone para acessar o aplicativo. .. centered:: |imgApp7| |imgApp8| .. |imgApp7| image:: /_images/cpqdidUseAppBiometric.jpg :width: 25% :height: 350 .. |imgApp8| image:: /_images/cpqdidUseAppSplashScreen.png :width: 25% :height: 350 2.3 Fluxo de emissão de credenciais =================================== Com a carteira pronta, o usuário do SOU iD poderá então usufruir das funcionalidades disponíveis. Para obter e armazenar múltiplas credenciais no SOU iD, o usuário precisa conectar-se e receber ofertas de credenciais de agentes emissores. .. _passo-2.3.2: 2.3.1 Conexão e obtenção de credenciais --------------------------------------- A conexão e o recebimento de uma oferta de credencial deve ser realizado por meio da leitura do QR Code disponibilizado pela empresa emissora com a qual o usuário deseja se relacionar. Com o aplicativo SOU iD no seu smartphone, o usuário vai precisar: * Acionar a opção **"Ler QR Code"**, na página principal; * Permitir o uso da câmera do smartphone; .. centered:: |imgApp9| |imgApp10| |imgApp11| .. |imgApp9| image:: /_images/cpqdidUseAppCredentialsNotification.jpg :width: 25% :height: 350 .. |imgApp10| image:: /_images/cpqdidUseAppGrantPermissionCamera.png :width: 25% :height: 350 .. |imgApp11| image:: /_images/cpqdidUseAppGrantPermissionImages2.jpg :width: 25% :height: 350 * Fazer a leitura do QR Code enviado pelo agente emissor; * Visualizar a oferta de credencial encaminhada por meio de uma conexão segura estabelecida com o agente emissor; * Conferir as informações (atributos da credencial); * Acionar **"Aceitar oferta"** ou **“Recusar”** a oferta de credencial. .. centered:: |imgApp12| |imgApp13| .. |imgApp12| image:: /_images/cpqdidUseAppReadQrcode.jpg :width: 25% :height: 350 .. |imgApp13| image:: /_images/cpqdidUseAppOffer.png :width: 25% :height: 350 Caso aceite, uma mensagem de confirmação aparecerá, devendo o usuário aguardar o recebimento e adição da credencial à sua carteira, podendo então visualizá-la na tela “Credenciais” do SOU iD. .. centered:: |imgApp14| |imgApp15| |imgApp16| .. |imgApp14| image:: /_images/cpqdidUseAppCredentialOnWay.jpg :width: 25% :height: 350 .. |imgApp15| image:: /_images/cpqdidUseAppCredentialAddsOnWallet.jpg :width: 25% :height: 350 .. |imgApp16| image:: /_images/cpqdidUseAppCredentialAdded.png :width: 25% :height: 350 Caso recuse, aparecerá uma mensagem para confirmar a recusa de oferta de credencial. .. centered:: |imgApp17| .. |imgApp17| image:: /_images/cpqdidUseAppCredentialRefuse.png :width: 25% :height: 350 O usuário poderá visualizar a conexão com o agente emissor no menu **Configurações > Conexões.** .. centered:: |imgApp27| .. |imgApp27| image:: /_images/cpqdidUseAppConnections.png :width: 25% :height: 350 É possível remover credenciais e conexões da carteira, acionando o botão **“Remover da carteira”**, disponível em ambas as opções. Uma conexão somente pode ser removida se não houver credenciais a ela associadas. Com a credencial emitida, o usuário poderá utilizá-la em processos de verificação ou de autenticação, caso a credencial possa ser utilizada para este fim. 2.4 Fluxo de compartilhamento de dados ====================================== Para compartilhar os dados das credenciais existentes na carteira, é necessário o consentimento do usuário. Para isso, ele deve aceitar o pedido de prova que será enviado via notificação. Uma vez aceito, os dados solicitados serão compartilhados com o agente. 2.4.1 Aceite ou recusa do compartilhamento de dados --------------------------------------------------- Quando um agente cria um pedido de prova, o usuário para quem o pedido foi gerado recebe uma notificação denominada “Pedido de prova”, devendo: * Clicar sobre a notificação para visualizar os dados que estão sendo solicitados no pedido; * Acionar **“Compartilhar dados”** ou **“Recusar”**. Caso aceite, uma mensagem de sucesso aparecerá após o compartilhamento dos dados da credencial com o agente e a notificação é descartada. .. centered:: |imgApp19| |imgApp20| |imgApp21| .. |imgApp19| image:: /_images/cpqdidUseAppSharingFlowNotificationRequestProof.jpg :width: 25% :height: 350 .. |imgApp20| image:: /_images/cpqdidUseAppSharingFlowRequestProof.png :width: 25% :height: 350 .. |imgApp21| image:: /_images/cpqdidUseAppSharingFlowDetails.jpg :width: 25% :height: 350 Caso recuse, uma mensagem de confirmação aparecerá e a notificação, juntamente com o pedido de prova, são descartados. .. centered:: |imgApp22| .. |imgApp22| image:: /_images/cpqdidUseAppTestRequest.png :width: 25% :height: 350 2.5 Fluxo de autenticação ========================= A autenticação utilizando aplicativo SOU iD em plataformas parceiras é dada por meio de compartilhamento de dados de uma credencial de autenticação solicitada por um pedido de prova. 2.5.1 Autenticação com a leitura do QR CODE -------------------------------------------- Após a emissão da credencial de autenticação, o aplicativo estará preparado para realizar a autenticação por meio da leitura do QR Code. Ao acessar a página do parceiro onde deseja se autenticar, o usuário vai: * Acionar o botão de **“Login com o CPQD iD”** para exibição da página do QR Code; * Acionar o botão **“Ler QR Code”** em seu aplicativo SOU iD e fazer a leitura; * Neste momento ocorre a verificação da credencial e um pedido de prova será enviado. **OBS.:** O envio ocorre via notificação, porém o pedido de prova abre automaticamente. O usuário poderá visualizar a notificação por meio do botão “home”. * Visualizar os dados de autenticação que estão sendo pedidos; * Acionar **“Compartilhar dados”** ou **“Recusar”**. Uma vez aceito, os dados solicitados serão compartilhados. Se o processo for concluído com sucesso, o provedor de identidade recebe a autorização da autenticação e o usuário visualiza uma mensagem de sucesso. O redirecionamento ocorrerá em instantes, bastando o usuário acionar o botão **"Voltar para home"** para continuar utilizando o aplicativo. .. centered:: |imgApp24| |imgApp25| |imgApp26| .. |imgApp24| image:: /_images/cpqdidUseAppReadQrcode.jpg :width: 25% :height: 350 .. |imgApp25| image:: /_images/cpqdidUseAppSharingFlowRequestProof.png :width: 25% :height: 350 .. |imgApp26| image:: /_images/cpqdidUseAppSharingFlowDetails.jpg :width: 25% :height: 350 .. _formulário de cadastro: https://blockchain.cpqd.com.br/hmcpqdid-portal-auth/realms/cpqd-portal/login-actions/registration?client_id=cpqd-portal&tab_id=m2Jh945OItM .. _QR Code Generator: https://br.qr-code-generator.com/ .. toctree:: :maxdepth: 1 cpqdidCreateWebhook