Come configurare OAuth 2.0 per un servizio REST in Oracle APEX

Una delle funzionalità più interessanti che offre Oracle APEX è quella di poter creare e pubblicare servizi RESTful utilizzando Oracle REST Data Services (ORDS).

In questo articolo ti ho mostrato come realizzare in pochi minuti un web service in grado di leggere e scrivere dati dal database Oracle e ti ho fatto vedere come puoi proteggere i tuoi dati da un uso non autorizzato implementando un meccanismo di autenticazione di base (Basic Authentication).

Ora desidero spiegarti come configurare l’autenticazione basata su protocollo OAuth 2.0 in Oracle APEX.

Che cos’è e come funziona il protocollo OAuth 2.0

Al giorno d’oggi tutti noi utilizziamo numerosi siti web e applicazioni mobile sia per lavoro che per motivi personali.

Con una tale varietà di piattaforme, è diventato normale per molti di noi condividere i contenuti di un’applicazione su un altro sito web: questo avviene, ad esempio, quando decidiamo di condividere automaticamente sul nostro profilo Facebook un post che abbiamo pubblicato sul nostro profilo Instagram.

Se ci pensi, durante questi processi viene trasferito un gran numero di informazioni e dati personali e pertanto la sicurezza della propria privacy diventa centrale.

Il protocollo di autorizzazione OAuth è stato progettato proprio per ridurre il rischio di un uso di dati non autorizzato.

OAuth 2 (abbreviazione di Open Authorization) è un protocollo standard aperto che consente alle applicazioni web di accedere alle risorse protette di un servizio per conto dell’utente. OAuth 2.0 definisce flussi di autorizzazione per applicazioni native, applicazioni Web e dispositivi mobili.

Questo significa, ad esempio, che se un’applicazione deve pubblicare per conto di un utente un post su Facebook (e quindi accedere all’API di Facebook), l’utente deve fornirle l’autorizzazione necessaria. Allo stesso modo, un’applicazione ha bisogno del permesso dell’utente per estrapolare informazioni sul suo profilo da un altro servizio.

Tramite il protocollo OAuth, l’utente può concedere tale delega (autorizzazione) senza dover fornire all’applicazione autorizzata username e password, mantenendo quindi il pieno controllo sui propri dati.

Molte aziende permettono ad applicazioni terze di collegarsi alle proprie api tramite OAuth: Google, Facebook, LinkedIn sono solo le prime che vengono in mente, ma anche Amazon e Microsoft figurano tra le grandi aziende che utilizzano OAuth come standard di delega di accesso per i loro servizi.

Quindi, come funziona il protocollo OAuth 2.0?

In generale, un processo di autorizzazione può essere descritto come segue:

1. L’applicazione invia all’Authorization Server una richiesta di autorizzazione per accedere tramite un’api REST ad una risorsa protetta.
2. Il proprietario della risorsa (di solito, l’utente) concede l’accesso.
3. L’Authorization Server restituisce un Access Token da utilizzare in tutte le successive richieste.

Questa è solo una rappresentazione ad alto livello dell’intero processo, il flusso effettivo potrà cambiare in base al tipo di grant utilizzato.

I due tipi di grant maggiormente utilizzati sono il Client Credentials grant e l’Authorization Code grant.

Autenticazione REST in Oracle APEX

In Oracle APEX oggi esistono due tipologie di autenticazione che puoi utilizzare per concedere l’accesso alle risorse della tua applicazione tramite api REST.

Il primo è tramite Autenticazione Base (Basic Authentication): per usare il servizio è necessario fornire username e password. Nel caso che ad accedere ai servizi rest deve essere una applicazione, significa che quest’ultima deve conservare localmente le credenziali di accesso

Il secondo metodo, che implementeremo in questo articolo, è basato sul grant OAuth 2.0 Client Credentials che è uno delle quattro tipologie di grants (Grant Type) previste dal protocollo OAuth 2.0.

In questo caso l’Authorization Server concede l’accesso all’applicazione piuttosto che all’utente. Per utilizzare questo flusso, l’applicazione che deve accedere alla risorsa HTTP deve essere registrata assegnandole un client ID e un client secret.

