Você está vendo a documentação do Apigee Edge.
Acesse a
documentação da Apigee X. informações
O OAuth surgiu como o principal protocolo de autorização para APIs. A versão do OAuth abordada em detalhes neste tópico é definida na Especificação do OAuth 2.0.
O OAuth é um protocolo que permite aos usuários finais do app autorizar apps a agir em nome deles. Os apps fazem isso por meio do recebimento de tokens de acesso dos provedores de API. O provedor de API autentica as credenciais do usuário final, assegura que o usuário autorizou o aplicativo e emite um token de acesso para o aplicativo. Quando o aplicativo consome uma API protegida, o Apigee Edge verifica o token de acesso para garantir que ele é válido e não expirou. Como provedor de API, você precisa expor endpoints que permitam aos apps receber tokens de acesso.
Para facilitar o uso do OAuth, o Apigee Edge permite configurar e aplicar o OAuth usando políticas, sem que você precise escrever qualquer código. Neste tópico, você vai aprender a proteger suas APIs, como conseguir tokens de acesso e como usar esses tokens para acessar APIs protegidas.
A configuração padrão do OAuth para sua organização
Por conveniência, todas as organizações no Apigee Edge vêm pré-configuradas com um conjunto de endpoints OAuth 2.0 que implementam o tipo de concessão de credenciais do cliente. O tipo de concessão de credenciais do cliente define um procedimento para emitir tokens de acesso em troca de credenciais de apps. Essas credenciais do app são simplesmente o par de chaves e secrets do cliente que o Apigee Edge emite para cada app registrado em uma organização. "Credenciais de cliente" se referem ao próprio par de chaves e secrets do cliente.
Para saber mais sobre a emissão de credenciais para apps usando os Serviços para desenvolvedores de borda, consulte Registrar apps e gerenciar chaves.
Por esse motivo, é relativamente simples "intensificar" o esquema de segurança da API desde a validação da chave até as credenciais do cliente OAuth. Os dois esquemas usam a mesma chave e chave secreta do cliente para validar o app cliente. A diferença é que as credenciais do cliente fornecem uma camada extra de controle, já que é possível revogar facilmente um token de acesso quando necessário, sem a necessidade da revogação da chave do consumidor do app. Para trabalhar com os endpoints OAuth padrão, use qualquer chave e secret do cliente gerados para o app na sua organização para recuperar os tokens de acesso do endpoint do token. É possível até ativar credenciais de cliente para apps que já têm chaves do cliente e secrets.
A especificação completa da concessão de credenciais de cliente está disponível na Especificação do OAuth 2.0.
Proteger a API com uma política
Antes de usar tokens de acesso, você precisa configurar suas APIs para validar os tokens de acesso OAuth no ambiente de execução. Para isso, configure um proxy de API para validate os tokens de acesso. Isso significa que, sempre que um app faz uma solicitação para consumir uma das suas APIs, ele precisa apresentar um token de acesso válido com a solicitação. O Apigee Edge lida com a complexidade por trás da geração, do armazenamento e da validação dos tokens de acesso apresentados.
É fácil adicionar a verificação OAuth a uma API ao criar um novo proxy de API. Ao criar um novo proxy de API, é possível Adicionar recursos. Conforme mostrado abaixo, você pode adicionar a verificação de tokens de acesso do OAuth 2.0 selecionando o botão de opção ao lado de Proteger com tokens de acesso do OAuth v2.0. Quando você seleciona essa opção, duas políticas são anexadas ao proxy de API recém-criado: uma para verificar os tokens de acesso e outra para remover o token de acesso depois que ele é verificado.
Além disso, quando você seleciona a opção Proteger com tokens de acesso OAuth v2.0, a caixa de seleção Publicar produto da API pode ser selecionada e marcada automaticamente. Marque esta opção se você quiser gerar um produto automaticamente ao criar o novo proxy de API. O produto gerado automaticamente será criado com uma associação ao novo proxy de API. Se você tiver um produto atual ao qual quer associar essa nova API, não se esqueça de desmarcar essa caixa de seleção para não criar um produto desnecessário. Para mais informações sobre produtos, consulte O que é um produto de API?
Se você precisar ativar a verificação do token de acesso para o proxy de API que já existe, basta anexar uma política do tipo OAuthV2 à API que quer proteger. As políticas do OAuthV2 funcionam especificando uma operação. Se quiser validar tokens de acesso, especifique a operação chamada VerifyAccessToken. Outros tipos de operações compatíveis com o tipo de política OAuthV2 são GenerateAccessToken e GenerateRefreshToken. Você vai aprender sobre essas operações ao configurar endpoints OAuth.)
Política VerifyOAuthTokens do tipo OAuthV2
Confira a seguir um exemplo de política para validar tokens de acesso. As configurações são explicadas na tabela abaixo.
<OAuthV2 name="VerifyOAuthTokens"> <Operation>VerifyAccessToken</Operation> </OAuthV2>
Configurações da política
| Nome | Descrição | Padrão | Obrigatório? |
|---|---|---|---|
OAuthV2 |
O tipo de política | ||
name |
O nome da política, que é referenciado na configuração do endpoint do proxy de API. | N/A | Sim |
Operation |
A operação a ser executada pela política OAuthV2. Ao especificar VerifyAccessToken, você configura a política para verificar solicitações de tokens de acesso e se o token de acesso é válido, não expirou e está aprovado para consumir o recurso da API (URI) solicitado. Para fazer essa verificação, a política lê o produto de API que o app está aprovado para consumir. | N/A | Sim |
Para criar essa política na interface de gerenciamento, navegue até APIs > Proxies de API.
Na lista de proxies de API, selecione weatherapi.
Na Visão geral do weatherapi, selecione a visualização Desenvolver.
No menu suspenso, selecione Nova política > OAuth v2.0
Depois de selecionar a política do OAuth v2.0, o menu de configuração Nova política será exibido.
Dê um nome descritivo à política e selecione Anexar política, Pré-fluxo de fluxo e Solicitação como configurações de anexo de política.
Selecione Add. A política será criada e anexada ao PreFlow de solicitação do weatherapi.
Depois que você adicionar a política, a configuração do PreFlow da solicitação abaixo será exibida no painel Designer.
Se você estiver trabalhando localmente em um editor de texto ou ambiente de desenvolvimento integrado, anexe a política ao pré-fluxo da solicitação do proxy de API que você quer proteger:
<PreFlow>
<Request>
<Step><Name>VerifyOAuthTokens</Name></Step>
</Request>
</PreFlow>
Ao anexar a política ao pré-fluxo da solicitação, você garante que ela seja sempre aplicada a todas as mensagens de solicitação.
Agora você protegeu uma API com as credenciais do cliente OAuth 2.0. A próxima etapa é aprender a conseguir um token de acesso e usá-lo para acessar a API segura.
Uso de um token para acessar um recurso protegido
Agora que a weatherapi está protegida com o OAuth 2.0, os apps precisam apresentar tokens de acesso para consumir a API. Para acessar um recurso protegido, o app apresenta um token de acesso na solicitação como um cabeçalho HTTP"Authorization" da seguinte maneira:
$ curl -H "Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282
Como a API tem uma política OAuthV2 anexada, o Apigee Edge verificará se o token de acesso apresentado é válido e concede acesso à API, retornando a previsão do tempo ao app que fez a solicitação.
Mas como os apps recebem tokens de acesso? Vamos falar sobre isso na próxima seção.
Como trocar credenciais de cliente por um token de acesso
Os apps recebem tokens de acesso apresentando os pares de chave/segredo do cliente ao endpoint do token. O endpoint do token é configurado no proxy de API chamado oauth. Portanto, os apps precisam chamar a API exposta pelo proxy de API oauth para receber um token de acesso. Depois que o app receber um token de acesso, ele poderá chamar a weatherapi repetidamente, até que o token de acesso expire ou o token de acesso seja revogado.
Agora é preciso mudar de direção e pensar que você é um desenvolvedor de apps. Para chamar o weatherapi, é necessário ter um token de acesso para o app. A primeira coisa que você precisa fazer é obter um par de chave e secret do cliente (também conhecido como chave de API ou chave de app).
Para receber uma chave e um secret do cliente, registre um app na sua organização no Apigee Edge.
É possível ver todos os apps da organização na interface de gerenciamento do Apigee Edge.
A lista de apps registrados na sua organização vai aparecer.
Se nenhum app for exibido, consulte o tópico Registrar apps e gerenciar chaves de API para saber como registrar um app.
Selecione um app na lista para conferir o perfil detalhado.
Na visualização de detalhes do app selecionado, observe os campos Chave do cliente e Chave secreta do cliente. Esses dois valores são as credenciais do cliente que você usará para receber um token de acesso do OAuth.
$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps \
-u myname:mypass
Essa chamada retorna uma lista de apps por ID do app.
[ "da496fae-2a04-4a5c-b2d0-709278a6f9db", "50e3e831-175b-4a05-8fb6-05a54701af6e" ]
É possível recuperar o perfil de um app fazendo uma chamada GET simples no ID do app:
$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps/{app_id} \
-u myname:mypass
Exemplo:
$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps/da496fae-2a04-4a5c-b2d0-709278a6f9db \
-u myname:mypass
A chamada de API retorna o perfil do app que você especificou. Por exemplo, um perfil de app para weatherapp tem a seguinte representação JSON:
{
"accessType" : "read",
"apiProducts" : [ ],
"appFamily" : "default",
"appId" : "da496fae-2a04-4a5c-b2d0-709278a6f9db",
"attributes" : [ ],
"callbackUrl" : "http://weatherapp.com",
"createdAt" : 1380290158713,
"createdBy" : "noreply_admin@apigee.com",
"credentials" : [ {
"apiProducts" : [ {
"apiproduct" : "PremiumWeatherAPI",
"status" : "approved"
} ],
"attributes" : [ ],
"consumerKey" : "bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K",
"consumerSecret" : "hAr4Gn0gA9vAyvI4",
"expiresAt" : -1,
"issuedAt" : 1380290161417,
"scopes" : [ ],
"status" : "approved"
} ],
"developerId" : "5w95xGkpnjzJDBT4",
"lastModifiedAt" : 1380290158713,
"lastModifiedBy" : "noreply_admin@apigee.com",
"name" : "weatherapp",
"scopes" : [ ],
"status" : "approved"
}
Observe os valores de consumerKey e consumerSecret. Use essas credenciais para receber um token de acesso. Basta apresentá-las como credenciais de autenticação básica em uma solicitação HTTP, conforme mostrado abaixo. O tipo de concessão é apresentado como um parâmetro de consulta à solicitação.
Altere o valor da variável {org_name} para refletir o nome da sua organização
no Apigee Edge.
Criar uma solicitação para receber um token de acesso
Na solicitação a seguir, substitua o valor de consumerKey por client_id. Substitua o valor do consumerSecret associado por
client_secret.
$ curl https://{org_name}-test.apigee.net/oauth/client_credential/accesstoken?grant_type=client_credentials -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K&client_secret=hAr4Gn0gA9vAyvI4'
Os serviços da API verificam a chave e o segredo do cliente e, em seguida, geram uma resposta contendo o token de acesso para o app:
{
"issued_at" : "1380892555397",
"application_name" : "957aa73f-25c2-4ead-8021-adc01f0d2c6b",
"scope" : "",
"status" : "approved",
"api_product_list" : "[oauth-test]",
"expires_in" : "3599",
"developer.email" : "tesla@weathersample.com",
"organization_id" : "0",
"client_id" : "bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K",
"access_token" : "ylSkZIjbdWybfs4fUQe9BqP0LH5Z",
"organization_name" : "rqa",
"refresh_token_expires_in" : "0",
"refresh_count" : "0"
}
Observe o valor access_token na resposta acima. Esse é o token de acesso que
o app vai usar para ter acesso de execução a recursos protegidos. O token de acesso para esse app é
ylSkZIjbdWybfs4fUQe9BqP0LH5Z.
Agora você tem um token de acesso válido, ylSkZIjbdWybfs4fUQe9BqP0LH5Z, que pode ser usado
para acessar APIs protegidas.
Como trabalhar com a configuração padrão do OAuth
Cada organização (até mesmo uma de avaliação sem custo financeiro) no Apigee Edge é provisionada com um endpoint de token OAuth. O endpoint é pré-configurado com políticas no proxy de API chamado oauth. É possível começar a usar o endpoint do token assim que criar uma conta no Apigee Edge.
O endpoint OAuth padrão expõe o seguinte URI de endpoint:
/oauth/client_credential/accesstoken
Publique esse URI para desenvolvedores que precisam conseguir tokens de acesso. Os desenvolvedores de aplicativos configuram os aplicativos para chamar esse endpoint, apresentando os pares de chave e secret do consumidor para receber tokens de acesso.
O endpoint do token de credenciais do cliente padrão é exposto pela rede no seguinte URL:
https://{org_name}-{env_name}.apigee.net/oauth/client_credential/accesstoken
Por exemplo, se o nome da organização for "apimakers", o URL será:
https://apimakers-test.apigee.net/oauth/client_credential/accesstoken
Esse é o URL que os desenvolvedores chamam para receber tokens de acesso.
Configurações de OAuth de três etapas
As configurações de OAuth de três etapas (tipos de concessão de código de autorização, implícito e de senha) exigem que você, o provedor de API, autentique os usuários finais do app. Como cada organização autentica os usuários de maneiras diferentes, é necessário ter um pouco de personalização de políticas ou códigos para integrar o OAuth à sua loja de usuários. Por exemplo, todos os usuários podem ser armazenados no Active Directory, em um LDAP ou em algum outro armazenamento de usuários. Para ativar o OAuth de três etapas, integre uma verificação desse armazenamento do usuário ao fluxo geral do OAuth.
OAuth 1.0a
Para saber mais sobre a política do OAuth 1.0a, consulte Política do OAuth v1.0a.
Conseguir ajuda
Para receber ajuda, consulte o Suporte ao cliente da Apigee.