Utiliser les API REST d'authentification avancée Oracle avec Postman

Introduction

Ce tutoriel vous explique comment effectuer des appels d'API REST vers Oracle Advanced Authentication à l'aide de Postman, logiciel généralement utilisé pour les tests d'API REST.

Objectifs

Les API REST d'authentification avancée Oracle permettent d'intégrer l'authentification avancée Oracle aux clients REST afin qu'ils puissent configurer et administrer l'authentification avancée Oracle. Pour obtenir la liste complète des adresses d'API REST, reportez-vous à API d'administration OAA.

Dans ce tutoriel, vous allez apprendre à télécharger et à importer la collection Postman d'authentification avancée Oracle et à tester certaines des demandes Postman les plus courantes.

Prérequis

Pour effectuer ce tutoriel, vous aurez besoin des éléments suivants :

Installation de la collection Postman d'authentification avancée Oracle

Définition des paramètres d'environnement dans Postman

  1. Ouvrez Postman et sélectionnez Fichier > Importer.

  2. Dans la boîte de dialogue Importer, dans l'onglet Fichier, sélectionnez Télécharger les fichiers. Choisissez Oracle_Advanced_Authentication_Example_Environment.postman_environment.json, puis cliquez sur Ouvrir.

  3. Dans le menu latéral gauche, cliquez sur .

  4. Dans la liste d'environnements affichée, à droite d'Oracle Advanced Authentication Example Environment, cliquez sur l'icône représentant des points de suspension, puis sur Dupliquer.

    Description de l'image duplic_env.jpg

  5. Dans Oracle Advanced Authentication Example Environment Copy, qui apparaît au-dessus de l'environnement d'origine, cliquez sur l'icône et renommez-la en Oracle Advanced Authentication Environment for REST APIs.

  6. Mettez à jour les variables d'environnement du nouvel environnement en entrant les valeurs suivantes pour Valeur initiale et Valeur actuelle. Une fois l'opération terminée, cliquez sur Enregistrer, puis sur X dans l'onglet pour la fermer :

    • oaa-admin : nom d'hôte et port d'administration Oracle Advanced Authentication, par exemple https://oaa.example.com
    • oaa-policy : nom d'hôte et port de stratégie Oracle Advanced Authentication, par exemple https://oaa.example.com
    • oaa-runtime : nom d'hôte et port d'exécution Oracle Advanced Authentication, par exemple https://oaa.example.com
    • RELEASENAME : RELEASENAME affecté à la configuration de l'authentification avancée Oracle, par exemple oaainstall. Il s'agit de la valeur transmise pour common.deployment.name lors de l'installation d'OAA.
    • oaapolicyapikey : oaapolicyapikey pour la configuration de l'authentification avancée Oracle, par exemple a5764d4ef6b71129f38a2d8ddc88b6060653d3c8. Il s'agit de la valeur transmise pour install.global.policyapikey lors de l'installation d'OAA.
    • oaaapikey : oaaapikey pour la configuration de l'authentification avancée Oracle, par exemple a5764d4ef6b71129f38a2d8ddc88b6060653d3c8. Il s'agit de la valeur transmise pour install.global.uasapikey lors de l'installation d'OAA.

    Remarque : si vous ne connaissez pas les URL pour oaa-admin, oaa-policy et oaa-runtime (spui), exécutez les opérations suivantes sur le cluster Kubernetes OAA :

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

    Pour chaque pod, exécutez la commande suivante pour obtenir l'URL :

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

    Voici un exemple de l'environnement :

    Description de l'image environment.jpg

    Remarque : les valeurs d'URL indiquées dans l'exemple ci-dessus supposent une installation OAA à l'aide de NodePort. Par conséquent, les numéros de port de chacun des pods sont définis dans les URL. Si l'installation OAA utilise une entrée, utilisez l'URL entrante dans tous les cas.

  7. Cliquez sur la liste déroulante Environnement, puis sélectionnez l'environnement mis à jour dans la liste :

    Description de l'image environment_selection.jpg

