Uso de las API de REST de autenticación avanzada de Oracle con Postman

Introducción

En este tutorial se muestra cómo realizar llamadas de API de REST a la autenticación avanzada de Oracle mediante Postman, software utilizado normalmente para pruebas de API de REST.

Objetivos

Las API de REST de autenticación avanzada de Oracle ofrecen una forma de integrar la autenticación avanzada de Oracle con clientes REST para que puedan configurar y administrar la autenticación avanzada de Oracle. Para obtener una lista completa de los puntos finales de la API de REST, consulte la API de administración de OAA.

En este tutorial aprenderá a descargar e importar la recopilación Postman de autenticación avanzada de Oracle y a probar algunas de las solicitudes Postman más comunes.

Requisitos

Para completar este tutorial, necesitará lo siguiente:

Instalación de Oracle Advanced Authentication Postman Collection

Configuración de los parámetros del entorno en Postman

  1. Abra Postman y seleccione Archivo > Importar.

  2. En el cuadro de diálogo Importar, en el separador Archivo, seleccione Cargar archivos. Seleccione Oracle_Advanced_Authentication_Example_Environment.postman_environment.json y, a continuación, haga clic en Abrir.

  3. En el menú de la izquierda, haga clic en .

  4. En la lista de entornos mostrada, a la derecha del entorno de ejemplo de autenticación avanzada de Oracle, haga clic en los puntos suspensivos y, a continuación, en Duplicar.

    Descripción de la ilustración duplic_env.jpg

  5. En Copia del entorno de ejemplo de autenticación avanzada de Oracle, que aparece por encima del entorno original, haga clic en los puntos suspensivos y cambie el nombre a Oracle Advanced Authentication Environment for REST APIs.

  6. Actualice las variables de entorno para el nuevo entorno introduciendo los siguientes valores para Valor inicial y Valor actual. Cuando haya terminado, haga clic en Guardar y, a continuación, en X en el separador para cerrarlo:

    • oaa-admin: puerto de administrador y nombre de host de autenticación avanzada de Oracle, por ejemplo https://oaa.example.com
    • oaa-policy: puerto de política y nombre de host de autenticación avanzada de Oracle, por ejemplo https://oaa.example.com
    • oaa-runtime: puerto de tiempo de ejecución y nombre de host de autenticación avanzada de Oracle, por ejemplo https://oaa.example.com
    • RELEASENAME: RELEASENAME asignado a la configuración de autenticación avanzada de Oracle, por ejemplo oaainstall. Este es el valor transferido para common.deployment.name al instalar OAA.
    • oaapolicyapikey: oaapolicyapikey para la configuración de autenticación avanzada de Oracle, por ejemplo a5764d4ef6b71129f38a2d8ddc88b6060653d3c8. Este es el valor transferido para install.global.policyapikey al instalar OAA.
    • oaaapikey: oaaapikey para la configuración de autenticación avanzada de Oracle, por ejemplo a5764d4ef6b71129f38a2d8ddc88b6060653d3c8. Este es el valor transferido para install.global.uasapikey al instalar OAA.

    Nota: si no conoce las URL de oaa-admin, oaa-policy y oaa-runtime (spui), ejecute lo siguiente en el cluster de Kubernetes de OAA:

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

    A continuación, para cada pod, ejecute lo siguiente para obtener la URL:

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

    El entorno tendrá el aspecto siguiente:

    Descripción de la ilustración Environment.jpg

    Nota: los valores de URL del ejemplo anterior asumen una instalación de OAA mediante NodePort y, por lo tanto, los números de puerto para cada uno de los pods se definen en las URL. Si la instalación de OAA utiliza una entrada, utilice la URL de entrada en todos los casos.

  7. Haga clic en la lista desplegable Entorno y, a continuación, seleccione el entorno actualizado de la lista:

    Descripción de la ilustración Environment_selection.jpg

