Usar APIs REST de Autenticação Avançada da Oracle com Postman

Introdução

Este tutorial mostra como fazer chamadas de API REST para Autenticação Avançada Oracle usando Postman, software geralmente usado para testes de API REST.

Objetivos

As APIs REST de Autenticação Avançada da Oracle fornecem uma maneira de integrar a Autenticação Avançada da Oracle aos clientes REST para que eles possam configurar e administrar a Autenticação Avançada da Oracle. Para obter uma lista completa dos pontos finais de API REST, consulte API Admin do OAA.

Neste tutorial, você aprenderá a fazer download e importar a coleção Postman do Oracle Advanced Authentication e testar algumas das solicitações Postman mais comuns.

Pré-requisitos

Para concluir este tutorial, você precisará do seguinte:

• Uma instalação do Oracle Advanced Authentication em execução
• Oracle Mobile Authenticator instalado em um dispositivo móvel
• Familiaridade com o estilo de arquitetura REST
• Cliente Postman nativo v8.0.6 ou mais recente instalado
• Os arquivos json Oracle_Advanced_Authentication_REST_API.postman_collection.json, Oracle_Advanced_Authentication_Example_Environment.postman_environment.json

Instalar a Coleção Postman de Autenticação Avançada da Oracle

Definir os Parâmetros de Ambiente em Postman

1. Abra Postman e selecione Arquivo > Importar.

2. Na caixa de diálogo Importar, na guia Arquivo, selecione Fazer Upload de Arquivos. Escolha Oracle_Advanced_Authentication_Example_Environment.postman_environment.json e clique em Abrir.

3. No menu esquerdo, clique em .

4. Na lista de ambientes exibida, à direita do Ambiente de Exemplo de Autenticação Avançada da Oracle, clique na elipse e, em seguida, em Duplicar

   

   Descrição da ilustração duplicate_env.jpg

5. Em Cópia do Ambiente de Exemplo de Autenticação Avançada da Oracle, que aparece acima do ambiente original, clique nas elipses e renomeie para Oracle Advanced Authentication Environment for REST APIs.

6. Atualize as variáveis de ambiente do novo ambiente informando os seguintes valores para Valor Inicial e Valor Atual. Depois de concluído, clique em Salvar e, em seguida, em X na guia para fechá-la:

   • oaa-admin: o nome do host e a porta de administração do Oracle Advanced Authentication, por exemplo, https://oaa.example.com
   • oaa-policy: o nome do host e a porta de política do Oracle Advanced Authentication, por exemplo, https://oaa.example.com
   • oaa-runtime: Nome do host e porta de runtime do Oracle Advanced Authentication, por exemplo, https://oaa.example.com
   • RELEASENAME: O RELEASENAME designado à configuração da Autenticação Avançada da Oracle, por exemplo, oaainstall. Este é o valor informado para common.deployment.name ao instalar o OAA.
   • oaapolicyapikey: O oaapolicyapikey para a configuração da Autenticação Avançada da Oracle, por exemplo, a5764d4ef6b71129f38a2d8ddc88b6060653d3c8. Este é o valor informado para install.global.policyapikey ao instalar o OAA.
   • oaaapikey: O oaaapikey para a configuração da Autenticação Avançada da Oracle, por exemplo, a5764d4ef6b71129f38a2d8ddc88b6060653d3c8. Este é o valor informado para install.global.uasapikey ao instalar o OAA.

   Observação: se você não souber os URLs para oaa-admin, oaa-policy e oaa-runtime (spui), execute o seguinte no cluster do Kubernetes do OAA:

   kubectl get pods -n <namespace> | grep 'oaa-admin\|oaa-policy\|spui'
   

   Em seguida, para cada pod, execute o seguinte para obter o URL:

   kubectl exec -it <pod> -n <namespace> -- cat serviceurl.txt
   

   O ambiente será semelhante ao seguinte:

   

   Descrição da ilustração environment.jpg

   Observação: Os valores de URL no exemplo acima supõem uma instalação OAA usando NodePort e, portanto, os números de porta de cada pods são definidos no URL. Se a instalação do OAA usar uma entrada, use o URL de entrada em todos os casos.

