Informazioni sull'autenticazione tra le applicazioni Node.js e Oracle Identity Cloud Service

Informazioni sui flussi di autenticazione a tre fasi

Oracle Identity Cloud Service supporta il flusso di autenticazione a tre fasi per l'SDK Node.js. In questo flusso gli utenti interagiscono direttamente con Oracle Identity Cloud Service. Dopo che un utente si è connesso, Oracle Identity Cloud Service emette un codice di autorizzazione scambiato dall'SDK per un token di accesso utente. L'applicazione Web Node.js utilizza questo token di accesso per concedere agli utenti l'accesso alle risorse protette nell'applicazione. Il flusso a tre fasi utilizza il tipo di concessione del codice di autorizzazione.

Per aumentare la sicurezza, Oracle consiglia di utilizzare il flusso a tre fasi per integrare le applicazioni Web Node.js con Oracle Identity Cloud Service per l'autenticazione. Utilizzando il tipo di privilegio del codice di autorizzazione, è inoltre possibile accedere ad altre applicazioni protette da Oracle Identity Cloud Service senza dover eseguire nuovamente l'autenticazione.

Informazioni sui casi d'uso principali per l'uso di un SDK con un'applicazione Node.js

L'applicazione Web Node.js implementa due casi d'uso: uno per l'autenticazione degli utenti e l'altro per l'accesso a informazioni dettagliate sull'utente collegato.

I diagrammi di flusso dati riportati di seguito illustrano il flusso di eventi, chiamate e risposte tra il browser Web, l'applicazione Web e Oracle Identity Cloud Service per ogni caso d'uso.

Caso d'uso n. 1: autenticazione di un utente

Segue la descrizione dell'autenticazione user.png

Descrizione dell'immagine authenticate-user.png

Il flusso di dati avviene in questo modo:

L'utente richiede una risorsa protetta.
Il modulo di autenticazione utilizza l'SDK per generare un URL di codice di autorizzazione della richiesta per Oracle Identity Cloud Service e inviare questo URL come risposta di reindirizzamento al browser Web.
Il browser Web chiama l'URL.
Viene visualizzata la pagina Accedi Oracle Identity Cloud Service.
L'utente sottomette le credenziali di accesso a Oracle Identity Cloud Service.
Dopo aver eseguito l'accesso, Oracle Identity Cloud Service crea una sessione per l'utente ed emette un codice di autorizzazione.
L'applicazione web effettua una chiamata back-end (o server-to-server) per scambiare il codice di autorizzazione per un token di accesso.
Oracle Identity Cloud Service emette un token di accesso e un token ID.
Viene stabilita una sessione e l'utente viene reindirizzato alla home page.
Viene visualizzata la Home page dell'applicazione Web.

Caso d'uso n. 2: ottenere dettagli sull'utente

Descrizione dell'immagine get-details-user.png

Il flusso di dati avviene in questo modo:

L'utente richiede la risorsa /myProfile.
L'applicazione Web utilizza l'SDK di Oracle Identity Cloud Service per convalidare il token ID.
I dati restituiti dalla convalida del token ID contengono i dettagli dell'utente nel formato di un oggetto JSON.
La pagina Profilo personale visualizza l'oggetto JSON come contenuto HTML.

Informazioni su metodi e funzioni

L'SDK Node.js è una strategia di passaporto Node.js che si aggiunge alla cartella Node.js modules. Questo SDK si basa anche sulle promesse di Node.js.

Tutte le dipendenze di terze parti necessarie per l'SDK Node.js vengono definite nel file package.json dell'SDK all'interno del file zip dell'SDK Node.js scaricato dalla console di Oracle Identity Cloud Service. È necessario utilizzare almeno questo set di moduli nell'applicazione Web Node.js.

"dependencies": {
    "async": "^2.1.2",
    "bunyan": "^1.8.5",
    "cache-manager": "^2.2.0",
    "json-web-token": "^2.1.3",
    "jsonwebtoken": "^8.2.1",
    "jwk-to-pem": "^1.2.6",
    "jws": "^3.1.5",
    "lru": "^3.1.0",
    "passport": "^0.4.0",
    "promise": "^8.0.1",
    "querystring": "^0.2.0",
    "request": "^2.81.0",
    "rsa-pem-to-jwk": "^1.1.3",
    "util": "^0.10.3"
  },

Un'applicazione Web Node.js è stata sviluppata utilizzando i moduli Node.js express e express-handlebars, che implementano gli instradamenti URL sotto forma di funzione app.get() per ogni URL.

L'SDK Node.js richiede una variabile JSON caricata con le informazioni di connessione di Oracle Identity Cloud Service. L'applicazione Web Node.js utilizza la variabile ids per memorizzare le informazioni riportate di seguito.