Importación de la recopilación Postman

  1. Para importar la recopilación posterior de API de REST de autenticación avanzada de Oracle, en la página principal de Postman, seleccione Archivo > Importar.

  2. En el cuadro de diálogo Importar, en el separador Archivo, seleccione Cargar archivos. Seleccione el archivo Oracle_Advanced_Authentication_REST_API.postman_collection.json y, a continuación, haga clic en Abrir y, a continuación, en Importar.

    Haga clic en Recopilaciones en el menú de la izquierda. La recopilación debe mostrarse de la siguiente manera:

    Descripción de la ilustración Collec.jpg

Probar las API de REST

En esta sección, ejecutará algunas de las solicitudes en la recopilación Postman para la autenticación avanzada de Oracle.

Nota: para evitar errores de verificación de certificados SSL, vaya a Archivo > Configuración y, en el separador General, defina Verificación de certificados SSL en Desactivado.

Crear un agente de integración de API

En esta sección, creará un agente de integración de API.

  1. En el separador Recopilaciones, vaya a API de REST de autenticación avanzada de Oracle > API de REST para definir entidades del sistema -> agent/v1.

  2. Seleccione Crear un nuevo agente de integración de API. Esta solicitud realiza una solicitud POST al punto final /oaa-policy/agent/v1 y crea un agente de integración de API denominado APIAgent según la información del cuerpo:

    Descripción de la ilustración createapiagent.jpg

  3. Haga clic en Enviar.

  4. En la respuesta, confirme que aparece Status: 200 OK y que el cuerpo de la respuesta muestra detalles sobre el agente de integración creado. Tome nota de la agentgid devuelta, ya que se utilizará en las siguientes secciones.

    Descripción de la ilustración createapiagentsuccess.jpg

Creación de un nivel de garantía

En esta sección, creará un nivel de garantía para el agente de integración creado.

  1. En el separador Recopilaciones, vaya a API de REST de autenticación avanzada de Oracle > API de REST para definir entidades del sistema -> AssuranceLevel/v1.

  2. Seleccione Definir nivel de garantía. Esta solicitud realiza una solicitud POST al punto final /oaa-policy/assuranceLevel/v1 y crea un nivel de garantía para el agente de integración denominado AssuranceLevel1. En el cuerpo, edite el valor de agentid para que coincida con el valor devuelto anteriormente:

    Descripción de la ilustración createassurancelvl.jpg

  3. Haga clic en Enviar.

  4. En la respuesta, confirme que aparece Status: 200 OK y que el cuerpo de la respuesta muestra detalles sobre el nivel de garantía creado.

    Descripción de la ilustración createassurancelvlsuccess.jpg

Creación de Grupos

En esta sección, creará un grupo de acciones para Factores y un grupo para direcciones IP. Estos grupos se asignarán posteriormente a una política y una regla para el agente de integración y el nivel de garantía creados anteriormente.

  1. En el separador Recopilaciones, vaya a API de REST de autenticación avanzada de Oracle > API de REST para definir entidades del sistema -> group/v1.

  2. Seleccione Crear nuevo grupo de factores. Esta solicitud realiza una solicitud POST al punto final /oaa-policy/group/v1 y crea un grupo para el agente denominado FactorRuleGrp1. En el cuerpo, edite el valor de agentid para que coincida con el valor devuelto anteriormente. En este ejemplo, el grupo define dos factores: ChallengeEmail y ChallengeOMATOTP:

    Descripción de la ilustración createfactorgrp.jpg

  3. Haga clic en Enviar.

  4. En la respuesta, confirme que aparece Status: 200 OK y que el cuerpo de la respuesta muestra detalles sobre el grupo creado. Tome nota de groupid, ya que se utilizará más adelante para asignar este grupo a una política.

    Descripción de la ilustración createfactorgrpsuccess.jpg

  5. En la recopilación actual en group/v1, seleccione Crear nuevo grupo de tipos de IP. Esta solicitud realiza una solicitud POST al punto final /oaa-policy/group/v1 y crea un grupo para el agente de integración denominado SecureIP. En el cuerpo, edite el valor de agentgid para que coincida con el valor devuelto anteriormente. En este ejemplo, la sección de valores establece las IP de 198.51.100.1 en 198.51.100.3:

    Descripción de la ilustración createipgrp.jpg

  6. Haga clic en Enviar.

  7. En la respuesta, confirme que aparece Status: 200 OK y que el cuerpo de la respuesta muestra detalles sobre el grupo creado. Tome nota de groupid, ya que se utilizará más adelante para asignar este grupo a una política.

    Descripción de la ilustración createipgrpsuccess.jpg

