Utilizza le API REST di autenticazione avanzata Oracle con Postman

Introduzione

Questa esercitazione descrive la procedura per effettuare chiamate API REST all'autenticazione avanzata Oracle mediante Postman, software in genere utilizzato per i test API REST.

Obiettivi

Le API REST dell'autenticazione avanzata Oracle consentono di integrare l'autenticazione avanzata Oracle con i client REST in modo da poter configurare e amministrare l'autenticazione avanzata Oracle. Per una lista completa degli endpoint API REST, consulta l'API di amministrazione OAA.

In questa esercitazione viene descritto come scaricare e importare la raccolta Postman dell'autenticazione avanzata Oracle e testare alcune delle richieste Postman più comuni.

Prerequisiti

Per completare questa esercitazione, è necessario quanto segue:

• Un'installazione di Oracle Advanced Authentication in esecuzione
• Oracle Mobile Authenticator installato su un dispositivo mobile
• Familiarità con lo stile architettura REST
• Client Postman nativo v8.0.6 o versione successiva installata
• I file json Oracle_Advanced_Authentication_REST_API.postman_collection.json, Oracle_Advanced_Authentication_Example_Environment.postman_environment.json

Installare la raccolta Postman di autenticazione avanzata di Oracle

Imposta i parametri di ambiente in Postman

1. Aprire Postman e selezionare File > Importa.

2. Nella finestra di dialogo Importa, nella scheda File selezionare Carica file. Scegliere Oracle_Advanced_Authentication_Example_Environment.postman_environment.json, quindi fare clic su Apri.

3. Nel menu a sinistra fare clic su .

4. Nella lista di ambienti visualizzata, a destra di Oracle Advanced Authentication Example Environment, fare clic sull'elipsis e quindi su Duplica.

   

   Descrizione dell'immagine duplicate_env.jpg

5. In Oracle Advanced Authentication Example Environment Copy, visualizzato sopra l'ambiente originale, fare clic sull'elisis e rinominare in Oracle Advanced Authentication Environment for REST APIs.

6. Aggiornare le variabili di ambiente per il nuovo ambiente immettendo i seguenti valori per Valore iniziale e Valore corrente. Una volta completato, fare clic su Salva, quindi su X nella scheda per chiuderla:

   • oaa-admin: nome host e porta di amministrazione dell'autenticazione avanzata Oracle, ad esempio https://oaa.example.com
   • oaa-policy: nome host e porta dei criteri dell'autenticazione avanzata Oracle, ad esempio https://oaa.example.com
   • oaa-runtime: nome host e porta runtime dell'autenticazione avanzata Oracle, ad esempio https://oaa.example.com
   • RELEASENAME: RELEASENAME assegnato all'impostazione dell'autenticazione avanzata Oracle, ad esempio oaainstall. Questo è il valore passato per common.deployment.name durante l'installazione di OAA.
   • oaapolicyapikey: oaapolicyapikey per l'impostazione dell'autenticazione avanzata Oracle, ad esempio a5764d4ef6b71129f38a2d8ddc88b6060653d3c8. Questo è il valore passato per install.global.policyapikey durante l'installazione di OAA.
   • oaaapikey: l'oaaapikey per l'impostazione dell'autenticazione avanzata Oracle, ad esempio a5764d4ef6b71129f38a2d8ddc88b6060653d3c8. Questo è il valore passato per install.global.uasapikey durante l'installazione di OAA.

   Nota: se non si conoscono gli URL per oaa-admin, oaa-policy e oaa-runtime (spui), eseguire le operazioni riportate di seguito nel cluster Kubernetes OAA.

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

   Quindi, per ogni pod eseguire le operazioni riportate di seguito per ottenere l'URL:

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

   L'ambiente sarà simile al seguente:

   

   Descrizione dell'immagine environment.jpg

   Nota: i valori URL nell'esempio precedente presuppongono un'installazione OAA che utilizza NodePort, pertanto i numeri di porta per ciascun pod sono definiti negli URL. Se l'installazione OAA utilizza un ingresso, utilizzare l'URL di entrata in tutti i casi.

7. Fare clic sull'elenco a discesa Ambiente, quindi selezionare l'ambiente aggiornato dall'elenco.

   

   Descrizione dell'immagine environment_selection.jpg

Importa la raccolta Postman

