OAuth

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X. informações

O OAuth surgiu como o principal protocolo de autorização para APIs. A versão do OAuth, que é abordado em detalhes neste tópico, está definido na documentação do OAuth 2.0 Especificação.

OAuth é um protocolo que permite aos usuários finais do aplicativo autorizar apps para agir em nome deles. Os aplicativos fazem isso obtendo o acesso tokens dos provedores de API. O provedor da API autentica o processo as credenciais do usuário, garante que ele autorizou o aplicativo e emite um token de acesso para o app. Quando o app consome uma API protegida, o Apigee Edge verifica o token de acesso para garantir se ele é válido e não expirou. Como provedor de API, você precisa expor endpoints que permitem que os apps recebam tokens de acesso.

Para facilitar o uso do OAuth, o Apigee Edge permite que você configure e aplique o OAuth usando políticas, sem a necessidade de escrever códigos. Neste tópico, você vai aprender a proteger suas APIs, como obter acesso e como usá-los 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 OAuth 2.0 de endpoints que implementam o tipo de concessão de credenciais do cliente. O cliente O tipo de concessão de credenciais define um procedimento para a emissão de tokens de acesso em troca de um serviço credenciais. Essas credenciais do aplicativo são simplesmente o par de chave e segredo do cliente que Problemas do Apigee Edge para cada app registrado em uma organização. "Credenciais do cliente" refere-se ao próprio par de token e senha do cliente.

Para saber mais sobre a emissão de credenciais para apps usando o Edge Developer Services, consulte Registre apps e gerencie chaves.

Por esse motivo, é relativamente simples "se aproximar" seu esquema de segurança de API da chave de API para as credenciais do cliente OAuth. Ambos os esquemas utilizam a mesma chave de cliente e o mesmo segredo 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 de revogar a chave do cliente do app. Para trabalhar com os endpoints OAuth padrão, você pode usar qualquer chave do cliente e o segredo gerado para o aplicativo em sua organização para recuperar tokens de acesso do token endpoint do Google Cloud. É possível até ativar credenciais de clientes para aplicativos que já têm chaves de consumidor e secrets.)

A especificação completa para a concessão de credenciais de cliente pode ser encontrada na documentação do OAuth 2.0 Especificação.

Proteger a API com uma política

Antes de poder usar tokens de acesso, você precisa configurar suas APIs para validar o acesso do OAuth no ambiente de execução. Para fazer isso, configure um proxy de API para validar tokens de acesso. Ou seja, sempre que um app solicita consumir uma de suas APIs, o aplicativo deverá apresentar um token de acesso válido junto com a solicitação de API. O Apigee Edge lida com a complexidade por trás da geração, armazenamento e 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, você pode Adicionar recursos. Conforme mostrado abaixo, é possível 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, dois políticas serão anexadas ao proxy de API recém-criado, uma para verificar tokens de acesso e outra remover o token de acesso após a verificação.

Além disso, ao selecionar a opção Secure with OAuth v2.0 Access Tokens, a caixa de seleção Publicar produto da API fica selecionável e automaticamente selecionados. Marque esta opção se quiser gerar um produto automaticamente ao criar a nova API proxy. O produto gerado automaticamente será criado com uma associação ao novo proxy de API. Se você tiver um produto existente ao qual deseja associar essa nova API, desmarque essa para não criar um produto desnecessário. Para informações sobre produtos, consulte O que é um produto de API?