Questi parametri sono generati dall’Authorization Server e sono necessari per garantire che il client che si connette sia effettivamente chi dice di essere.

Prima di Iniziare

Prima di attivare l’autenticazione OAuth 2.0 è necessario che tu abbia già creato un’api REST.

Se non lo hai già fatto, leggi prima questo tutorial su come creare un servizio REST in Oracle APEX.

Per implementare l’autenticazione con OAuth 2.0 Client Credentials dovremo fare le seguenti attività:

1. Creare un ruolo
2. Creare un privilegio ed assegnarlo al ruolo
3. Registrare l’applicazione client che desidera connettersi alla nostra APP: come risultato di questa operazione otterremo le chiave privata e pubblica che l’applicazione client dovrà usare per accedere al servizio REST
4. Assegnare il ruolo al client.

Solo dopo aver eseguito questi passaggi potremo finalmente testare l’autenticazione generando di un Access Token che l’app client dovrà utilizzare per usare le api REST.

Se hai letto questo articolo, dovresti aver già fatto gli step 1 e 2 che riporto qui sotto per comodità.

Creare un ruolo

• Accedi ad Oracle APEX e vai in SQL Workshop > RESTful Services

• Seleziona il nodo Roles. Qui puoi vedere diversi ruoli, molti dei quali generati automaticamente da APEX.
• Clicca Create Role e inserisci un nuovo ruolo che si chiamerà oracle.dbtools.role.autorest.<WORKSPACE>.EMPLOYEE

Creare un privilegio

• Seleziona il nodo Privileges.

• Clicca Create Privilege ed inserisci le seguenti informazioni
  • Name: oracle.dbtools.autorest.privilege.<WORKSPACE>.EMPLOYEE
  • Title: employee

• Vai alla sezione Roles ad assegna a questo privilegio il ruolo che abbiamo creato allo step precedente.

• Vai alla sezione Protected Modules ed assegna il modulo REST che stiamo creando in questo momento.

Registrare l’APP Client

• Accedi ad Oracle APEX e vai in SQL Workshop > SQL Commands.

• Per registrare il client utilizzeremo uno script PL-SQL che richiama la procedura standard oauth.create_client. Ecco il significato dei parametri:
  • p_name: è il nome che verrà dato al Client che utilizzerà le api REST. Deve essere univoco.
  • p_grant_type: devi indicare uno tra i metodi previsti: authorization_code, implicit, o client_credentials
  • p_description: una descrizione del client
  • p_support_email: una e-mail di supporto che gli utilizzatori del cliente possono utilizzare
  • p_privilege_names: elenco dei privilegi separati da virgole a cui il Client vuole accedere

begin 
    oauth.create_client(
    p_name => 'any_name_you_want',
    p_grant_type => 'client_credentials',
    p_description => 'any_description_you_want',
    p_support_email => 'your_email', 
    p_privilege_names => 'privilege name');

    commit; 
end; 

• Modifica lo script inserendo i parametri specifici che hai usato per configurare la tua api REST. Nel mio caso questo è lo script finale:

begin 
    oauth.create_client(
        p_name => 'appin5minuti_client', 
        p_grant_type => 'client_credentials', 
        p_description => 'client demo', 
        p_support_email => 'daniele.trasarti@appin5minuti.com', 
        p_privilege_names => 'oracle.dbtools.autorest.privilege.APPIN5MINUTI.EMPLOYEE'); 
    commit; 
end; 

• Esegui lo script premendo Run e verifica che venga completato con successo.

• Se tutto va come previsto, il sistema registrerà un nuovo client con una chiave pubblica (Client ID) ed una chiave privata (Client Secret). Queste due informazioni serviranno poi all’applicazione che deve accedere alle api REST per generare un token di accesso. Lo vedremo tra poco.
• Per recuperare il Client ID e il Client Secret esegui questa query

SELECT id, 
       name, 
       description, 
       client_id, 
       client_secret 
FROM   user_ords_clients 
WHERE  name = 'appin5minuti_client';

• Come risultato dovresti ottenere questo

Assegnare il ruolo al client

• Per assegnare il ruolo al client appena creato devi utilizzare lo script seguente

BEGIN
   oauth.grant_client_role(
      p_client_name => '<nome client>',
      p_role_name => '<nome ruolo>'
);
   commit;
