Nota

Accedi alle risorse protette in ORDS utilizzando un token JWT emesso dai domini IAM OCI

Introduzione

Oracle Cloud Infrastructure Identity and Access Management (OCI IAM) utilizza i domini di Identity per fornire funzioni di gestione delle identità e degli accessi come autenticazione, Single Sign-On (SSO) e gestione del ciclo di vita delle identità per OCI, nonché per applicazioni Oracle e non Oracle, su SaaS, in hosting sul cloud o in locale.

Oracle REST Data Services (ORDS) collega HTTPS e Oracle Database. ORDS, un'applicazione Java di livello intermedio, fornisce un'API REST di gestione del database, SQL Developer Web, un gateway PL/SQL, un SOA (Simple Oracle Document Access) per REST e la possibilità di pubblicare servizi Web RESTful per l'interazione con i dati e le stored procedure in Oracle Database.

La release 23.3 di ORDS introduce il supporto per JSON Web Token (JWT). Questi token al portatore consentono agli sviluppatori ORDS di delegare l'autenticazione e l'autorizzazione a qualsiasi provider di identità (IdP) conforme a OAuth2 per emettere un token di accesso JWT che ORDS può convalidare per fornire l'accesso alle risorse protette ORDS.

In questa esercitazione verrà descritto come accedere alle risorse protette in ORDS utilizzando un token JWT emesso dai domini IAM OCI. Per questa demo, utilizzeremo Oracle Autonomous Database in OCI, che viene fornito con un'applicazione ORDS preconfigurata e completamente gestita.

L'immagine seguente mostra la rappresentazione di alto livello dell'architettura della soluzione.

Diagramma architettura

Obiettivi

Prerequisiti

Nota: il dominio IAM OCI e il token JWT emesso da esso soddisfano tutti i requisiti di cui sopra.

Task 1: impostare ORDS per uno schema di database, definire gli endpoint API e configurare il controllo dell'accesso

  1. Eseguire il login a OCI Console, passare a Oracle Database e fare clic su Autonomous Database.

  2. Fare clic su Istanza Autonomous Database con provisioning eseguito, Azioni database e quindi su SQL.

  3. Eseguire la query seguente per assicurarsi di disporre di ORDS versione 23.3 o successiva, che supporta JWT.

    SELECT * FROM ORDS_METADATA.ORDS_VERSION;

    Versione ORDS

  4. Eseguire la query seguente per creare un utente (ordstest) e assegnare i privilegi necessari.

    CREATE USER ordstest IDENTIFIED BY "<Password>";
GRANT CONNECT, RESOURCE TO ordstest;
ALTER USER ordstest DEFAULT ROLE CONNECT, RESOURCE;

  5. Eseguire la query seguente per abilitare ORDS per lo schema per consentire la funzionalità API REST.

    BEGIN
 ORDS_ADMIN.ENABLE_SCHEMA(
     p_enabled => TRUE,
     p_schema => 'ordstest',
     p_url_mapping_type => 'BASE_PATH',
     p_url_mapping_pattern => 'ordstest',
     p_auto_rest_auth=> FALSE
 );
commit;
END;
/

  6. Eseguire la query seguente per creare una tabella denominata emp nello schema ordstest e inserire dati di esempio.

    CREATE TABLE ordstest.emp (
EMPNO NUMBER(4,0),
ENAME VARCHAR2(10 BYTE),
JOB VARCHAR2(9 BYTE),
MGR NUMBER(4,0),
HIREDATE DATE,
SAL NUMBER(7,2),
COMM NUMBER(7,2),
DEPTNO NUMBER(2,0),
CONSTRAINT PK_EMP PRIMARY KEY (EMPNO)
);

    Insert into ordstest.EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7369,'SMITH','CLERK',7902,to_date('17-DEC-80','DD-MON-RR'),800,null,20);
Insert into ordstest.EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7499,'ALLEN','SALESMAN',7698,to_date('20-FEB-81','DD-MON-RR'),1600,300,30);
Insert into ordstest.EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7521,'WARD','SALESMAN',7698,to_date('22-FEB-81','DD-MON-RR'),1250,500,30);
Insert into ordstest.EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7566,'JONES','MANAGER',7839,to_date('02-APR-81','DD-MON-RR'),2975,null,20);
Insert into ordstest.EMP (EMPNO,ENAME,JOB,MGR,HIREDATE,SAL,COMM,DEPTNO) values (7654,'MARTIN','SALESMAN',7698,to_date('28-SEP-81','DD-MON-RR'),1250,1400,30);

  7. Eseguire la query seguente per definire un modulo ORDS (demo) che conterrà gli endpoint API.

    BEGIN
  ORDS_ADMIN.DEFINE_MODULE(
     p_schema => 'ordstest',
     p_module_name => 'demo',
     p_base_path => '/demo/',
     p_items_per_page=> 1000,
     p_status => 'PUBLISHED',
     p_comments=> ''
 );