Importer la collection Postman

  1. Pour importer la collection Postman de l'API REST d'authentification avancée Oracle, dans la page principale Postman, sélectionnez Fichier > Importer.

  2. Dans la boîte de dialogue Importer, dans l'onglet Fichier, sélectionnez Télécharger les fichiers. Choisissez le fichier Oracle_Advanced_Authentication_REST_API.postman_collection.json, puis cliquez sur Ouvrir et Importer.

    Cliquez sur Collections dans le menu de gauche. La collection doit s'afficher comme suit :

    Description de l'image Collections.jpg

Tester l'API REST

Dans cette section, vous allez exécuter certaines des demandes de la collection Postman pour Oracle Advanced Authentication.

Remarque : pour empêcher les erreurs de vérification de certificat SSL, accédez à Fichier > Paramètres et, dans l'onglet Général, définissez Vérification de certificat SSL sur OFF.

Création d'un agent d'intégration d'API

Dans cette section, vous allez créer un agent d'intégration d'API.

  1. Dans l'onglet Collections, accédez à API REST d'authentification avancée Oracle > API REST pour la définition des entités système -> agent/v1.

  2. Sélectionnez Créer un agent d'intégration d'API. Cette demande envoie une demande POST à l'adresse /oaa-policy/agent/v1 et crée un agent d'intégration d'API appelé APIAgent en fonction des informations contenues dans le corps :

    Description de l'image createapiagent.jpg

  3. Cliquez sur Envoyer.

  4. Dans la réponse, vérifiez que Status: 200 OK apparaît et que le corps de la réponse affiche les détails de l'agent d'intégration créé. Notez la valeur agentgid renvoyée car elle sera utilisée dans les sections suivantes.

    Description de l'image createapiagentsuccess.jpg

Créer un niveau d'assurance

Dans cette section, vous allez créer un niveau d'assurance pour l'agent d'intégration créé.

  1. Dans l'onglet Collections, accédez à API REST d'authentification avancée Oracle > API REST pour la définition des entités système -> AssuranceLevel/v1.

  2. Sélectionnez Définir le niveau d'assurance. Cette demande envoie une demande POST à l'adresse /oaa-policy/assuranceLevel/v1 et crée un niveau d'assurance pour l'agent d'intégration appelé AssuranceLevel1. Dans le corps, modifiez la valeur de agentid afin qu'elle corresponde à la valeur renvoyée précédemment :

    Description de l'image createassurancelvl.jpg

  3. Cliquez sur Envoyer.

  4. Dans la réponse, vérifiez que Status: 200 OK apparaît et que le corps de la réponse affiche des détails sur le niveau d'assurance créé.

    Description de l'image createassurancelvlsuccess.jpg

Créer des groupes

Dans cette section, vous allez créer un groupe d'actions pour les facteurs et un groupe pour les adresses IP. Ces groupes seront ensuite affectés à une stratégie et une règle pour l'agent d'intégration et le niveau d'assurance précédemment créés.

  1. Dans l'onglet Collections, accédez à API REST d'authentification avancée Oracle > API REST pour la définition des entités système -> group/v1.

  2. Sélectionnez Créer un groupe de facteurs. Cette demande envoie une demande POST à l'adresse /oaa-policy/group/v1 et crée un groupe pour l'agent nommé FactorRuleGrp1. Dans le corps, modifiez la valeur de agentid afin qu'elle corresponde à la valeur renvoyée précédemment. Dans cet exemple, le groupe définit deux facteurs : ChallengeEmail et ChallengeOMATOTP :

    Description de l'image createfactorgrp.jpg

  3. Cliquez sur Envoyer.

  4. Dans la réponse, vérifiez que Status: 200 OK apparaît et que le corps de la réponse affiche les détails du groupe créé. Notez la valeur groupid car elle sera utilisée ultérieurement pour affecter ce groupe à une stratégie.

    Description de l'image createfactorgrpsuccess.jpg

  5. Dans la collection actuelle sous group/v1, sélectionnez Créer un groupe de type IP. Cette demande envoie une demande POST à l'adresse /oaa-policy/group/v1 et crée un groupe pour l'agent d'intégration nommé SecureIP. Dans le corps, modifiez la valeur de agentgid afin qu'elle corresponde à la valeur renvoyée précédemment. Dans cet exemple, la section des valeurs définit l'adresse IP de 198.51.100.1 sur 198.51.100.3 :

    Description de l'image createipgrp.jpg

  6. Cliquez sur Envoyer.

  7. Dans la réponse, vérifiez que Status: 200 OK apparaît et que le corps de la réponse affiche les détails du groupe créé. Notez la valeur groupid car elle sera utilisée ultérieurement pour affecter ce groupe à une stratégie.

    Description de l'image createipgrpsuccess.jpg