1. Per importare la raccolta Postman dell'API REST dell'autenticazione avanzata Oracle, nella pagina principale Postman selezionare File > Importa.

2. Nella finestra di dialogo Importa, nella scheda File selezionare Carica file. Scegliere il file Oracle_Advanced_Authentication_REST_API.postman_collection.json, quindi fare clic su Apri, quindi su Importa.

   Fare clic su Raccolte nel menu a sinistra. La raccolta dovrebbe presentare come segue:

   

   Descrizione dell'immagine Collections.jpg

Test delle API REST

In questa sezione verranno eseguite alcune richieste nella raccolta Postman per l'autenticazione avanzata di Oracle.

Nota: per evitare errori di verifica del certificato SSL, andare a File > Impostazioni e nella scheda Generale impostare Verifica certificato SSL su OFF.

Crea un agente di integrazione API

In questa sezione verrà creato un agente di integrazione API.

1. Nella scheda Raccolte passare a Oracle Advanced Authentication REST API > API REST per la definizione delle entità di sistema -> agent/v1.

2. Selezionare Crea un nuovo agente di integrazione API. Questa richiesta effettua una richiesta POST all'endpoint /oaa-policy/agent/v1 e crea un agente di integrazione API denominato APIAgent in base alle informazioni contenute nel corpo:

   

   Descrizione dell'immagine createapiagent.jpg

3. Fare clic su Invia.

4. Nella risposta confermare che viene visualizzato Status: 200 OK e che il corpo della risposta visualizzi i dettagli relativi all'agente di integrazione creato. Prendere nota di agentgid restituito perché verrà utilizzato nelle seguenti sezioni.

   

   Descrizione dell'immagine createapiagentsuccess.jpg

Crea un livello di garanzia

In questa sezione verrà creato un livello di garanzia per l'agente di integrazione creato.

1. Nella scheda Raccolte passare a Oracle Advanced Authentication REST API > API REST per la definizione delle entità di sistema -> AssuranceLevel/v1.

2. Selezionare Definisci livello di garanzia. Questa richiesta effettua una richiesta POST all'endpoint /oaa-policy/assuranceLevel/v1 e crea un livello di garanzia per l'agente di integrazione denominato AssuranceLevel1. Nel corpo, modificare il valore di agentid in modo che corrisponda al valore restituito in precedenza:

   

   Descrizione dell'immagine createassurancelvl.jpg

3. Fare clic su Invia.

4. Nella risposta confermare che viene visualizzato Status: 200 OK e che il corpo della risposta visualizzi i dettagli sul livello di garanzia creato.

   

   Descrizione dell'immagine createassurancelvlsuccess.jpg

Crea gruppi

In questa sezione verrà creato un gruppo di azioni per i fattori e un gruppo per gli indirizzi IP. Questi gruppi verranno successivamente assegnati a una polizza e a una regola per l'agente di integrazione e il livello di garanzia precedentemente creati.

1. Nella scheda Raccolte passare a Oracle Advanced Authentication REST API > API REST per la definizione delle entità di sistema -> group/v1.

2. Selezionare Crea nuovo gruppo di fattori. Questa richiesta effettua una richiesta POST all'endpoint /oaa-policy/group/v1 e crea un gruppo per l'agente denominato FactorRuleGrp1. Nel corpo, modificare il valore di agentid in modo che corrisponda al valore restituito in precedenza. In questo esempio il gruppo imposta due fattori: ChallengeEmail e ChallengeOMATOTP:

   

   Descrizione dell'immagine createfactorgrp.jpg

3. Fare clic su Invia.

4. Nella risposta confermare che viene visualizzato Status: 200 OK e che il corpo della risposta visualizzi i dettagli relativi al gruppo creato. Prendere nota di groupid, in quanto verrà utilizzato in un secondo momento per assegnare questo gruppo a un criterio.

   

   Descrizione dell'immagine createfactorgrpsuccess.jpg

5. Nella raccolta corrente sotto group/v1 selezionare Create new group of type IP's. Questa richiesta effettua una richiesta POST all'endpoint /oaa-policy/group/v1 e crea un gruppo per l'agente di integrazione denominato SecureIP. Nel corpo, modificare il valore di agentgid in modo che corrisponda al valore restituito in precedenza. In questo esempio la sezione dei valori imposta gli IP da 198.51.100.1 a 198.51.100.3:

   

   Descrizione dell'immagine createipgrp.jpg

