Documentação do Oracle Cloud Infrastructure

Usando a Autorização do Token de Acesso com a API Meus Serviços

Importante

O painel de controle Meus Serviços e as APIs estão obsoletos.

Este tópico explica como configurar e usar a autorização de token de acesso com a API Meus Serviços do Oracle Cloud. A autorização do token de acesso permite que um desenvolvedor acesse pontos finais programáticos (APIs)para obter algumas informações (por exemplo, direitos, instâncias ou medição de dados) da sua conta do Cloud.

Sobre Tokens de Acesso

Um token de acesso contém as informações necessárias para permitir que um desenvolvedor acesse informações da sua conta do Cloud. Um desenvolvedor apresenta o token ao fazer chamadas de API. As ações e os pontos finais permitidos dependem dos escopos (permissões) que você seleciona quando gera o token. Um token de acesso é válido durante uma hora.

Um token de atualização permite que o desenvolvedor gere um novo token de acesso sem precisar entrar em contato com um administrador. Um token de atualização é válido por cerca de um ano.

Visão Geral do Processo

Etapas de configuração para o Administrador

  1. Crie um aplicativo cliente do Identity Cloud Service com os privilégios específicos que você deseja conceder aos desenvolvedores.
  2. Gere um token de acesso que contenha os privilégios necessários para o desenvolvedor desejado.
  3. Forneça o token de acesso e as informações necessárias ao desenvolvedor.
  4. Configure o Identity Cloud Service para validação do token de acesso.

Etapas para o desenvolvedor usar o token:

  1. Emita solicitações com relação aos pontos finais da API Meus Serviços. Inclua o token de acesso para o parâmetro de autorização.
  2. Quando o token de acesso expirar, atualize o token de acesso sem intervenção do administrador até que o privilégio seja encerrado.

Tarefas do Administrador para Configurar Validação de Token

Execute as tarefas a seguir para permitir o acesso do desenvolvedor com um token de acesso:

Criar o Aplicativo Cliente do IDCS
  1. Acesse o Identity Cloud Services como Administrador e vá para a console de administração. Consulte Como Acessar o Oracle Identity Cloud Service se precisar de ajuda para acessar o sistema.
  2. Clique no bloco Aplicativos. Uma lista dos aplicativos é exibida.
  3. Clique em + Adicionar para criar um novo aplicativo.
  4. Clique em Aplicativo Confidencial como o tipo de aplicativo.
  5. Na seção Detalhes do Aplicativo, digite um Nome e uma Descrição. Evite digitar informações confidenciais.
  6. Clique em Próximo.

  7. Na seção Cliente:

    1. Selecione Configurar este aplicativo como cliente agora.
    2. Em Autorização, para Tipos de Concessão Permitidos, selecione as seguintes opções:
      • Asserção JWT
      • Token de Atualização

  8. Em Política de Emissão de Token, em Recursos, clique em Adicionar Escopo.

  9. Na caixa de diálogo Selecionar Escopo, selecione CloudPortalResourceApp e clique na seta para selecionar escopos para o recurso.

  10. Marque a caixa ao lado de cada autorização que talvez você queira dar aos desenvolvedores a quem você fornecerá um Token de Acesso. (As permissões são designadas em outra etapa.)

  11. Clique em Adicionar para fechar a caixa de diálogo. Suas seleções são exibidas.

  12. Clique em Próximo.

  13. Na seção Recursos, aceite o padrão e clique em Próximo.
  14. Na seção Política da Camada Web, aceite o padrão e clique em Próximo.

  15. Na seção Autorização, clique em Finalizar.

    A notificação Aplicativo Adicionado exibe o novo ID do Cliente e o Segredo do Cliente para o aplicativo.

    Importante

    Copie e armazene o ID do Cliente e o Segredo do Cliente em um local seguro e, em seguida, clique em Fechar. O ID do Cliente e o Segredo do Cliente são credenciais específicas do aplicativo que você acabou de criar. Você precisará dessas credenciais posteriormente.
  16. Para concluir o processo de criação, clique em Ativar na parte superior da página.
Gerar um token de acesso

  1. Navegue até o aplicativo IDCS que você criou na tarefa anterior e selecione a guia Detalhes.

  2. Clique em Gerar Token de Acesso.

  3. Na caixa de diálogo Gerar Token, selecione Escopos Personalizados e, em seguida, selecione Chama Outras APIs.

  4. Selecione os escopos que você deseja dar ao desenvolvedor que receberá este token de acesso.

    Observação

    A Oracle recomenda que você forneça apenas os privilégios mínimos necessários.

  5. Selecione Incluir Token de Atualização.

  6. Clique em Fazer Download do Token. Seu browser solicitará que você faça download de um arquivo de token (. tok). O arquivo de token contém um token de acesso e um token de atualização.

  7. Forneça este arquivo ao desenvolvedor.
Enviar as informações de acesso a um desenvolvedor