Créer une stratégie

Dans cette section, vous allez créer une stratégie pour le niveau d'assurance et l'agent d'intégration précédemment créés.

  1. Dans l'onglet Collections, accédez à API REST d'authentification avancée Oracle > API REST pour la définition des entités système -> policy/v1.

  2. Sélectionnez Créer une stratégie. Cette demande envoie une demande POST à l'adresse /oaa-policy/policy/v1 et crée une stratégie pour l'agent d'intégration et le niveau de garantie précédemment créés, appelés Policy1. Dans le corps, modifiez la valeur de agentgid afin qu'elle corresponde à la valeur renvoyée précédemment :

    Description de l'image createpolicy.jpg

  3. Cliquez sur Envoyer.

  4. Dans la réponse, vérifiez que Status: 200 OK apparaît et que le corps de la réponse affiche les détails de la stratégie créée. Notez la valeur policygid car elle sera utilisée ultérieurement pour affecter une règle à cette stratégie.

    Description de l'image createpolicysuccess.jpg

Créer une règle

Dans cette section, vous allez créer une règle pour la stratégie.

  1. Dans l'onglet Collections, accédez à API REST d'authentification avancée Oracle > API REST pour la définition des entités système -> policy/v1 -> {policygid} -> rule > {ruleid}.

  2. Sélectionnez Définir une nouvelle règle pour la stratégie. Cette demande envoie une demande POST à l'adresse /oaa-policy/policy/v1/:policygid/rule. Dans l'onglet Paramètres, modifiez la valeur de policygid afin qu'elle corresponde à la valeur de la stratégie renvoyée précédemment. Dans le corps, sous conditionMap, modifiez les valeurs sous expression et values et définissez sur groupId du groupe SecureIP créé précédemment. Sous results, définissez la valeur de action de sorte qu'elle corresponde à la valeur groupId du groupe FactorGroup1 créé précédemment :

    Description de l'image createrule.jpg

    Dans ce qui précède, la règle indique que si l'adresse IP de l'utilisateur final effectuant la demande d'authentification est l'une de celles définies dans le groupe SecureIP, définissez les facteurs d'authentification sur ceux définis dans FactorGroup1.

  3. Cliquez sur Envoyer.

  4. Dans la réponse, vérifiez que Status: 200 OK apparaît et que le corps de la réponse affiche les détails de la règle créée. Notez rulegid pour référence ultérieure.

    Description de l'image createrulesuccess.jpg

Créer des préférences utilisateur

Dans cette section, vous créez un utilisateur user1 et enregistrez ses préférences de facteur.

  1. Dans l'onglet Collections, accédez à API REST d'authentification avancée Oracle > API REST pour les préférences utilisateur -> preferences/v1.

  2. Sélectionnez User Preferences are created/registered. Cette demande envoie une demande POST à l'adresse /oaa/runtime/preferences/v1. Dans le corps, entrez userId à créer et le groupId correspondant. Dans l'exemple ci-dessous, user1 est créé dans le groupe Default et enregistre l'utilisateur pour les facteurs Email et OMATOTP. Remplacez la valeur de l'adresse électronique par une adresse valide. Remplacez secret_key pour OMATOTP par la valeur de votre choix à utiliser dans l'application Oracle Mobile Authenticator.

    Description de l'image createuserprefs.jpg

  3. Cliquez sur Envoyer.

  4. Dans la réponse, vérifiez que l'élément Status: 200 OK apparaît et que l'utilisateur et ses préférences ont été créés et enregistrés.

    Description de l'image createuserprefssuccess.jpg

Challenge à l'utilisateur, initialiser la question d'authentification et valider

