Configurar aplicação client com o Cerberus

Observações:

Importante: Nos exemplos foi usado localhost isso deverá ser alterado para a url do ambiente de testes (Equipe TCE será responsável por enviar as informações do ambiente de testes);

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 lib cerberus-client em uma api Java

1. Adicionamos também uma chave pública, ela está localizada em src/main/resources/certs/public.txt, essa chave é necessária para o Cerberus validar o client;
2. Configurando o arquivo properties
   1. Adicionamos a configuração para a url do cerberus, cerberus.url = http://localhost:9999 (Local onde a aplicação Cerberus está sendo executada);

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;
   
   

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: registry=http://repo.tce.pb/repository/npm-group (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, caso ocorra algum erro com a versão instalada, poderá ser usada a versão "@auth0/angular-jwt": "^2.0.0";
   
   
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
   
   
   
   
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:
      

      

       

      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:

      
      

   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: 
     
     
     Ao concluir essas configurações e executar o projeto, se tudo deu certo, você deverá ser redirecionado para tela de login do Cerberus;
     
     
     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`;