![Diagrama da lógica do token
de autenticação](https://developer.android.com/static/images/training/oauth_dance.png?authuser=7&hl=pt-br)
Para acessar um serviço on-line com segurança, os usuários precisam se autenticar no serviço. Eles precisam fornecer um comprovante de identidade. Para um aplicativo que acessa um serviço de terceiros, o problema de segurança é ainda mais complicado. O usuário não só precisa de autenticação para acessar o serviço, como também o aplicativo precisa ter autorização para agir em nome do usuário.
A forma padrão do setor de lidar com autenticação para serviços de terceiros é o protocolo OAuth2. O OAuth2 oferece um valor único, chamado token de autenticação, que representa a identidade do usuário e a autorização do aplicativo para agir em nome dele. Esta lição mostra como se conectar a um servidor do Google compatível com o OAuth2. Os serviços do Google são usados como exemplo, mas as técnicas demonstradas funcionam em qualquer serviço que ofereça suporte ao protocolo OAuth2.
Usar o OAuth2 é bom para:
- Conseguir permissão do usuário para acessar um serviço on-line usando a conta dele.
- autenticar um serviço on-line em nome do usuário;
- lidar com erros de autenticação.
Coletar informações
Para começar a usar o OAuth2, você precisa conhecer alguns detalhes específicos da API sobre o serviço que está tentando acessar:
- O URL do serviço que você quer acessar.
- O escopo de autenticação, que é uma string que define o tipo específico de acesso solicitado pelo app. Por exemplo, o escopo de autenticação para acesso somente leitura ao Google Tarefas é
View your tasks
, enquanto o escopo de autenticação para acesso de leitura e gravação ao Google Tarefas éManage your tasks
. - Um ID e uma chave secreta do cliente, que são strings que identificam seu app para o serviço. Você precisa receber essas strings diretamente do proprietário do serviço. O Google tem um sistema de autoatendimento para receber IDs e secrets do cliente.
Solicitar a permissão de acesso à Internet
Para apps destinados ao Android 6.0 (nível 23 da API) e versões mais recentes, o
método getAuthToken()
não requer nenhuma permissão. No entanto, para
realizar operações no token, você precisa adicionar a permissão
INTERNET
ao arquivo de manifesto, conforme mostrado no snippet de código a seguir:
<manifest ... > <uses-permission android:name="android.permission.INTERNET" /> ... </manifest>
Solicitar um token de autenticação
Para receber o token, chame AccountManager.getAuthToken()
.
Cuidado : como algumas operações de conta podem envolver
a comunicação de rede, a maioria dos métodos
AccountManager
é assíncrono. Isso significa que, em vez de fazer todo o trabalho de autenticação
em uma única função, você precisa implementá-lo como uma série de callbacks.
O snippet a seguir mostra como trabalhar com uma série de callbacks para receber o token:
Kotlin
val am: AccountManager = AccountManager.get(this) val options = Bundle() am.getAuthToken( myAccount_, // Account retrieved using getAccountsByType() "Manage your tasks", // Auth scope options, // Authenticator-specific options this, // Your activity OnTokenAcquired(), // Callback called when a token is successfully acquired Handler(OnError()) // Callback called if an error occurs )
Java
AccountManager am = AccountManager.get(this); Bundle options = new Bundle(); am.getAuthToken( myAccount_, // Account retrieved using getAccountsByType() "Manage your tasks", // Auth scope options, // Authenticator-specific options this, // Your activity new OnTokenAcquired(), // Callback called when a token is successfully acquired new Handler(new OnError())); // Callback called if an error occurs
Neste exemplo, OnTokenAcquired
é uma classe que implementa
AccountManagerCallback
. AccountManager
chama
run()
em OnTokenAcquired
com um
AccountManagerFuture
que contém um Bundle
. Se
a chamada for bem-sucedida, o token estará dentro
do Bundle
.
Veja como conseguir o token do Bundle
:
Kotlin
private class OnTokenAcquired : AccountManagerCallback<Bundle> { override fun run(result: AccountManagerFuture<Bundle>) { // Get the result of the operation from the AccountManagerFuture. val bundle: Bundle = result.getResult() // The token is a named value in the bundle. The name of the value // is stored in the constant AccountManager.KEY_AUTHTOKEN. val token: String = bundle.getString(AccountManager.KEY_AUTHTOKEN) } }
Java
private class OnTokenAcquired implements AccountManagerCallback<Bundle> { @Override public void run(AccountManagerFuture<Bundle> result) { // Get the result of the operation from the AccountManagerFuture. Bundle bundle = result.getResult(); // The token is a named value in the bundle. The name of the value // is stored in the constant AccountManager.KEY_AUTHTOKEN. String token = bundle.getString(AccountManager.KEY_AUTHTOKEN); ... } }
Se tudo correr bem, o Bundle
conterá um token válido na chave KEY_AUTHTOKEN
e está tudo pronto.
Sua primeira solicitação de um token de autenticação pode falhar por vários motivos:
- Um erro no dispositivo ou na rede causado a falha do
AccountManager
. - O usuário decidiu não conceder ao seu app acesso à conta.
- As credenciais da conta armazenadas não são suficientes para ter acesso a ela.
- O token de autenticação armazenado em cache expirou.
Os aplicativos podem processar os dois primeiros casos de maneira trivial, geralmente apenas mostrando uma mensagem de erro ao usuário. Se a rede estiver inativa ou o usuário tiver decidido não conceder acesso, não haverá muito que seu aplicativo possa fazer a respeito. Os dois últimos casos são um pouco mais complicados, porque espera-se que aplicativos bem comportados processem essas falhas automaticamente.
O terceiro caso de falha, ter credenciais insuficientes, é comunicado pelo
Bundle
que você recebe no seu AccountManagerCallback
(OnTokenAcquired
do exemplo anterior). Se o Bundle
incluir
um Intent
na chave KEY_INTENT
,
o autenticador estará informando que precisa interagir diretamente com o usuário antes de poder
fornecer um token válido.
Pode haver muitas razões para o autenticador retornar um Intent
. Talvez seja a primeira vez que o usuário fez login nessa conta. Talvez a conta do usuário tenha expirado e ele precise fazer login novamente ou as credenciais armazenadas estejam incorretas. Talvez a conta
exija autenticação de dois fatores ou precise ativar a câmera para fazer uma verificação de retina. Não importa qual seja o motivo. Se você quiser um token válido, será necessário disparar o Intent
para obtê-lo.
Kotlin
private inner class OnTokenAcquired : AccountManagerCallback<Bundle> { override fun run(result: AccountManagerFuture<Bundle>) { val launch: Intent? = result.getResult().get(AccountManager.KEY_INTENT) as? Intent if (launch != null) { startActivityForResult(launch, 0) } } }
Java
private class OnTokenAcquired implements AccountManagerCallback<Bundle> { @Override public void run(AccountManagerFuture<Bundle> result) { ... Intent launch = (Intent) result.getResult().get(AccountManager.KEY_INTENT); if (launch != null) { startActivityForResult(launch, 0); return; } } }
Observe que o exemplo usa startActivityForResult()
, para que você possa capturar
o resultado do Intent
implementando onActivityResult()
na
sua própria atividade. Isso é importante: se você não capturar o resultado da
Intent
de resposta do autenticador,
será impossível dizer se o usuário foi autenticado.
Se o resultado for RESULT_OK
, o
autenticador atualizou as credenciais armazenadas para que elas sejam suficientes para
o nível de acesso solicitado. Chame AccountManager.getAuthToken()
novamente para solicitar o novo
token de autenticação.
O último caso, em que o token expirou, não é uma falha de AccountManager
. A única maneira de descobrir se um token expirou é entrar em contato com o servidor. Seria
um desperdício e caro para AccountManager
ficar sempre on-line para verificar o
estado de todos os tokens. Portanto, essa é uma falha que só pode ser detectada quando um aplicativo como
o seu tenta usar o token de autenticação para acessar um serviço on-line.
Conectar ao serviço on-line
O exemplo abaixo mostra como se conectar a um servidor do Google. Como o Google usa o protocolo OAuth2 padrão do setor para autenticar solicitações, as técnicas discutidas aqui são amplamente aplicáveis. No entanto, lembre-se de que cada servidor é diferente. Talvez você precise fazer pequenos ajustes nessas instruções para considerar sua situação específica.
As APIs do Google exigem que você forneça quatro valores a cada solicitação: a chave de API, o ID do cliente, a chave secreta do cliente e a chave de autenticação. Os três primeiros vêm do site do Console de APIs do Google. O último é o valor de string que você
recebeu chamando AccountManager.getAuthToken()
. Você os transmite para o servidor do Google como parte de uma solicitação HTTP.
Kotlin
val url = URL("https://www.googleapis.com/tasks/v1/users/@me/lists?key=$your_api_key") val conn = url.openConnection() as HttpURLConnection conn.apply { addRequestProperty("client_id", your client id) addRequestProperty("client_secret", your client secret) setRequestProperty("Authorization", "OAuth $token") }
Java
URL url = new URL("https://www.googleapis.com/tasks/v1/users/@me/lists?key=" + your_api_key); URLConnection conn = (HttpURLConnection) url.openConnection(); conn.addRequestProperty("client_id", your client id); conn.addRequestProperty("client_secret", your client secret); conn.setRequestProperty("Authorization", "OAuth " + token);
Caso a solicitação retorne um código de erro HTTP 401, isso significa que seu token foi negado. Conforme mencionado na última seção, o motivo mais comum para isso é a expiração do token. A correção é simples: chame AccountManager.invalidateAuthToken()
e repita o processo de aquisição do token mais uma vez.
Como os tokens expirados são uma ocorrência comum e a correção deles é muito fácil, muitos aplicativos simplesmente supõem que o token expirou antes mesmo de solicitá-lo. Se a renovação de um token for uma
operação barata para o servidor, pode ser preferível chamar
AccountManager.invalidateAuthToken()
antes da primeira chamada para
AccountManager.getAuthToken()
e evitar a necessidade de solicitar um token de autenticação
duas vezes.