Dans cette section, vous testez une question de vérification utilisateur pour user1 par rapport à la règle créée précédemment dans Créer une règle de stratégie. Si la règle est validée, les facteurs enregistrés pour cet utilisateur sont renvoyés. Après avoir choisi un facteur avec lequel s'authentifier, une demande d'initialisation est envoyée pour demander le mot de passe à usage unique pour ce facteur. Un mot de passe à usage unique de facteur valide est ensuite saisi et validé.

Avant de démarrer cette section, assurez-vous qu'un compte Oracle est ajouté à Oracle Mobile Authenticator avec Key défini sur la valeur secret_key saisie dans Créer des préférences utilisateur. Reportez-vous à Configuration d'un compte dans Oracle Mobile Authenticator

  1. Dans l'onglet Collections, accédez à API REST d'authentification avancée Oracle > API REST pour la question de vérification utilisateur -> Défi Défi utilisateur, Initaliser la question de vérification, Valider la question de vérification.

  2. Sélectionnez Utilisateur du défi. Cette demande envoie une demande POST à l'adresse /oaa/runtime/authn/v1. Dans le corps, entrez userId pour user1 et le groupId correspondant. Dans l'exemple ci-dessous, la question de vérification sera appliquée à user1 par rapport à l'agent d'intégration d'API créé précédemment dans Créer une API d'agent d'intégration. Entrez les valeurs pour clientSecret et clientId pour cet agent d'API. Dans ipAddr, entrez une adresse IP définie dans le groupe SecureIP créé précédemment :

    Description de l'image challengeuser.jpg

  3. Cliquez sur Envoyer.

  4. Dans la réponse, vérifiez que Status: 200 OK apparaît. Un message OAA-40001 est renvoyé, indiquant Authentication Required. Les facteurs inscrits à user1 (Email et OMATOTP) sont renvoyés avec correlationId. Notez la valeur correlationId à utiliser dans les demandes suivantes :

    Description de l'image challengeusersuccess.jpg

  5. Sous Utilisateur du défi, Initialiser la question de vérification, Valider la question de vérification, sélectionnez Initialiser la question de vérification. Cette opération envoie une demande PUT à l'adresse /oaa/runtime/authn/v1. Dans Corps, entrez correlationId renvoyé dans la réponse précédente. Dans cet exemple, nous choisissons d'utiliser le facteur OMATOTP :

    Description de l'image initchallenge.jpg

  6. Cliquez sur Envoyer.

  7. Dans la réponse, vérifiez que Status: 200 OK apparaît. Un message OAA-40001 est renvoyé, indiquant Authentication Required pour OMATOTP. Une valeur nonce est renvoyée pour l'élément correlationId associé. Notez la valeur nonce pour utiliser la demande suivante :

    Description de l'image initchallengesuccess.jpg

  8. Sous Utilisateur du défi, Initialiser la question de vérification, Valider la question de vérification, sélectionnez Valider la question de vérification. Cette opération envoie une demande PUT à l'adresse /oaa/runtime/authn/v1. Dans Corps, entrez correlationId et nonce renvoyés dans la réponse précédente. Entrez un mot de passe à usage unique valide à partir d'Oracle Mobile Authenticator dans ChallengeAnswer :

    Description de l'image validate.jpg

  9. Cliquez sur Envoyer.

  10. Dans la réponse, vérifiez que Status: 200 OK apparaît. Si la validation du mot de passe à usage unique aboutit, un message OAA-40004 est renvoyé, indiquant que l'utilisateur est Authenticated :

    Description de l'image validatesuccess.jpg

En savoir plus

Commentaires

Pour faire part de vos commentaires sur ce tutoriel, veuillez contacter idm_user_assistance_ww_grp@oracle.com

Remerciements

Ressources de formation supplémentaires

Explorez d'autres exercices sur docs.oracle.com/learn ou accédez à davantage de contenu d'apprentissage gratuit sur le canal Oracle Learning YouTube. De plus, visitez le site education.oracle.com/learning-explorer pour devenir Oracle Learning Explorer.

Pour consulter la documentation du produit, consultez le centre d'aide Oracle.