7. Clique na lista drop-down Ambiente e selecione o ambiente atualizado na lista:

   

   Descrição da ilustração environment_selection.jpg

Importar a Coleção Postman

1. Para importar a coleção Postman da API REST do Oracle Advanced Authentication, na página principal Postman, selecione Arquivo > Importar.

2. Na caixa de diálogo Importar, na guia Arquivo, selecione Fazer Upload de Arquivos. Escolha o arquivo Oracle_Advanced_Authentication_REST_API.postman_collection.json e clique em Abrir e, em seguida, em Importar.

   Clique em Coletas no menu esquerdo. A coleção deve ser exibida da seguinte forma:

   

   Descrição da ilustração collections.jpg

Testar as APIs REST

Nesta seção, você executará algumas das solicitações na coleção Postman para Autenticação Avançada da Oracle.

Observação: para evitar erros de verificação do certificado SSL, navegue até Arquivo > Configurações e, na guia Geral, defina verificação do certificado SSL como DESATIVADO.

Criar um Agente de Integração da API

Nesta seção, você criará um agente de integração de API.

1. Na guia Coleções, navegue até API REST de Autenticação Avançada da Oracle > API REST para Definir Entidades do Sistema -> agente/v1.

2. Selecione Criar um novo agente de integração de API. Esta solicitação faz uma solicitação POST para o ponto final /oaa-policy/agent/v1 e cria um agente de integração de API chamado APIAgent com base nas informações do Corpo:

   

   Descrição da ilustração createapiagent.jpg

3. Clique em Enviar.

4. Na resposta, confirme se Status: 200 OK aparece e se o corpo da resposta exibe detalhes sobre o agente de integração criado. Anote o agentgid retornado, pois ele será usado nas seções a seguir.

   

   Descrição da ilustração createapiagentsuccess.jpg

Criar um Nível de Garantia

Nesta seção, você criará um Nível de Garantia para o agente de integração criado.

1. Na guia Coleções, navegue até API REST de Autenticação Avançada da Oracle > API REST para Definir Entidades do Sistema -> AssuranceLevel/v1.

2. Selecione Definir Nível de Garantia. Esta solicitação faz uma solicitação POST para o ponto final /oaa-policy/assuranceLevel/v1 e cria um Nível de Garantia para o agente de integração chamado AssuranceLevel1. No corpo, edite o valor de agentid para corresponder ao valor retornado anteriormente:

   

   Descrição da ilustração createassurancelvl.jpg

3. Clique em Enviar.

4. Na resposta, confirme se Status: 200 OK aparece e se o corpo da resposta exibe detalhes sobre o Nível de Garantia criado.

   

   Descrição da ilustração createassurancelvlsuccess.jpg

Criar Grupos

Nesta seção, você criará um grupo de ações para Fatores e um grupo para endereços IP. Esses grupos serão designados posteriormente a uma política e regra para o agente de integração e Nível de Garantia criados anteriormente.

1. Na guia Coleções, navegue até API REST de Autenticação Avançada da Oracle > API REST para Definir Entidades do Sistema -> group/v1.

2. Selecione Criar novo grupo de fatores. Esta solicitação faz uma solicitação POST para o ponto final /oaa-policy/group/v1 e cria um grupo para o agente chamado FactorRuleGrp1. No corpo, edite o valor de agentid para corresponder ao valor retornado anteriormente. Neste exemplo, o grupo define dois fatores - ChallengeEmail e ChallengeOMATOTP:

   

   Descrição da ilustração createfactorgrp.jpg

3. Clique em Enviar.

4. Na resposta, confirme se Status: 200 OK aparece e se o corpo da resposta exibe detalhes sobre o grupo criado. Anote o groupid, pois ele será usado posteriormente para designar esse grupo a uma política.

   

   Descrição da ilustração createfactorgrpsuccess.jpg