COMMIT;
END;
/

  8. Eseguire la query seguente per definire un modello emp mappato a una risorsa REST specifica.

    BEGIN
 ORDS_ADMIN.DEFINE_TEMPLATE(
     p_schema => 'ordstest',
     p_module_name => 'demo',
     p_pattern => 'emp',
     p_priority => 0,
     p_etag_type => 'HASH',
     p_comments => ''
 );
COMMIT;
END;
/

  9. Eseguire la query seguente per creare un handler di richieste GET per emp, che esegue una query SQL semplice che restituisce i dati dalla tabella emp.

    BEGIN
 ORDS_ADMIN.DEFINE_HANDLER(
     p_schema => 'ordstest',
     p_module_name => 'demo',
     p_pattern => 'emp',
     p_method => 'GET',
     p_source_type => ords.source_type_collection_feed,
     p_source => 'select * from emp',
     p_items_per_page => 25,
     p_comments => ''
 );
COMMIT;
END;
/

    La tabella emp può essere visualizzata senza autenticazione aggiungendo /ordstest/demo/emp all'URL di accesso pubblico ORDS dei database autonomi Oracle, disponibile nella sezione Configurazione degli strumenti. Postman è utilizzato in questo tutorial.

    URL ORDINI

    Accesso senza autorizzazione

  10. Eseguire la query seguente per definire un privilegio (privilegetest) per proteggere il modulo demo.

    DECLARE
L_PRIV_ROLES owa.vc_arr;
L_PRIV_PATTERNS owa.vc_arr;
L_PRIV_MODULES owa.vc_arr;
BEGIN
L_PRIV_MODULES( 1 ) := 'demo';
ORDS_ADMIN.DEFINE_PRIVILEGE(
  P_Schema=> 'ordstest',
  P_PRIVILEGE_NAME => 'privilegetest',
  P_ROLES => L_PRIV_ROLES,
  P_PATTERNS =>  L_PRIV_PATTERNS,
  P_MODULES => L_PRIV_MODULES,
  P_LABEL => 'privilegetest',
  P_DESCRIPTION => 'Demonstrate controlling access with priviliges',
  P_COMMENTS=> ''
  );
COMMIT;
END;
/

    Poiché il modulo demo è protetto dal privilegio privilegetest, non è possibile accedervi senza un'autorizzazione appropriata. Per abilitare l'accesso, è necessario creare un profilo JWT per lo schema ordstest. Ciò consente a ORDS di convalidare i token del portatore JWT e concedere l'accesso a risorse protette, ad esempio il modulo demo.

Task 2: creare un profilo JWT ORDS

È possibile creare un profilo JWT all'interno di uno schema abilitato per REST utilizzando la procedura OAUTH.CREATE_JWT_PROFILE. È tuttavia possibile definire un solo profilo JWT per schema. Per aggiornare un profilo JWT esistente, è necessario eliminarlo prima di crearne uno nuovo.

BEGIN
  OAUTH_ADMIN.DELETE_JWT_PROFILE(p_schema=>'ordstest');
  OAUTH_ADMIN.CREATE_JWT_PROFILE(
  p_schema => 'ordstest',
  p_issuer => 'https://idcs-123456789abcdefghijklmnopqrstuvw.identity.oraclecloud.com',
  p_audience => 'ords/ordstest/',
  p_jwk_url =>'https://idcs-123456789abcdefghijklmnopqrstuvw.identity.oraclecloud.com:443/admin/v1/SigningCert/jwk'
 );
COMMIT;
END;
/

Questo profilo JWT specifica l'emittente, l'audience e l'URL JWK.

È possibile ottenere i valori Issuer e JWK URI per un dominio IAM OCI inviando una richiesta GET all'URL del dominio IAM OCI, aggiungendo /.well-known/openid-configuration, come mostrato nell'immagine seguente.

Metadati dominio IAM

Per verificare la configurazione del profilo JWT, eseguire il login come utente ordstest ed eseguire la query SQL seguente.

SELECT * FROM ORDS_METADATA.USER_ORDS_JWT_PROFILE;

Questa query recupera i dettagli del profilo JWT, garantendo che l'emittente, l'audience e l'URL JWK siano configurati correttamente.

Profilo JWT ORDS

Una volta configurato il profilo JWT, gli utenti finali possono accedere alle risorse protette ORDS presentando i token JWT emessi da un file IdP conforme alla versione OAuth 2.0, ad esempio il dominio IAM OCI specificato nel profilo JWT. Quando un token del portatore JWT viene convalidato correttamente, ORDS accetta quanto segue:

Task 3: abilitare l'accesso ORDS al certificato di firma del dominio IAM OCI senza autenticazione

  1. Andare alla console OCI, andare a Identità e sicurezza, Identità e fare clic su Domini.

  2. Fare clic sul nome del dominio di Identity che si desidera utilizzare. Potrebbe essere necessario modificare il compartimento per trovare il dominio desiderato. Fare clic su Impostazioni e Impostazioni dominio.

  3. Nella sezione Certificato di firma per l'accesso selezionare Configura accesso client e fare clic su Salva modifiche. Ciò consente a ORDS di accedere alla certificazione di firma per il dominio di Identity senza autenticazione.

    Certificato di firma

