Ir para o conteúdo principal

Configurar aplicação client com o Cerberus

Observações:

Importante: Será disponibilizado um ambiente para os testes (Equipe TCE será responsável por enviar as informações necessárias);

1 - Para realizar os testes descritos nessa documentação será necessário está conectado à uma vpn;

2 - A equipe TCE criará uma client para que seja possível realizar os testes;

  1. Para configurar a api para usar o Cerberus será necessário um certificado;
  2. Foi criada a lib ngx-cerberus para a aplicação front;
Configurando o uso da chave pública na API

Obs: É indispensável essa validação para garantir que foi o token foi gerado pelo Cerberus

  1. Essa chave pública pode ser armazenada dentro de um arquivo de configuração da API, como por exemplo: src/main/resources/certs/public.txt, essa chave é necessária para validar o token gerado. 
  2. A chave pública também pode ser consultada através de um endpoint disponibilizado no Cerberus, exemplo: http://10.10.5.83:9999/.keys/jwks.json.

Adicionamos a configuração da chave pública, cert.path = certs_dev/public.txt

Exemplo da configuração de validação da publicKey em Scala
  1. Esse certificado é obrigatório, ele será entregue pela equipe TCE;
  2. Esse certificado pode ser armazenado em um arquivo de configuração dentro da API. Ele será usado para validação da assinatura do token.
  3. Para validar o certificado será necessário que na api Scala tem a validação se o certificado realmente é válido;
  4. Exemplo em Scala que como é feita a validação;

    exemplo_public_key.png
Obs: Visando facilitar a integração da aplicação angular com o cerberus desenvolvemos a lib ngx-cerberus
Configurando o uso da lib ngx-cerberus em uma aplicação angular

Essa lib é responsável por fazer o gerenciamento do usuário na aplicação;

  1. É necessário instalar a lib ngx-cerberus, para instalar essa lib é necessário ter na raiz do projeto um arquivo .npmrc com a seguinte configuração:
    @tcepb:registry=https://gitlab.tce.pb.gov.br/api/v4/projects/366/packages/npm/
    //gitlab.tce.pb.gov.br/api/v4/projects/366/packages/npm/:_authToken=TOKEN
     (para ter acesso ao repositório), após a criação desse arquivo, executar o seguinte comando npm install @tcepb/[email protected];
    Importante: A lib ngx-cerberus utiliza algumas outras dependências, dentre elas, é utilizada a @auth0/angular-jwt;

  2. Configurando o arquivo environment.ts
    1. Será necessário adicionar as configuracões da url da aplicação Cerberus, o clientID, o clientSecret; (Os valores para essas informações serão passados pela equipe do TCE);
    Exemplo do arquivo environment.ts

    exemplo_arquivo_environment.png

  3. Configurando os parâmetros que serão necessários para o NgxCerberus
    1. No arquivo app.module.ts será necessário realizar as configurações para o uso da lib ngx-cerberus;

    2. import  HTTP_INTERCEPTORS, JwtInterceptor, JwtModule, getToken, NgxCerberusHttpInterceptor, NgxCerberusModule, NgxCerberusService , environment(no exemplo configuramos algumas variáveis necessárias para JwtModule  nesse arquivo );

    3.  

      Exemplo das importações: 

      import { HTTP_INTERCEPTORS, HttpClientModule } from '@angular/common/http';
      import { JwtInterceptor, JwtModule } from '@auth0/angular-jwt';
      import { environment } from 'src/environments/environment';

      import { getToken, NgxCerberusHttpInterceptor, NgxCerberusModule, NgxCerberusService } from '@tcepb/ngx-cerberus';




    4. Configurando os parâmetros necessários para o módulo JwtModule; Será usado o .forRoot método de JwtModule para fornecer um objeto de configuração com os seguintes atributos:
      Exemplo:

      exemplo_app_modules.png

       

      Será necessário informar um objeto de configuração:

      • tokenGetter: esta função é usada para personalizar como JwtModule e obter o token de acesso JWT do armazenamento local.
      • whiteListedDomains: nesta matriz, você pode adicionar qualquer domínio que tenha permissão para receber o JWT como APIs públicas.
      • blackListedRoutes: nesta matriz, você pode adicionar rotas que não têm permissão para receber o token JWT.

    5. Configurando o objeto necessário para o módulo NgxCerberusModule:
      Será necessário informar os seguintes valores para o objeto: clientID, clientSecret, providerURL (essas informações serão passadas pela equipe TCE) ;

      Exemplo:

      exemplo_config_ngx_cerberus_no_module.png

    6. Adicionar ao array de imports o módulo JwtModule, NgxCerberusModule; 


    • Adicionar ao array de providers o HTTP_INTERCEPTORS utilizando o JwtInterceptor, NgxCerberusHttpInterceptor e o NgxCerberusService;
      Exemplo: 
      exemplo_declarations_module.png

      Ao concluir essas configurações e executar o projeto, se tudo deu certo, você deverá ser redirecionado para tela de login do Cerberus;

      tela_login_cerberus.png
      Repositório de exemplo de uma aplicação angular utilizando a lib ngx-cerberus: xxxxxxxx

      Integrando um aplicativo mobile ao Cerberus

      Realizando a requisição para obter um code


    • Observação: os dados necessários como endpoint para obtenção de code, token, clientId, clientSecret, usuário e senha de testes deverão ser passados pela equipe de desenvolvedores do tce.

      Para obter um Authorization code do Cerberus será necessário realizar uma requisição para o endpoint http://10.10.5.83:9999/oauth/authorize, essa requisição precisa ser apenas um redirect para esse enpoint;

      Exemplo da requisição: 

      `http://10.10.5.83:9999/oauth/authorize?response_type=code&client_id=appCarteiraFuncional&redirect_uri=http://127.0.0.1:8100`, essa requisição irá abrir a tela de login do Cerberus com as informações do client que está sendo passado como parâmetro;

      Após efetuar o login no Cerberus será retornado juntamente com a url de retorno(sua url) o code. Com o code de acesso agora é possível obter um token jwt; 

      Trocando o code recebido por um token jwt

      Para obter o token jwt será necessário enviar uma requisição do tipo POST para o Cerberus no endpoint http://10.10.5.83:9999/oauth/token informando os parâmetros necessários;

      Parâmetros que deverão ser passados: grant_type(do tipo authorization_code), client_id(fornecido pela equipe do tce), code(recebido na requisição para o obter um code), redirect_uri(sua url que receberá o retorno do Cerberus);
      Exemplo da requisição: 

      const params = new HttpParams()
      .set("grant_type", "authorization_code")
      .set("client_id", environment.clientId)
      .set("code", code)
      .set("redirect_uri", "http://127.0.0.1:8100");

      const headers = new HttpHeaders()
      .set("Content-type", "application/json; charset=utf-8")
      .set(
      "Authorization",
      "Basic " + btoa(environment.clientId + ":" + environment.clientSecret)
      );

      `http://10.10.5.83:9999/oauth/token?grant_type=authorization_code&client_id=appCarteiraFuncional&code=CODE_RECEBIDO_AO_EFETUAR_LOGIN_NO_CERBERUS&redirect_uri=http://127.0.0.1:8100`;

Voltar ao topo