6. Fare clic su Invia.

7. Nella risposta confermare che viene visualizzato Status: 200 OK e che il corpo della risposta visualizzi i dettagli relativi al gruppo creato. Prendere nota di groupid, in quanto verrà utilizzato in un secondo momento per assegnare questo gruppo a un criterio.

   

   Descrizione dell'immagine createipgrpsuccess.jpg

Crea criterio

In questa sezione verrà creato un criterio per il livello di garanzia e l'agente di integrazione creato in precedenza.

1. Nella scheda Raccolte passare a Oracle Advanced Authentication REST API > API REST per la definizione delle entità di sistema -> criterio/v1.

2. Selezionare Crea nuovo criterio. Questa richiesta effettua una richiesta POST all'endpoint /oaa-policy/policy/v1 e crea un criterio per l'agente di integrazione e il livello di garanzia creati in precedenza denominato Policy1. Nel corpo, modificare il valore di agentgid in modo che corrisponda al valore restituito in precedenza:

   

   Descrizione dell'immagine createpolicy.jpg

3. Fare clic su Invia.

4. Nella risposta confermare che viene visualizzato Status: 200 OK e che il corpo della risposta visualizzi i dettagli relativi al criterio creato. Prendere nota di policygid in quanto verrà utilizzata in seguito per assegnare una regola a questo criterio.

   

   Descrizione dell'immagine createpolicysuccess.jpg

Crea regola dei criteri

In questa sezione verrà creata una regola dei criteri per il criterio.

1. Nella scheda Raccolte selezionare API REST autenticazione avanzata Oracle > API REST per la definizione delle entità di sistema -> criterio/v1 -> {policygid} -> rule > {ruleid}.

2. Selezionare Definisci nuova regola per il criterio. Questa richiesta effettua una richiesta POST all'endpoint /oaa-policy/policy/v1/:policygid/rule. Nella scheda Parametri modificare il valore di policygid in modo che corrisponda al valore per il criterio restituito in precedenza. Nel corpo, in conditionMap modificare i valori in expression e values e impostarli su groupId del gruppo SecureIP creato in precedenza. In results impostare il valore per action in modo che corrisponda al valore groupId del gruppo FactorGroup1 creato in precedenza:

   

   Descrizione dell'immagine createrule.jpg

   Nella regola sopra riportata viene indicato che se l'indirizzo IP dell'utente finale che effettua la richiesta di autenticazione è uno di quelli definiti nel gruppo SecureIP, impostare i fattori per l'autenticazione su quelli definiti in FactorGroup1.

3. Fare clic su Invia.

4. Nella risposta confermare che viene visualizzato Status: 200 OK e che il corpo della risposta visualizzi i dettagli sulla regola creata. Prendere nota di rulegid per un riferimento successivo.

   

   Descrizione dell'immagine createrulesuccess.jpg

Crea preferenze utente

In questa sezione è possibile creare un utente user1 e registrare le relative preferenze di fattore.

1. Nella scheda Raccolte, passare a Oracle Advanced Authentication REST API > API REST per preferenze utente -> preferenze/v1.

2. Selezionare Le preferenze utente vengono create/registrate. Questa richiesta effettua una richiesta POST all'endpoint /oaa/runtime/preferences/v1. Nel corpo immettere il valore userId da creare e il relativo valore groupId. Nell'esempio seguente, user1 viene creato nel gruppo Default e registra l'utente per i fattori Email e OMATOTP. Modificare il valore dell'indirizzo e-mail in un indirizzo e-mail valido. Modificare il valore secret_key per OMATOTP impostandolo su un valore da utilizzare nell'applicazione Oracle Mobile Authenticator.

   

   Descrizione dell'immagine createuserprefs.jpg

3. Fare clic su Invia.

4. Nella risposta, verificare che venga visualizzato Status: 200 OK e che l'utente e le relative preferenze siano stati creati e registrati correttamente.

   

   Descrizione dell'immagine createuserprefssuccess.jpg

Richiesta di verifica per l'utente, inizializzazione della richiesta di verifica e convalida