5. Na coleção atual em group/v1, selecione Criar novo grupo do tipo IPs. Esta solicitação faz uma solicitação POST para o ponto final /oaa-policy/group/v1 e cria um grupo para o agente de integração chamado SecureIP. No corpo, edite o valor de agentgid para corresponder ao valor retornado anteriormente. Neste exemplo, a seção de valores define os IPs de 198.51.100.1 para 198.51.100.3:

   

   Descrição da ilustração createipgrp.jpg

6. Clique em Enviar.

7. Na resposta, confirme se Status: 200 OK aparece e se o corpo da resposta exibe detalhes sobre o grupo criado. Anote o groupid, pois ele será usado posteriormente para designar esse grupo a uma política.

   

   Descrição da ilustração createipgrpsuccess.jpg

Criar Política

Nesta seção, você criará uma Política para o Nível de Garantia e o agente de integração criado anteriormente.

1. Na guia Coleções, navegue até API REST de Autenticação Avançada da Oracle > API REST para Definir Entidades do Sistema -> política/v1.

2. Selecione Criar Nova Política. Esta solicitação faz uma solicitação POST para o ponto final /oaa-policy/policy/v1 e cria uma política para o agente de integração criado anteriormente e o nível de garantia chamado Policy1. No corpo, edite o valor de agentgid para corresponder ao valor retornado anteriormente:

   

   Descrição da ilustração createpolicy.jpg

3. Clique em Enviar.

4. Na resposta, confirme se Status: 200 OK aparece e se o corpo da resposta exibe detalhes sobre a política criada. Anote o policygid, pois ele será usado posteriormente, designe uma regra a esta política.

   

   Descrição da ilustração createpolicysuccess.jpg

Criar Regra de Política

Nesta seção, você criará uma Regra de Política para a Política.

1. Na guia Coleções, navegue até API REST de Autenticação Avançada da Oracle > API REST para Definir Entidades do Sistema -> policy/v1 -> {policygid} -> regra > {ruleid}.

2. Selecione Definir nova regra para a política. Esta solicitação faz uma solicitação POST para o ponto final /oaa-policy/policy/v1/:policygid/rule. Na guia Parâmetros, edite o valor de policygid para corresponder ao valor da política retornado anteriormente. No Corpo, em conditionMap edite os valores em expression e values e defina como groupId do grupo SecureIP criado anteriormente. Em results, defina o valor de action para corresponder ao groupId do grupo FactorGroup1 criado anteriormente:

   

   Descrição da ilustração createrule.jpg

   Na regra acima, a regra declara que, se o endereço IP do usuário final que faz a solicitação de autenticação for um dos definidos no grupo SecureIP, defina os fatores para autenticação para os definidos em FactorGroup1.

3. Clique em Enviar.

4. Na resposta, confirme se Status: 200 OK aparece e se o corpo da resposta exibe detalhes sobre a regra criada. Anote o rulegid para referência posterior.

   

   Descrição da ilustração createrulesuccess.jpg

Criar Preferências do Usuário

Nesta seção, você cria um usuário user1 e registra suas preferências de fator.

1. Na guia Coleções, navegue até API REST de Autenticação Avançada da Oracle > API REST para Preferências do Usuário -> preferências/v1.

2. Selecione As Preferências do Usuário são criadas/registradas. Esta solicitação faz uma solicitação POST para o ponto final /oaa/runtime/preferences/v1. No Corpo, informe userId a ser criado e seu groupId correspondente. No exemplo abaixo, user1 é criado no grupo Default e registra o usuário para fatores de E-mail e OMATOTP. Altere o valor do endereço de e-mail para um endereço de e-mail válido. Altere secret_key para OMATOTP para um valor de sua escolha a ser usado no aplicativo Oracle Mobile Authenticator.

   

   Descrição da ilustração createuserprefs.jpg

3. Clique em Enviar.

4. Na resposta, confirme se o Status: 200 OK aparece e se o usuário e suas preferências são criados e registrados com sucesso.

   

   Descrição da ilustração createuserprefssuccess.jpg

Desafio do Usuário, Inicializar o Desafio e Validar