Task 4: Configura server risorse e client, ambiti JWT e privilegi ORDS

È necessario configurare IdP in modo che il JWT venga emesso con un ambito corrispondente al privilegio ORDS richiesto. Se una risorsa in ORDS è protetta da un privilegio, è necessario definire tale nome di privilegio come ambito. Questo ambito consente all'applicazione di richiedere l'accesso per conto dell'utente. Il JWT emesso deve quindi includere l'ambito come reclamo. Poiché utilizzeremo i servizi OAuth2 IAM OCI per applicare l'autorizzazione, è necessario impostare alcuni server e client di risorse.

Task 4.1: Creare un'applicazione riservata di tipo Server risorse con l'audience e gli ambiti desiderati

  1. Andare al dominio di Identity in cui si sta lavorando e fare clic su Applicazioni integrate.

  2. Selezionare Aggiungi applicazione, Applicazione riservata e fare clic su Avvia workflow.

  3. Immettere un nome per l'applicazione (ad esempio, ORDS-SERVER) e fare clic su Avanti.

  4. Nella sezione Configurazione del server risorse, selezionare Configurare questa applicazione come server risorse ora.

  5. Configurare il server delle risorse con audience principale corrispondente al profilo JWT e ambito corrispondente al privilegio ORDS.

    Configurazione server risorse

  6. Fare clic su Avanti e Fine.

  7. Nella pagina di panoramica dell'applicazione selezionare Attiva e confermare che si desidera attivare l'applicazione. L'applicazione riservata viene attivata.

Task 4.2: Creare un'applicazione riservata di tipo Client a cui sono assegnati gli ambiti desiderati

  1. Andare al dominio di Identity in cui si sta lavorando e fare clic su Applicazioni integrate.

  2. Selezionare Aggiungi applicazione, Applicazione riservata e fare clic su Avvia workflow.

  3. Immettere un nome per l'applicazione (ad esempio, ORDS-CLIENT) e fare clic su Avanti.

  4. Nella sezione Configurazione client selezionare Configurare l'applicazione come client ora.

  5. Nella sezione Autorizzazione selezionare Credenziali client.

    Nota: in questa esercitazione viene utilizzato Credenziali client come Tipi di concessione. È possibile selezionare un tipo di privilegio diverso in base ai requisiti, ad esempio Flusso codice autorizzazione per un client rivolto all'utente.

  6. In Tipo di client selezionare Riservato.

  7. Nella sezione Criterio di emissione token, selezionare Specifico come Risorse autorizzate.

  8. Fare clic su Aggiungi risorse e in Risorse selezionare Aggiungi ambito. Selezionare gli ambiti desiderati per il server risorse creato nel task 4.1. Ad esempio, privilegetest.

    Configurazione client

  9. Fare clic su Avanti e Fine.

  10. Nella pagina Panoramica applicazione, selezionare Attiva e confermare che si desidera attivare l'applicazione. L'applicazione riservata viene attivata.

  11. Copiare i valori ID client e Secondario client di questa applicazione client. Queste credenziali saranno necessarie per l'autenticazione.

Task 5: Invia richieste a ORDS utilizzando un token del servizio di trasporto JWT

Inviare una richiesta successiva (utilizzando Postman) all'endpoint del token del dominio IAM OCI con Tipo di concessione client_credentials e Ambito privilegetest come mostrato nell'immagine seguente.

Endpoint token

Nota: l'audience e l'ambito devono essere inclusi nel campo dell'ambito quando si richiede il token al portatore dal dominio IAM OCI.

Credenziali client

Convalidare il token JWT per ambiti, emittente e audience.

Dettagli token JWT

Ora è possibile accedere alla risorsa ORDS protetta (modulo demo) nello schema ordstest fornendo un token JWT bearer valido con la richiesta get, come mostrato nella seguente immagine.

Accesso con JWT

ORDS convalida il token recuperando la chiave pubblica dall'URL JWK e verificando la firma del token. Se la firma è valida, ORDS verifica se le richieste iss (emittente) e aud (pubblico) corrispondono a quelle definite nel profilo JWT. Verifica inoltre che la richiesta di ambito corrisponda al privilegio che protegge la risorsa. Se vengono soddisfatte tutte le condizioni, all'utente viene concesso l'accesso alla risorsa protetta.

Conferme

Altre risorse di apprendimento

Esplora altri laboratori su docs.oracle.com/learn o accedi a più contenuti gratuiti sulla formazione su Oracle Learning YouTube channel. Inoltre, visita education.oracle.com/learning-explorer per diventare un Oracle Learning Explorer.

Per la documentazione del prodotto, visita l'Oracle Help Center.