In questa sezione viene eseguito il test di una richiesta di verifica utente per user1 rispetto alla regola creata in precedenza in Crea regola criteri. Se la regola viene convalidata, vengono restituiti i fattori registrati per l'utente. Dopo aver scelto un fattore con cui eseguire l'autenticazione, viene inviata una richiesta di inizializzazione per richiedere l'OTP per tale fattore. Viene quindi immesso e convalidato un OTP fattore valido.

Prima di avviare questa sezione, assicurarsi che Oracle Mobile Authenticator disponga di un account Oracle aggiunto con il valore Key impostato sul valore secret_key immesso in Crea preferenze utente. Vedere Configurazione di un account in Oracle Mobile Authenticator

1. Nella scheda Raccolte, passare a API REST di autenticazione avanzata Oracle > API REST per richieste di verifica utente -> Utente di verifica, Initalizza richiesta di verifica, Convalida richiesta di verifica.

2. Selezionare Utente richiesta di verifica. Questa richiesta effettua una richiesta POST all'endpoint /oaa/runtime/authn/v1. Nel corpo immettere il valore userId per user1 e il relativo valore groupId. Nell'esempio riportato di seguito verrà eseguita la richiesta di verifica per user1 rispetto all'agente di integrazione API creato in precedenza in Crea API agente integrazione. Immettere i valori per clientSecret e clientId per questo agente API. In ipAddr immettere un IP definito nel gruppo SecureIP creato in precedenza:

   

   Descrizione dell'immagine challengeuser.jpg

3. Fare clic su Invia.

4. Nella risposta confermare che viene visualizzato Status: 200 OK. Viene restituito un messaggio OAA-40001 con l'indicazione Authentication Required. I fattori registrati in user1 (e-mail e OMATOTP) vengono restituiti insieme a correlationId. Prendere nota di correlationId da utilizzare nelle richieste successive:

   

   Descrizione dell'immagine challengeusersuccess.jpg

5. In Challenge User, Initalize Challenge, Validation Challenge selezionare Initialze Challenge. In questo modo viene effettuata una richiesta PUT all'endpoint /oaa/runtime/authn/v1. Nel corpo immettere il valore correlationId restituito nella risposta precedente. In questo esempio si sceglie di utilizzare il fattore OMATOTP:

   

   Descrizione dell'immagine initchallenge.jpg

6. Fare clic su Invia.

7. Nella risposta confermare che viene visualizzato Status: 200 OK. Viene restituito un messaggio OAA-40001 con l'indicazione Authentication Required per OMATOTP. Viene restituito un valore nonce per il file correlationId associato. Prendere nota del valore nonce per utilizzare la richiesta successiva:

   

   Descrizione dell'immagine initchallengesuccess.jpg

8. In Challenge User, Initalize Challenge, Validation Challenge selezionare Convalida sfida. In questo modo viene effettuata una richiesta PUT all'endpoint /oaa/runtime/authn/v1. Nel corpo immettere correlationId e nonce restituito nella risposta precedente. Immettere un OTP valido da Oracle Mobile Authenticator in ChallengeAnswer:

   

   Descrizione dell'immagine validate.jpg

9. Fare clic su Invia.

10. Nella risposta confermare che viene visualizzato Status: 200 OK. Se la convalida dell'OTP riesce, viene restituito un messaggio OAA-40004 che indica che l'utente è Authenticated:

    

    Descrizione dell'immagine validatesuccess.jpg

Per saperne di più

• Oracle Advanced Authentication
• API di amministrazione OAA
• API runtime OAA
• Usa agente Oracle RADIUS con l'autenticazione avanzata Oracle per l'autenticazione con più fattori
• Integra Oracle Access Management con l'autenticazione avanzata Oracle

Feedback

Per fornire un feedback su questa esercitazione, contattare [e-mail]

Riconoscimenti

• Autore - Russ Hodgson

Altre risorse di apprendimento

Esplora altri laboratori su docs.oracle.com/learn o accedi a più contenuti di apprendimento gratuito sul canale Oracle Learning YouTube. Inoltre, visitare education.oracle.com/learning-explorer per diventare Oracle Learning Explorer.

Per la documentazione del prodotto, visitare il sito Oracle Help Center.

---

Titolo e informazioni sul copyright

Use Oracle Advanced Authentication REST APIs with Postman

F53379-01

February 2022

Copyright © 2022, Oracle and/or its affiliates.