Este guia tem como objetivo auxiliar desenvolvedores no processo de integração da sua aplicação com o Portal de Serviços da BRy, provendo acesso aos dados de usuários do Portal, bem como derivados desses dados, como informações de conta.
Premissas
Para o sucesso do processo de integração, este guia partirá das seguintes premissas:
A versão do Java utilizada (no projeto a ser integrado) deve ser uma variante da versão 1.7 ou superior.
A API do Portal utiliza a versão 1.5.2.2 da biblioteca BRyX509. Esteja atento para possíveis conflitos de versão.
A aplicação deve estar devidamente cadastrada no Portal da BRy. Se a sua aplicação ainda não foi cadastrada, siga os passos descritos em: Cadastrando uma Aplicação
Você deve possuir um Token que identifique sua aplicação (o Token é obtido após o cadastro).
As chamadas devem ser realizadas para a porta 543, que é a porta que exige certificado na comunicação - e, portanto, consegue atingir o serviço.
Cadastrando uma Aplicação
Para cadastrar sua aplicação no Portal:
Autentique-se no portal como Pessoa Jurídica.
No menu de conta, selecione a opção "Minhas Aplicações".
Forneça os dados da sua aplicação, e clique em 'inserir'.
Pronto! Sua aplicação está cadastrada e pode integrar-se ao BRy Cloud, através do Portal de Serviços.
Para isso, você deve emitir um Token que dará acesso à API de integração. Faça isso selecionando a sua Aplicação e clicando em "Emitir Token". Este token pode ser revogado a Qualquer momento.
Fique atento: o cadastro da sua aplicação poderá falhar nos casos de uma chave que já esteja sendo utilizada por outra aplicação.
A API do Portal da BRy provê um conjunto de Web Services REST para que você, parceiro da BRy, tenha acesso aos serviços disponibilizados e acesso ao gerenciamento de identidade do BRy Cloud.
Preparando o Cliente
Antes de realizar qualquer uma das chamadas, é fundamental que o ClienteREST seja configurado para utilizar um certificado para comunicação.
Isso pode ser feito informando um arquivo de extensão PFX ou P12 e fornecendo a senha para importação do certificado da aplicação.
Junto com a biblioteca da API já está um certificado. No entanto, recomendamos emitir um certificado para uso da aplicação, preiodicamente, pois os certificados possuem um prazo de validade limitado.
A inicialização pode ser feita com um InputStream:
//...
ClienteREST.getInstance(new ConfiguracaoCertificadoClientePadrao(MinhaClasse.class.getClassLoader().getResourceAsStream("certificado.p12"), "senhaDoCertificado"));
// uma chamada com ClienteREST.getInstance(null) fará com que o certificado embarcado com a biblioteca seja utilizado.
//...
Ou informando-se o caminho do arquivo (PFX ou P12) no sistema de arquivos:
//...
ClienteREST.getInstance(new ConfiguracaoCertificadoClientePadrao("/diretorio/do/certificado/certificado.p12", "senhaDoCertificado"));
// uma chamada com ClienteREST.getInstance(null) fará com que o certificado embarcado com a biblioteca seja utilizado.
//...
A partir disso, as chamadas subsequentes serão realizadas com a configuração fornecida.
Uma nova chamada ao método getInstance informando uma nova configuração fará com
que as chamadas passem a utilizar as novas configurações, descartando quaisquer configurações anteriores.
Outro detalhe importante, é que você possui a opção de implementar a interface br.com.bry.portal.api.config.IConfiguracaoCertificadoCliente,
caso deseje acrescentar comportamentos à classe que armazena as configurações de certificado.
Solicitando uma URL de Autorização
Para que um usuário autorize a Aplicação a realizar requisições em seu nome, a Aplicação deve solicitar uma URL de Autorização, ao Portal, e exibir esta URL no navegador, para que o Usuário se identifique. Além da URL, este serviço retorna um identificador de contexto de autorização, que servirá para a obtenção do token.
ATENÇÃO: O prazo para concluir o processo de autenticação é de 60 minutos, por padrão (podendo ser alterado por um administrador). Se o prazo de autorização é importante para o seu procedimento, consulte um administrador para mais informações.
//...
ParametrosComunicacaoPadrao parametrosComunicacaoSemUsuario = new ParametrosComunicacaoPadrao("https://dominio.do.portal:543/", "seuToken");
RespostaPortalVO<UrlAutorizacaoTerceiroVO> respostaUrlAutorizacao = ClienteREST.getCurrentInstance().solicitarUrlAutorizacao(parametrosComunicacaoSemUsuario, "computador-pessoal-do-usuario");
// O segundo argumento (String) deve ser o nome/identificador do dispositivo através do qual o token está sendo emitido
//...
Página que deve ser exibida, após a autenticação do usuário:
Há algumas exceções que podem ser lançadas nas chamadas:
caso algum parâmetro obrigatório não tenha sido preenchido.
quando há algum erro no processamento por parte do servidor. Para maiores detalhes das circunstâncias
que ocasionaram o problema de processamento, um objeto com.sun.jersey.api.client.ClientResponse é disponibilizado dentro da exceção (por exemplo, se você
deseja saber qual o status HTTP da requisição gerada pela chamada).
quando a chamada não foi autorizada pelo servidor. Sempre está relacionado a um Status HTTP 403.
As situações mais comuns são:
O certificado utilizado na requisição é inválido (não faz parte da cadeia da BRy / está vencido / foi revogado)
O Token fornecido na chamada é inválido (não existe / foi revogado / está vencido)
A aplicação ou o usuário identificado pelo Token utilizado não possuem privilégios para realizar a chamada.
quando a chamada não foi autorizada pelo servidor devido ao uso de um token expirado.
Neste caso, um token de renovação de autorização é emitido e armazenado em PortalTokenExpiradoException.getTokenRenovacao().
Esta exceção não ocorre nos casos em que o token não é informado. Mais detalhes da renovação de Token serão abordados posteriormente.
Recuperando o Token de Autorização
Em posse do Identificador de Contexto de Autorização obtido no serviço de Solicitar URL de Autorização, o serviço de Recuperar Token deve ser chamado, de forma assíncrona, para se obter o Token de autorização do usuário.
Fica a critério da aplicação a periodicidade com que este serviço será chamado, visto que o Usuário possui até o fim do dia para autorizar a Aplicação, momento em que o contexto de autorização expira (é descartado).
Em poucas palavras, este serviço só retornará um Token de Autorização se o Usuário autenticou-se com sucesso no Portal e autorizou a Aplicação.
//...
// objeto respostaUrlAutorizacao foi obtido na seção anterior
// objeto parametrosComunicacaoSemUsuario foi obtido na seção anterior
UrlAutorizacaoTerceiroVO urlAutorizacao = respostaUrlAutorizacao.getEntidades().get(0);
RespostaPortalVO<StatusAutorizacaoPortalVO> respostaRecuperarToken = ClienteREST.getCurrentInstance().recuperarTokenAutorizacao(parametrosComunicacaoSemUsuario, urlAutorizacao.getIdContextoAutorizacao());
//O token de autorização ficará armazenado na seguinte propriedade:
String tokenAutorizacao = statusAutorizacao.getToken();
//...
Um Token expirou! O que fazer?
Todo Token possui um prazo de validade limitado. Após o fim do prazo, a primeira chamada de serviço realizada após o
vencimento gerará uma exceção: br.com.bry.portal.api.excecoes.PortalTokenExpiradoException.
Quando isso acontecer, um Token de Renovação será gerado e estará acessível em br.com.bry.portal.api.excecoes.PortalTokenExpiradoException.getTokenRenovacao().
O Token de Renovação deve ser utilizado, uma única vez, para que um novo Token seja gerado para o usuário, sem que seja necessária uma nova prova de credenciais:
//...
ParametrosComunicacaoPadrao parametrosComunicacao = new ParametrosComunicacaoPadrao("https://dominio.portal:543/", "umToken");
try {
ClienteREST.getCurrentInstance().recuperarUsuarioDaSessao(parametrosComunicacao, false, false);
} catch (PortalTokenExpiradoException e) {
String tokenRenovacao = e.getTokenRenovacao();
RespostaPortalVO<StatusAutorizacaoPortalVO> respostaRenovacao = ClienteREST.getCurrentInstance().renovarAutorizacao(new ParametrosRenovacaoComunicacaoPadrao("https://dominio.portal:543/", tokenRenovacao));
if (respostaRenovacao.isOk()) {
String novoToken = respostaRenovacao.getEntidades().get(0).getToken();
// ... Tratamento para atualização do valor do Token ...
}
}
//...
A partir desse ponto, fica disponibilizado o novo Token, identificando o mesmo usuário e sem que seja necessária uma nova prova de credenciais.
Os Tokens de renovação possuem uma validade mais curta e são descartados assim que vencem, ou assim que são utilizados na renovação (para impedir
o uso repetido).
Serviços Disponíveis
Abaixo, uma relação dos serviços disponibilizados pela API, com uma breve descrição, junto de um link para o Javadoc:
Serviço
Descrição
Exige Token?
Links
Solicitar URL de Autorização
Recupera uma URL que deve ser exibida no navegador Web, para que o usuário autentique-se e autorize a Aplicação a realizar requisições em seu nome. ATENÇÃO: O prazo para concluir o processo de autenticação é de 60 minutos, por padrão (podendo ser alterado por um administrador). Se o prazo de autorização é importante para o seu procedimento, consulte um administrador para mais informações.
Checa o status do processo de autorização de um usuário, retornando um Token de autorização, caso o Usuário tenha autorizado a Aplicação. Este serviço serve
para verificar, de forma assíncrona, se todos os passos, após a chamada do serviço anterior (Solicitar URL de Autorização), foram executados com sucesso pelo Usuário
que está sendo autorizado.