Nesta seção, você testa um desafio do usuário para user1 em relação à regra criada anteriormente em Criar Regra de Política. Se a regra for validada, os fatores registrados para esse usuário serão retornados. Depois de escolher um fator com o qual autenticar, uma solicitação de Inicialização será enviada para solicitar o OTP desse fator. Uma OTP de fator válido é informada e validada.

Antes de iniciar esta seção, certifique-se de que o Oracle Mobile Authenticator tenha uma conta Oracle adicionada com o valor Key definido como secret_key informado em Criar Preferências do Usuário. Consulte Configurando uma Conta no Oracle Mobile Authenticator

1. Na guia Coleções, navegue até API REST de Autenticação Avançada da Oracle > API REST para Desafio do Usuário -> Desafio do Usuário, Inicializar Desafio, Validar Desafio.

2. Selecione Desafio de Usuário. Esta solicitação faz uma solicitação POST para o ponto final /oaa/runtime/authn/v1. No Corpo, digite userId para user1 e seu groupId correspondente. No exemplo abaixo, o desafio será feito para user1 em relação ao Agente de Integração de API criado anteriormente em Criar API do Agente de Integração. Informe os valores para clientSecret e clientId para este agente de API. No ipAddr, informe um IP que foi definido no grupo SecureIP criado anteriormente:

   

   Descrição da ilustração desafuser.jpg

3. Clique em Enviar.

4. Na resposta, confirme se o Status: 200 OK é exibido. Uma mensagem OAA-40001 é retornada informando Authentication Required. Os fatores registrados em user1 (E-mail e OMATOTP) são retornados junto com um correlationId. Anote o correlationId a ser usado em solicitações subsequentes:

   

   Descrição da ilustração desafusersuccess.jpg

5. Em Usuário do Desafio, Inicializar Desafio, Validar Desafio, selecione Iniciar Desafio. Isso faz uma solicitação PUT para o ponto final /oaa/runtime/authn/v1. No Corpo, digite o correlationId retornado na resposta anterior. Neste exemplo, estamos selecionando para usar o fator OMATOTP:

   

   Descrição da ilustração initchallenge.jpg

6. Clique em Enviar.

7. Na resposta, confirme se o Status: 200 OK é exibido. Uma mensagem OAA-40001 é retornada informando Authentication Required para OMATOTP. Um valor nonce é retornado para o correlationId associado. Anote o valor nonce para usar a próxima solicitação:

   

   Descrição da ilustração initchallengesuccess.jpg

8. Em Usuário do Desafio, Inicializar Desafio, Validar Desafio, selecione Validar Desafio. Isso faz uma solicitação PUT para o ponto final /oaa/runtime/authn/v1. No Corpo, digite correlationId e nonce retornados na resposta anterior. Informe um OTP válido do Oracle Mobile Authenticator em ChallengeAnswer:

   

   Descrição da ilustração validate.jpg

9. Clique em Enviar.

10. Na resposta, confirme se o Status: 200 OK é exibido. Se a validação do OTP for bem-sucedida, uma mensagem OAA-40004 será retornada informando que o usuário é Authenticated:

    

    Descrição da ilustração validatesuccess.jpg

Saiba Mais

• Autenticação Avançada da Oracle
• API de Administração OAA
• API de Runtime do OAA
• Usar o Oracle RADIUS Agent com Autenticação Avançada da Oracle para Autenticação Multifator
• Integrar o Oracle Access Management ao Oracle Advanced Authentication

Feedback

Para fornecer feedback sobre este tutorial, entre em contato com [e-mail]

Agradecimentos

• Autor - Russ Hodgson

Mais Recursos de Aprendizagem

Explore outros laboratórios em docs.oracle.com/learn ou acesse mais conteúdo de aprendizado gratuito no canal YouTube do Oracle Learning. Além disso, visite education.oracle.com/learning-explorer para se tornar um Oracle Learning Explorer.

Para obter a documentação do produto, visite o Oracle Help Center.

---

Título e Informações de Copyright

Use Oracle Advanced Authentication REST APIs with Postman

F53391-01

February 2022

Copyright © 2022, Oracle and/or its affiliates.