var ids = {
    oracle: {
    "ClientId": "123456789abcdefghij'",
    "ClientSecret": "abcde-12345-zyxvu-98765-qwerty",
    "ClientTenant": "idcs-abcd1234",
    "IDCSHost": "https://%tenant%.identity.oraclecloud.com",
    "AudienceServiceUrl" : "https://idcs-abcd1234.identity.oraclecloud.com",
    "TokenIssuer": "https://identity.oraclecloud.com/",
    "scope": "urn:opc:idm:t.user.me openid",
    "logoutSufix": "/oauth2/v1/userlogout",
    "redirectURL": "http://localhost:3000/callback",
    "LogLevel":"INFO",
    "ConsoleLog":"True"
    }
};
module.exports = ids;

Di seguito è riportata una breve spiegazione di ciascun attributo obbligatorio per questo SDK.

Nome	Descrizione
`ClientId`	Il valore dell'ID client generato dopo la registrazione dell'applicazione Web Node.js nella console di Oracle Identity Cloud Service.
`ClientSecret`	Il valore del segreto client generato dopo la registrazione dell'applicazione Web Node.js nella console di Oracle Identity Cloud Service.
`ClientTenant`	Prefisso di dominio dell'istanza di Oracle Identity Cloud Service. Questo prefisso è in genere simile a `idcs-abcd1234`.
`IDCSHost`	Il suffisso di dominio dell'istanza di Oracle Identity Cloud Service. In fase di esecuzione, il segnaposto %tenant% viene sostituito dal valore dell'attributo ClientTenant.
`AudienceServiceUrl`	URL del nome dominio completamente qualificato dell'istanza di Oracle Identity Cloud Service.
`TokenIssuer`	Per questo attributo, Oracle consiglia di mantenere il valore `https://identity.oraclecloud.com/`.
`scope`	L'ambito controlla i dati ai quali l'applicazione può accedere o elaborare per conto dell'utente di Oracle Identity Cloud Service. Se l'applicazione utilizza l'SDK per autenticare un utente, l'ambito è `openid`. Se l'applicazione utilizza l'SDK per ottenere dettagli sull'utente, l'ambito è `urn:opc:idm:t.user.me openid`.
`ConsoleLog`	Abilita il log SDK.
`LogLevel`	Indica il livello di log del kit SDK.

L'applicazione utilizza sia gli attributi logoutSufix che redirectURL per evitare di codificare questi valori. L'SDK non ne ha bisogno.

L'applicazione Node.js implementa l'instradamento URL /oauth/oracle. Quando un utente esegue l'autenticazione con Oracle Identity Cloud Service, il browser Web invia una richiesta GET a questo URL. Questo instradamento utilizza l'SDK per generare l'URL di autorizzazione di Oracle Identity Cloud Service.

//Loading the configurations
var auth = require('./auth.js');
 
//Route for /oauth/oracle
app.get("/auth/oracle", function(req, res){
    //Authentication Manager loaded with the configurations.
    am = new IdcsAuthenticationManager(auth.oracle);
    //Using Authentication Manager to generate the Authorization Code URL, passing the
    //application's callback URL as parameter, along with code value and code parameter.
    am.getAuthorizationCodeUrl(auth.oracle.redirectURL, auth.oracle.scope, "1234", "code")
        .then(function(authZurl){
            //Redirecting the browser to the Oracle Identity Cloud Service Authorization URL.
            res.redirect(authZurl);
        }).catch(function(err){
            res.end(err);
        })
});

Questa funzione carica i parametri JSON in una variabile, inizializza un gestore di autenticazione e utilizza la funzione IdcsAuthenticationManager.getAuthorizationCodeUrl() dell'SDK Node.js per generare l'URL del codice di autorizzazione. Questa funzione utilizza la promessa di reindirizzare il browser Web dell'utente quando viene generato l'URL del codice di autorizzazione o di visualizzare un errore nel browser.

Per generare l'URL del codice di autorizzazione vengono utilizzati i parametri riportati di seguito.

Nome	Descrizione
`auth.oracle.redirectURL`	Dopo che un utente si è connesso, Oracle Identity Cloud Service reindirizza il browser Web dell'utente a questo URL. Questo URL deve corrispondere a quello che verrà configurato per l'applicazione sicura nella console di Identity Cloud Service. Per ulteriori informazioni sulla specifica di un URL di reindirizzamento per l'applicazione Web Node.js, vedere Registrare l'applicazione Node.js.
`auth.oracle.scope`	L'ambito di autenticazione OAuth o OpenID Connect. Questa applicazione richiede solo l'autenticazione `openid`.
`state`	Il protocollo OAuth definisce questo parametro. L'applicazione Web Node.js di esempio utilizza questo codice per verificare se è possibile stabilire una comunicazione con Oracle Identity Cloud Service. Per questo esempio, il valore di questo parametro è `1234`.
`response_type`	Parametro richiesto dal tipo di privilegio del codice di autorizzazione. Per questo esempio, il valore di questo parametro è `code`.