Para chamar pontos finais de API, o desenvolvedor precisa:

  • De um arquivo de token que você gerou.

  • Do ID do Cliente e do Segredo do Cliente do aplicativo IDCS usado para gerar o arquivo de token. O ID e o Segredo do Cliente são obrigatórios para o desenvolvedor gerar um novo token de acesso com base no token de atualização.

  • Dos pontos finais das APIs.

    • Pontos finais relacionados aos escopos itas:myservices são: https://itra.oraclecloud.com/itas/<tenant-IDCS-ID>/myservices/api/v1
    • Os pontos finais relacionados aos escopos itas:metering são: https://itra.oraclecloud.com/metering/api/v1

Certifique-se de enviar as informações acima de uma forma segura. Se você achar que essas informações foram comprometidas, consulte Revogando a Capacidade de um Desenvolvedor Atualizar Tokens de Acesso.

Configurar o Identity Cloud Service para validação do token de acesso

Para permitir que os clientes acessem o certificado de assinatura do tenant sem fazer log-in no Oracle Identity Cloud Service:

  1. Acesse a console de administração do Oracle Identity Cloud Services. Consulte Como Acessar o Oracle Identity Cloud Service se precisar de ajuda para acessar o sistema.
  2. Abra o menu de navegação. Em Definições, selecione Definições Padrão.
  3. Defina o botão de alternância Acessar Certificado de Assinatura como ativado.

Usando o Token de Acesso

O arquivo de token tem uma extensão .tok. O arquivo contém o token de acesso e o token de atualização. O conteúdo é semelhante a:

{"app_access_token":"eyJ4N...aabb...CpNwA","refresh_token":"AQID...9NCA="}

Para usar o token com a API Meus Serviços:

  1. Abra o arquivo de token.

  2. Emita uma solicitação para um ponto final válido, inserindo o token de acesso para o parâmetro Authorization.

    Por exemplo:

    curl -X GET  https://itra.oraclecloud.com/itas/<tenant-IDCS-ID>/myservices/api/v1/serviceEntitlements   -H 'Authorization: Bearer eyJ4N...aabb...CpNwA'

Solicitando um Novo Token de Acesso de um Token de Atualização

Um token de acesso é válido durante uma hora. Quando o token não for mais válido, você obterá um código de resposta 401 e um valor de Mensagem de Erro ("errorMessage") contendo "Expirado."

Você pode gerar um novo token de acesso de curta duração com base no token de atualização. Você precisará do ID do Cliente e do Segredo do Cliente para gerar o novo token. Você só pode gerar tokens com o mesmo acesso ou menor (escopos) que o seu token original.

Exemplo usando o comando curl:

curl -i -H 'Authorization: Basic <base64Encoded clientid:secret>' -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST https://<tenant-IDCS-ID>/oauth2/v1/token -d 'grant_type=refresh_token&refresh_token=<refresh-token>'

Usando o arquivo de token de amostra da seção anterior, o valor de <refresh-token> seria AQID...9NCA=.

Amostra de resposta:

{ "access_token": "eyJraWQiO....2nqA", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "AQIDBAUn…VkxNCB7djF9NCA=" }
Observação

Quando um desenvolvedor gera um novo token de acesso e um token de atualização, o token de atualização anterior torna-se inválido.

Revogando a Capacidade de um Desenvolvedor Atualizar Tokens de Acesso

Se precisar revogar a capacidade de um desenvolvedor atualizar tokens de acesso, você pode invalidar o token de atualização existente gerando um novo Segredo do Cliente para o token; como alternativa, você pode revogar temporariamente o acesso desativando o aplicativo.

Importante

A realização dessas ações encerrará ou suspenderá a capacidade de todos os desenvolvedores usarem o Segredo do Cliente ou o aplicativo atual. Ao gerar tokens para vários desenvolvedores, considere criar mais de um aplicativo do IDCS para isolar desenvolvedores um do outro.

Para encerrar a capacidade de um desenvolvedor para atualizar seu token de acesso

  1. Acesse o Identity Cloud Services como Administrador e vá para a console de administração. Consulte Como Acessar o Oracle Identity Cloud Service se precisar de ajuda para acessar o sistema.
  2. Clique no bloco Aplicativos. Uma lista dos aplicativos é exibida.
  3. Clique no aplicativo usado para gerar o token e exibir seus detalhes.
  4. Clique em Configuração.
  5. Em Informações Gerais, ao lado de Segredo do Cliente, clique em Gerar Novamente para gerar um novo Segredo do Cliente.

Para restaurar a capacidade de o desenvolvedor gerar um token de acesso com base em um token de atualização, gere um novo token de acesso. Em seguida, forneça o token junto com o novo Segredo do Cliente ao desenvolvedor.

Para suspender temporariamente a capacidade de um desenvolvedor de atualizar o token de acesso

  1. Acesse o Identity Cloud Services como Administrador e vá para a console de administração. Consulte Como Acessar o Oracle Identity Cloud Service se precisar de ajuda para acessar o sistema.
  2. Clique no bloco Aplicativos. Uma lista dos aplicativos é exibida.
  3. Clique no aplicativo usado para gerar o token e exibir seus detalhes.
  4. No canto superior direito da página, clique em Desativar.
  5. No prompt, clique em Desativar Aplicativo.

Para capacitar novamente os desenvolvedores a usar os mesmos tokens, clique em Ativar.