Guia do Android SDK (herdado)
- Tópicos:
- Authentication
Introdução
Este documento descreve os workflows de direito que um aplicativo de nível superior do programador pode implementar por meio das APIs expostas pela biblioteca Android AccessEnabler.
A solução de direito de autenticação da Adobe Pass para o Android é dividida em dois domínios:
-
O domínio da interface do usuário — essa é a camada de aplicativo de nível superior que implementa a interface do usuário e usa os serviços fornecidos pela biblioteca do AccessEnabler para fornecer acesso ao conteúdo restrito.
-
O domínio AccessEnabler - é aqui que os workflows de direito são implementados no formato de:
- Chamadas de rede feitas aos servidores back-end da Adobe
- Regras de lógica de negócios relacionadas aos workflows de autenticação e autorização
- Gerenciamento de vários recursos e processamento do estado do fluxo de trabalho (como o cache de token)
O objetivo do domínio AccessEnabler é ocultar todas as complexidades dos workflows de direito e fornecer ao aplicativo de camada superior (por meio da biblioteca AccessEnabler) um conjunto de primitivos de direito simples com os quais você implementa os workflows de direito:
-
Defina a identidade do solicitante.
-
Verifique e obtenha autenticação em relação a um provedor de identidade específico.
-
Verifique e obtenha autorização para um recurso específico.
-
Fazer logoff.
A atividade de rede do AccessEnabler ocorre em um thread diferente, de modo que o thread de interface do usuário nunca é bloqueado. Como resultado, o canal de comunicação bidirecional entre os dois domínios de aplicativos deve seguir um padrão totalmente assíncrono:
- A camada de aplicativo da interface envia mensagens para o domínio AccessEnabler por meio das chamadas de API expostas pela biblioteca AccessEnabler.
- O AccessEnabler responde à camada da interface do usuário por meio dos métodos de retorno de chamada incluídos no protocolo AccessEnabler que a camada da interface do usuário registra na biblioteca AccessEnabler.
Fluxos de Direitos
A. Pré-requisitos
-
Crie suas funções de retorno de chamada:
-
Acionado por
setRequestor()
, retorna êxito ou falha.
Success indica que você pode continuar com chamadas de direito. -
Disparado por
getAuthentication()
somente se o usuário não tiver selecionado um provedor (MVPD) e ainda não estiver autenticado.
O parâmetromvpds
é uma matriz de provedores disponíveis para o usuário. -
"setAuthenticationStatus(status, errorcode)"
Disparado por
checkAuthentication()
toda vez.
Disparado porgetAuthentication()
somente se o usuário já estiver autenticado e tiver selecionado um provedor.O status retornado é sucesso ou falha, o código de erro descreve o tipo da falha.
-
Disparado por
getAuthentication()
depois que o usuário seleciona uma MVPD. O parâmetrourl
fornece o local da página de logon do MVPD. -
"sendTrackingData(event, data)"
Disparado por
checkAuthentication(), getAuthentication(), checkAuthorization(), getAuthorization(), setSelectedProvider()
.
O parâmetroevent
indica qual evento de direito ocorreu; o parâmetrodata
é uma lista de valores relacionados ao evento. -
Acionado por
checkAuthorization()
egetAuthorization()
após uma autorização bem-sucedida para exibir um recurso.
O parâmetrotoken
é o token de mídia de vida curta; o parâmetroresource
é o conteúdo que o usuário está autorizado a exibir. -
"tokenRequestFailed(resource, code, description)"
Acionado por
checkAuthorization()
egetAuthorization()
após uma autorização sem êxito.
O parâmetroresource
é o conteúdo que o usuário estava tentando exibir; o parâmetrocode
é o código de erro que indica que tipo de falha ocorreu; o parâmetrodescription
descreve o erro associado ao código de erro. -
Disparado por
getSelectedProvider()
.
O parâmetromvpd
fornece informações sobre o provedor selecionado pelo usuário. -
setMetadataStatus(metadados, chave, argumentos)
Acionado por
getMetadata().
O parâmetrometadata
fornece os dados específicos solicitados; o parâmetrokey
é a chave usada na solicitaçãogetMetadata()
; e o parâmetroarguments
é o mesmo dicionário passado paragetMetadata()
. -
"preauthorizedResources(resources)"
Disparado por
checkPreauthorizedResources()
.
O parâmetroauthorizedResources
apresenta os recursos que o usuário está autorizado a exibir.
-
B. Fluxo de inicialização
-
Inicie o aplicativo de nível superior.
-
Iniciar autenticação do Adobe Pass
a. Chame
getInstance
para criar uma única instância do Adobe Pass Authentication AccessEnabler.- Dependência: Autenticação Adobe Pass Nativa
Biblioteca da Android (AccessEnabler)
b. Chame
setRequestor()
para estabelecer a identificação do Programador; transmita norequestorID
do Programador e (opcionalmente) uma matriz de pontos de extremidade de Autenticação Adobe Pass.-
Dependência: RequestorID de Autenticação Adobe Pass Válido
(Trabalhe com seu gerente de conta de autenticação da Adobe Pass para organizar isso.) -
Acionadores: retorno de chamada setRequestorComplete()
NOTANenhuma solicitação de direito pode ser concluída até que a identidade do solicitante seja totalmente estabelecida. Isso significa que, enquanto setRequestor() ainda estiver em execução, todas as solicitações de direitos subsequentes (por exemplo,checkAuthentication()
) serão bloqueadas.
Você tem duas opções de implementação: Depois que as informações de identificação do solicitante forem enviadas para o servidor back-end, a camada de aplicativo da interface poderá escolher uma das duas seguintes abordagens:
1. Aguarde o acionamento do retorno de chamadasetRequestorComplete()
(parte do delegado AccessEnabler). Essa opção fornece a maior certeza de quesetRequestor()
foi concluído, portanto, ela é recomendada para a maioria das implementações.
2. Continue sem aguardar o acionamento do retorno de chamadasetRequestorComplete()
e comece a emitir solicitações de direito. Essas chamadas (checkAuthentication, checkAuthorization, getAuthentication, getAuthorization, checkPreauthorizedResource, getMetadata, logout) são enfileiradas pela biblioteca AccessEnabler, que fará as chamadas de rede reais apóssetRequestor().
Essa opção poderá ser interrompida ocasionalmente se, por exemplo, a conexão de rede estiver instável. - Dependência: Autenticação Adobe Pass Nativa
-
Chame checkAuthentication() para verificar uma autenticação existente sem iniciar o fluxo de Autenticação completo. Se essa chamada for bem-sucedida, você poderá prosseguir diretamente para o Fluxo de autorização. Caso contrário, prossiga para o Fluxo de autenticação.
-
Dependência: uma chamada bem-sucedida para
setRequestor()
(essa dependência também se aplica a todas as chamadas subsequentes). -
Acionadores: retorno de chamada setAuthenticationStatus()
-
C. Fluxo de autenticação
-
Chame
getAuthentication()
para iniciar o fluxo de autenticação ou obter a confirmação de que o usuário já está autenticado.
Acionadores:- O retorno de chamada setAuthenticationStatus(), se o usuário já estiver autenticado. Nesse caso, prossiga diretamente para o Fluxo de Autorização.
- O retorno de chamada displayProviderDialog(), se o usuário ainda não estiver autenticado.
-
Apresentar ao usuário a lista de provedores enviada para
displayProviderDialog()
. -
Depois que o usuário selecionar um provedor, obtenha a URL da MVPD do usuário no retorno de chamada
navigateToUrl()
. Abra um WebView e direcione esse controle do WebView para o URL. -
Por meio do WebView instanciado na etapa anterior, o usuário acessa a página de logon do MVPD e insere credenciais de logon. Várias operações de redirecionamento ocorrem no WebView.
Observação: neste momento, o usuário tem a oportunidade de cancelar o fluxo de autenticação. Se isso ocorrer, a camada da interface do usuário será responsável por informar o AccessEnabler sobre esse evento, chamando
setSelectedProvider()
comnull
como parâmetro. Isso permite que o AccessEnabler limpe seu estado interno e redefina o Fluxo de autenticação. -
Após um logon bem-sucedido pelo usuário, a camada do aplicativo detecta o carregamento de um "URL de redirecionamento personalizado" (ou seja:
http://adobepass.android.app
). Na verdade, esse URL personalizado é um URL inválido que não se destina ao carregamento do WebView. É um sinal de que o Fluxo de Autenticação foi concluído e que o WebView precisa ser fechado. -
Feche o controle WebView e chame
getAuthenticationToken()
, que instrui o AccessEnabler a recuperar o token de autenticação do servidor back-end. -
[Opcional] Chame
checkPreauthorizedResources(resources)
para verificar quais recursos o usuário está autorizado a visualizar. O parâmetroresources
é uma matriz de recursos protegidos associada ao token de autenticação do usuário.
Acionadores: Retorno de chamada depreAuthorizedResources()
Ponto de execução: após a conclusão do fluxo de autenticação -
Se a autenticação tiver sido bem-sucedida, prossiga para o Fluxo de autorização.
D. Fluxo de autorização
-
Chame getAuthorization() para iniciar a autorização
fluxo.Dependência: ResourceID(s) válido(s) acordado(s) com a(s) MVPD(s).
Observação: ResourceIDs devem ser os mesmos usados em qualquer outro dispositivo ou plataforma e serão os mesmos em MVPDs.
-
Validar autenticação e autorização.
-
Se a chamada
getAuthorization()
tiver êxito: o usuário tem tokens AuthN e AuthZ válidos (o usuário é autenticado e autorizado a assistir à mídia solicitada). -
Se
getAuthorization()
falhar: examine a exceção lançada para determinar seu tipo (AuthN, AuthZ ou algo mais):- Se foi um erro de autenticação (AuthN), reinicie o fluxo de autenticação.
- Se foi um erro de autorização (AuthZ), o usuário não está autorizado a assistir à mídia solicitada, e algum tipo de mensagem de erro deve ser exibido para o usuário.
- Se houver algum outro tipo de erro (erro de conexão, erro de rede etc.), exiba uma mensagem de erro apropriada para o usuário.
-
-
Valide o token de mídia curta.
Use a biblioteca do Verificador de Token de Mídia de Autenticação do Adobe Pass para verificar o token de mídia de curta duração retornado da chamadagetAuthorization()
acima:- Se a validação for bem-sucedida: Reproduza a mídia solicitada para o usuário.
- Se a validação falhar: O token AuthZ era inválido, a solicitação de mídia deve ser recusada e uma mensagem de erro deve ser exibida ao usuário.
-
Retorne ao fluxo normal do aplicativo.
E. Fluxo de mídia de visualização
- O usuário seleciona a mídia a ser exibida.
- A mídia está protegida? Seu aplicativo verifica se a mídia selecionada está protegida:
- Se a mídia selecionada estiver protegida, o aplicativo iniciará o Fluxo de Autorização acima.
- Se a mídia selecionada não estiver protegida, reproduza a mídia para o usuário.
F. Fluxo de logout
-
Ligue para
logout()
para desconectar o usuário.
O AccessEnabler apaga todos os valores e tokens em cache para o MVPD atual para o solicitante atual e também para os solicitantes com Logon único. Depois de limpar o cache, o AccessEnabler faz uma chamada de servidor para limpar as sessões do lado do servidor. Como a chamada do servidor pode resultar em um redirecionamento SAML para o IdP (isso permite a limpeza da sessão no lado do IdP), essa chamada deve seguir todos os redirecionamentos. Por esse motivo, essa chamada deve ser tratada em um controle WebView.a. Seguindo o mesmo padrão do fluxo de trabalho de autenticação, o domínio AccessEnabler faz uma solicitação à camada de aplicativo da interface do usuário (por meio do retorno de chamada
navigateToUrl()
) para criar um controle WebView e instruir esse controle a carregar a URL do ponto de extremidade de logout no servidor back-end.b. Novamente, a interface do usuário deve monitorar a atividade do controle WebView e detectar o momento em que o controle, à medida que passa por vários redirecionamentos, carrega a URL personalizada do aplicativo (ou seja:
http://adobepass.android.app/
). Depois que esse evento ocorrer, a camada de aplicativo da interface do usuário fechará o WebView e o processo de logout será concluído.Observação: o fluxo de logout difere do fluxo de autenticação na medida em que o usuário não precisa interagir com o WebView de nenhuma maneira. A camada de aplicativo da interface do usuário usa uma WebView para verificar se todos os redirecionamentos estão sendo seguidos. Assim, é possível (e recomendado) tornar o controle do WebView invisível (ou seja, oculto) durante o processo de logout.
Fluxos de usuário para logon com vários MVPDs e logout
Aqui você tem um documento que descreve o comportamento ao usar vários MVPDs e o que está acontecendo quando o usuário faz logoff de um aplicativo.
O comportamento descrito está disponível ao usar o Android SDK versão >= 2.0.0.