Crear política

En esta sección, creará una política para el nivel de garantía y el agente de integración creados anteriormente.

  1. En el separador Recopilaciones, vaya a API de REST de autenticación avanzada de Oracle > API de REST para definir entidades del sistema -> policy/v1.

  2. Seleccione Crear nueva política. Esta solicitud realiza una solicitud POST al punto final /oaa-policy/policy/v1 y crea una política para el agente de integración y el nivel de garantía creados anteriormente denominado Policy1. En el cuerpo, edite el valor de agentgid para que coincida con el valor devuelto anteriormente:

    Descripción de la ilustración createpolicy.jpg

  3. Haga clic en Enviar.

  4. En la respuesta, confirme que aparece Status: 200 OK y que el cuerpo de la respuesta muestra detalles sobre la política creada. Tome nota de policygid, ya que se utilizará posteriormente, asigne una regla a esta política.

    Descripción de la ilustración createpolicysuccess.jpg

Crear Regla de Política

En esta sección, creará una regla de política para la política.

  1. En el separador Recopilaciones, vaya a API de REST de autenticación avanzada de Oracle > API de REST para definir entidades del sistema -> policy/v1 -> {policygid} -> rule > {ruleid}.

  2. Seleccione Definir nueva regla para la política. Esta solicitud realiza una solicitud POST al punto final /oaa-policy/policy/v1/:policygid/rule. En el separador Parámetros, edite el valor de policygid para que coincida con el valor de la política devuelta anteriormente. En Body, en conditionMap, edite los valores en expression y values y defina en groupId del grupo SecureIP creado anteriormente. En results, defina el valor para action para que coincida con groupId del grupo FactorGroup1 creado anteriormente:

    Descripción de la ilustración createrule.jpg

    En lo que antecede, la regla indica que si la dirección IP del usuario final que realiza la solicitud de autenticación es una de las definidas en el grupo SecureIP, defina los factores para la autenticación en los definidos en FactorGroup1.

  3. Haga clic en Enviar.

  4. En la respuesta, confirme que aparece Status: 200 OK y que el cuerpo de la respuesta muestra detalles sobre la regla creada. Anote rulegid para obtener una referencia posterior.

    Descripción de la ilustración createrulesuccess.jpg

Crear preferencias de usuario

En esta sección, creará un usuario user1 y registrará sus preferencias de factor.

  1. En el separador Recopilaciones, vaya a API de REST de autenticación avanzada de Oracle > API de REST para preferencias de usuario -> preferences/v1.

  2. Seleccione User Preferences are created/registered (Las preferencias de usuario se crean/registran). Esta solicitud realiza una solicitud POST al punto final /oaa/runtime/preferences/v1. En el cuerpo, introduzca el userId que se va a crear y su groupId correspondiente. En el siguiente ejemplo, se crea user1 en el grupo Default y registra el usuario para los factores de correo electrónico y OMATOTP. Cambie el valor de la dirección de correo electrónico a una dirección de correo electrónico válida. Cambie secret_key para OMATOTP a un valor de su elección para utilizarlo en la aplicación Oracle Mobile Authenticator.

    Descripción de la ilustración createuserprefs.jpg

  3. Haga clic en Enviar.

  4. En la respuesta, confirme que aparece Status: 200 OK y que el usuario y sus preferencias se crean y registran correctamente.

    Descripción de la ilustración createuserprefssuccess.jpg