Dopo aver eseguito l'accesso, Oracle Identity Cloud Service reindirizza il browser Web dell'utente a un URL di callback, che lo sviluppatore deve implementare. L'applicazione Web Node.js utilizza l'instradamento /callback per gestire questa richiesta.

//Route for /callback
app.get("/callback", function(req,res){
    //Authentication Manager loaded with the configurations.
    var am = new IdcsAuthenticationManager(auth.oracle);
    //Getting the authorization code from the "code" parameter
    var authZcode = req.query.code;
    //Using the Authentication Manager to exchange the Authorization Code to an Access Token.
    am.authorizationCode(authZcode)
        .then(function(result){
            //Getting the Access and Id Token Values to set in the session.
            req.session.access_token = result.access_token;
            req.session.id_token = result.id_token;
            res.cookie(config.IDCS_COOKIE_NAME, result.access_token);
            res.header('idcs_user_assertion', result.access_token)
            res.redirect('/auth.html');
        }).catch(function(err){
            res.end(err);
        })
});

L'applicazione Node.js utilizza il codice di autorizzazione per richiedere un token di accesso. Il token di accesso viene memorizzato come cookie, che viene quindi inviato al browser Web per un uso futuro.

La funzione IdcsAuthenticationManager.authorizationCode() dell'SDK Node.js utilizza anche promise (un'istruzione then-catch) per impostare il token di accesso come cookie e per reindirizzare il browser alla pagina /auth.html.

L'SDK Node.js si basa sul framework del passaporto Node.js. Pertanto, il browser deve inoltrare il token di accesso come variabile di intestazione all'handler di URL /auth e utilizzare il metodo passport.authenticate() con il nome della strategia di Oracle Identity Cloud Service come parametro:

//Uses passport to create a User Session in Node.js.
//Passport sets a user attribute in the request as a json object.
app.get('/auth', passport.authenticate(config.IDCS_STRATEGY_NAME, {}), function(req, res) {
   res.redirect('/home');
});

Dopo che il metodo passport.authenticate() ha creato la sessione dell'applicazione, la funzione reindirizza il browser Web dell'utente a un URL protetto nell'applicazione /home. Oltre a /home, l'applicazione Web Node.js dispone di un altro URL protetto: /myProfile.

Qualsiasi URL protetto deve controllare se la sessione dell'utente è stata creata in precedenza. La funzione seguente viene utilizzata da ciascuna funzione app.get() per questi URL.

function ensureAuthenticated(req, res, next) {
   if (req.isAuthenticated()) {
      return next();
   }
   res.redirect('/login')
}

L'applicazione Node.js gestisce l'instradamento /myProfile e ottiene le informazioni impostate nella sessione, come indicato di seguito.

app.get("/myProfile", ensureAuthenticated, function(req,res){
   //User Manager loaded with the configurations
   var am = new IdcsAuthenticationManager(auth.oracle);
   //Validating id token to acquire information such as UserID, DisplayName, list of groups and AppRoles assigned to the user.
   am.validateIdToken(req.session['id_token'])
    .then(function(idToken){
      res.render('myProfile', {
         layout: 'privateLayout',
         title: 'My Profile',
         user: req.user,
         userInfo: JSON.stringify(idToken, null, 2)
         });
    }).catch(function(err1){
       res.end(err1);
   })
});

Dopo aver inizializzato l'oggetto IdcsAuthenticationManager, l'handler dell'instradamento /myProfile utilizza la funzione IdcsAuthenticationManager.validateIdToken() dell'SDK per acquisire informazioni utente quali nome visualizzato, ID utente e la lista di gruppi e ruoli applicazione assegnati all'utente. L'oggetto JSON viene quindi analizzato come stringa nel file myProfile.handlebars per il rendering nel browser Web.

Per disconnettere l'utente da Single Sign-On tra l'applicazione e Oracle Identity Cloud Service, l'applicazione Web Node.js implementa l'instradamento /logout, come riportato di seguito.

app.get('/logout', function(req, res){
  var id_token = req.session.id_token;
  var logouturl = auth.oracle.AudienceServiceUrl + auth.oracle.logoutSufix + '?post_logout_redirect_uri=http%3A//localhost%3A3000&id_token_hint='+ id_token;
  req.session.destroy(function(err) {
    if(err) {
      console.log(err);
    } else {
      req.logout();
      res.clearCookie();
      res.redirect(logouturl);
    }
  })
});

Questo instradamento invalida la sessione dell'applicazione, rimuove qualsiasi oggetto e cookie impostati in precedenza, quindi reindirizza il browser Web dell'utente all'URL di logout di Oracle Identity Cloud Service OAuth.