Se for necessário 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 você querem proteger. As políticas OAuthV2 especificam uma operação. Se você quiser para validar tokens de acesso, especifique a operação VerifyAccessToken. (Outros tipos de operações que são 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

Veja a seguir um exemplo de política para validar tokens de acesso. (As configurações são explicado na tabela abaixo.)

<OAuthV2 name="VerifyOAuthTokens"> 
  <Operation>VerifyAccessToken</Operation> 
</OAuthV2>

Configurações da política

Para criar essa política na interface de gerenciamento, acesse APIs > API Proxies.

Na lista de proxies de API, selecione weatherapi.

Na Visão geral da weatherapi, selecione a opção Desenvolver visualização.

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. Flow PreFlow e Request como configurações de anexo de política.

Selecione Add, e a política será criada e anexada à solicitação do weatherapi PreFlow.

Depois de adicionar a política, a configuração de pré-fluxo da solicitação abaixo será exibida na Painel Designer.

Se você estiver trabalhando localmente em um editor de texto ou ambiente de desenvolvimento integrado, anexe a política para o PreFlow de 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. em todas as mensagens de solicitação.

Você protegeu uma API com as credenciais do cliente OAuth 2.0. A próxima etapa é aprender para obter um token de acesso e usá-lo para acessar a API segura.

Usar um token de acesso para acessar uma instância recurso

Agora que o weatherapi está protegido com o OAuth 2.0, os aplicativos devem apresentar tokens de acesso para consumir a API. Para acessar um recurso protegido, o aplicativo apresenta um token de acesso na solicitação como um "Autorização" cabeçalho HTTP da seguinte forma:

$ 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 para o aplicativo 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 uma token de acesso

Os apps recebem tokens de acesso apresentando os pares de chave/segredo do consumidor ao token endpoint do Google Cloud. O endpoint do token é configurado no proxy de API chamado oauth do SDK do Cloud. Por isso, os apps precisam chamar a API exposta pela API oauth. proxy para receber um token de acesso. Depois que o app tiver um token de acesso, ele poderá chamar a weatherapi repetidamente, até que o token de acesso expire ou seja revogado.

Agora você precisa mudar o foco para pensar em si como um desenvolvedor de aplicativos. Você quer chamar a função weatherapi, então você precisa de um token de acesso para seu aplicativo. A primeira coisa que você precisa fazer conseguir um par de chave e segredo do cliente (também conhecido como um par de chaves key ou uma chave de app).

Para receber uma chave e um secret do consumidor, registre um app na sua organização na Apigee Borda

É possível ver todos os apps da sua 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, saiba como fazer isso no tópico Registrar apps e gerenciar API chaves.

Selecione um aplicativo na lista para visualizar seu perfil detalhado.

Na visualização de detalhes do app selecionado, observe os campos de Consumer Key. e Chave secreta do cliente. Esses dois valores são os valores de cliente credenciais que você usará para receber um token de acesso 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 aplicativo 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"
}

Anote os valores de consumerKey e consumerSecret. Você usa essas para receber um token de acesso ao apresentá-las como credenciais de autenticação básica no uma solicitação HTTP, como 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 do 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 de API verificam a chave e o segredo do cliente e geram uma resposta contendo os token de acesso para este 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 o aplicativo usará para obter acesso de tempo de execução a recursos protegidos. O token de acesso para este 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 (mesmo as de teste sem custo financeiro) no Apigee Edge é provisionada com um token OAuth endpoint do Google Cloud. O endpoint é pré-configurado com políticas no proxy de API chamadas oauth do SDK do Cloud. Você pode começar a usar o endpoint de 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 do OAuth de três etapas

Configurações de OAuth de três etapas (concessão de código de autorização, implícito e senha) tipos) exigem que você, o provedor da API, autentique os usuários finais do app. Como cada a organização autentica os usuários de diferentes maneiras, é necessário um pouco de personalização de política ou código para integrar o OAuth à sua loja de usuários. Por exemplo, todos os seus usuários podem ser armazenados em Active diretório, em um LDAP ou em algum outro armazenamento de usuário. Para ativar o OAuth de três etapas, precisa integrar uma verificação desse armazenamento de usuários ao fluxo geral do OAuth.

OAuth 1.0a

Para mais detalhes sobre a política do OAuth 1.0a, consulte a política do OAuth v1.0a.

Ajuda

Para receber ajuda, consulte Apigee Suporte ao Cliente.