Comprobar al usuario, inicializar la comprobación y validar

En esta sección, probará una comprobación de usuario para user1 en la regla creada anteriormente en Crear regla de política. Si se valida la regla, se devuelven los factores registrados para ese usuario. Después de seleccionar un factor con el que autenticarse, se envía una solicitud de inicialización para solicitar la OTP para ese factor. A continuación, se introduce y valida un factor OTP válido.

Antes de iniciar esta sección, asegúrese de que Oracle Mobile Authenticator tiene una cuenta de Oracle agregada con Key definida en el valor secret_key introducido en Crear preferencias de usuario. Consulte Configuring an Account in Oracle Mobile Authenticator

  1. En el separador Recopilaciones, vaya a API de REST de autenticación avanzada de Oracle > API de REST para comprobación de usuario -> Desafío de usuario, comprobación de inicialización, comprobación de validación.

  2. Seleccione Usuario de Comprobación. Esta solicitud realiza una solicitud POST al punto final /oaa/runtime/authn/v1. En el cuerpo, introduzca userId para user1 y su correspondiente groupId. En el siguiente ejemplo, se realizará el desafío para user1 en el agente de integración de API que ha creado anteriormente en Crear API de agente de integración. Introduzca los valores para clientSecret y clientId para este agente de API. En ipAddr, introduzca una IP definida en el grupo SecureIP creado anteriormente:

    Descripción de la ilustración desafuser.jpg

  3. Haga clic en Enviar.

  4. En la respuesta, confirme que aparece Status: 200 OK. Se devuelve un mensaje OAA-40001 que indica Authentication Required. Los factores registrados en user1 (correo electrónico y OMATOTP) se devuelven junto con correlationId. Tome nota de correlationId para utilizar en solicitudes posteriores:

    Descripción de la ilustración desafusersuccess.jpg

  5. En Usuario de confirmación, Initalizar comprobación, Validar comprobación, seleccione Iniciar comprobación. Esto hace una solicitud PUT al punto final /oaa/runtime/authn/v1. En el cuerpo, introduzca correlationId devuelto en la respuesta anterior. En este ejemplo, estamos seleccionando utilizar el factor OMATOTP:

    Descripción de la ilustración initchallenge.jpg

  6. Haga clic en Enviar.

  7. En la respuesta, confirme que aparece Status: 200 OK. Se devuelve un mensaje OAA-40001 que indica Authentication Required para OMATOTP. Se devuelve un valor nonce para el correlationId asociado. Tome nota del valor nonce para utilizar la siguiente solicitud:

    Descripción de la ilustración initchallengesuccess.jpg

  8. En Usuario de confirmación, Initalizar comprobación, Validar comprobación, seleccione Validar comprobación. Esto hace una solicitud PUT al punto final /oaa/runtime/authn/v1. En el cuerpo, introduzca correlationId y nonce devueltos en la respuesta anterior. Introduzca una OTP válida de Oracle Mobile Authenticator en ChallengeAnswer:

    Descripción de la ilustración validate.jpg

  9. Haga clic en Enviar.

  10. En la respuesta, confirme que aparece Status: 200 OK. Si la validación de OTP se realiza correctamente, se devuelve un mensaje OAA-40004 que indica que el usuario es Authenticated:

    Descripción de la ilustración validatesuccess.jpg

Más información

Comentarios

Para proporcionar comentarios sobre este tutorial, póngase en contacto con idm_user_assistance_ww_grp@oracle.com

Agradecimientos

Más recursos de aprendizaje

Explore otras prácticas en docs.oracle.com/learn o acceda a contenido de aprendizaje más gratuito en el canal YouTube de Oracle Learning. Además, visite education.oracle.com/learning-explorer para convertirse en un explorador de formación de Oracle.

Para obtener documentación sobre los productos, visite Oracle Help Center.