end;

• Questo è quello che ho dovuto usare nel mio caso

BEGIN
   oauth.grant_client_role(
      p_client_name => 'appin5minuti_client',
      p_role_name => 'oracle.dbtools.role.autorest.APPIN5MINUTI.EMPLOYEE');
   commit;
end;

• Lancia lo script premendo Run e verifica che venga eseguito con successo

Come testare il client OAuth usando Postaman

Postaman è una applicazione web che consente di costruire, testare e documentare API.

Dopo esserti registrato gratuitamente puoi testare subito l’api rest sviluppata in APEX usando un Access Token.

• Accedi al Workspace di Postaman e clicca su Create New

• Seleziona HTTP Request

• Inserisci l’URI del servizio REST e premi Save

• Clicca su Auth e seleziona il tipo di autenticazione OAuth 2.0

• Inizialmente non ci sarà un Access Token. Tra poco ti farò vedere come generarlo.

• Vai alla sezione Configure New Token. Qui inseriremo le informazioni necessarie per recuperare l’Accesso Token.

• Token Name: opzionale, puoi inserire un nome per identificare il token.
• Grant Type: seleziona Client Credentials
• Access Token URL: devi inserire l’URI dell’Authentication Provider che in questo caso è proprio la nostra applicazione APEX. Il modo più veloce per recuperare questa URL consiste nel prendere l’URI del servizio e rimuovere l’ultima parte (dal Base Path del modulo in poi) ed aggiungere la stringa “/oauth/token“. Esempio:
  • URI API REST: https://hostname/ords/appin5minuti/employee/employee/:id
  • URI Access Token: https://hostname/ords/appin5minuti/oauth/token

• Client ID e Client Secret: inserisci chiave pubblica e privata che è stata generata prima.
• Premi Get New Access Token. Postman effettuerà una richiesta per ottenere il token.

• Se l’operazione va a buon fine dovresti ottenere questo risultato. Clicca Use Token.

• Ora che il token è stato caricato, puoi effettuare una richiesta

• Inserisci eventuali parametri e premi Send per fare una chiamata. Come puoi vedere dall’esempio sotto, Postaman è stato in grado di fare una chiamata REST e possiamo vedere la response.

Come collegarsi ad un API Rest OAuth da Oracle APEX

Per testare l’api REST abbiamo usato Postaman.

A questo punto una cosa interessante da fare potrebbe essere quella di collegare una applicazione APEX al servizio che abbiamo pubblicato pochi minuti fa usando l’autenticazione OAuth.

Ho già spiegato come configurare un’origine dati di tipo REST: in questo esempio ci concentreremo su come configurare la connessione quando è prevista una autenticazione basata su protocollo OAuth 2.0.

A tal proposito ho già creato una applicazione APEX che ho chiamato API Restful APP.

• Accedi all’App Builder e vai in Shared Components
• Seleziona Data Source > Rest Data Sources

• Configuriamo la connessione ad un’origine dati di tipo Rest. Clicca su Create Rest Data Source e seleziona l’opzione From Scratch.

• Dai un nome all’origine dati ed inserisci l’URI del servizio.
• Inserisci eventuali parametri che APEX utilizzerà per effettuare una prima connessione al servizio e clicca Next.

• Inserisci i parametri per l’autenticazione:
  • Authentication Type
  • OAuth Token URL
  • Client ID
  • Client Secret
• Clicca Discover

• Se la connessione va a buon fine, dovresti vedere dei risultati. Clicca Create REST Data Source per completare la configurazione dell’origine dati

A questo punto puoi creare una pagina APEX per visualizzare i dati restituiti dal web service.

Conclusioni

Al giorno d’oggi meccanismi di autenticazione più sofisticati come OAuth 2.0 sono quasi d’obbligo perché semplificano molto i processi di Identity Management e garantiscono la sicurezza degli account.

Fortunatamente Oracle APEX fornisce tutti gli strumenti necessari per implementarlo al meglio e, allo stesso tempo, ti permette di collegare una APP APEX a servizi esterni basati su questo protocollo.

Spero con tutto il cuore che queste informazioni ti siano utili.

Un abbraccio

Daniele