Informationen zur Authentifizierung zwischen Node.js-Anwendungen und Oracle Identity Cloud Service

Informationen zu Authentifizierungsabläufen mit drei Schlüsseln

Oracle Identity Cloud Service unterstützt den dreibeinigen Authentifizierungsfluss für das Node.js-SDK. In diesem Ablauf interagieren Benutzer direkt mit Oracle Identity Cloud Service. Nachdem sich ein Benutzer angemeldet hat, gibt Oracle Identity Cloud Service einen Autorisierungscode aus, den das SDK für ein Benutzerzugriffstoken austauscht. Die Webanwendung Node.js verwendet dieses Zugriffstoken, um Benutzern Zugriff auf die geschützten Ressourcen in der Anwendung zu erteilen. Der dreibeinige Ablauf verwendet den Berechtigungstyp für den Autorisierungscode.

Um die Sicherheit zu erhöhen, empfiehlt Oracle, die Node.js-Webanwendungen mit dem dreiteiligen Ablauf zur Authentifizierung in Oracle Identity Cloud Service zu integrieren. Mit dem Autorisierungscodezugriffsberechtigungstyp können Sie auch auf andere Anwendungen zugreifen, die durch Oracle Identity Cloud Service geschützt sind, ohne sich erneut authentifizieren zu müssen.

Informationen zu den primären Anwendungsfällen für die Verwendung eines SDK mit einer Node.js-Anwendung

Die Webanwendung Node.js implementiert zwei Anwendungsfälle: einen für die Authentifizierung von Benutzern und den anderen für den Zugriff auf detaillierte Informationen über den angemeldeten Benutzer.

Die folgenden Datenflussdiagramme veranschaulichen den Ablauf von Ereignissen, Aufrufen und Antworten zwischen dem Webbrowser, der Webanwendung und Oracle Identity Cloud Service für jeden Anwendungsfall.

Anwendungsfall 1: Benutzer authentifizieren

Beschreibung von authenticate-user.png folgt

Beschreibung der Abbildung authenticate-user.png

Der Datenfluss geschieht auf folgende Weise:

Der Benutzer fordert eine geschützte Ressource an.
Das Authentifizierungsmodul verwendet das SDK, um eine URL für den Anforderungsautorisierungscode für Oracle Identity Cloud Service zu generieren und diese URL als Umleitungsantwort an den Webbrowser zu senden.
Der Webbrowser ruft die URL auf.
Die Oracle Identity Cloud Service-Seite Anmelden wird angezeigt.
Der Benutzer leitet seine Oracle Identity Cloud Service-Anmeldezugangsdaten weiter.
Nachdem sich der Benutzer angemeldet hat, erstellt Oracle Identity Cloud Service eine Session für den Benutzer und gibt einen Autorisierungscode aus.
Die Webanwendung führt einen Backend-Aufruf (oder Server-zu-Server-Aufruf) durch, um den Autorisierungscode für ein Zugriffstoken auszutauschen.
Oracle Identity Cloud Service gibt ein Zugriffstoken und ein ID-Token aus.
Eine Session wird eingerichtet, und der Benutzer wird zur Homepage umgeleitet.
Die Seite Home der Webanwendung wird angezeigt.

Anwendungsfall #2: Details zum Benutzer abrufen

Beschreibung von get-details-user.png folgt

Beschreibung der Abbildung get-details-user.png

Der Datenfluss geschieht auf folgende Weise:

Der Benutzer fordert die Ressource /myProfile an.
Die Webanwendung verwendet das SDK von Oracle Identity Cloud Service, um das ID-Token zu validieren.
Die Daten, die von der ID-Tokenvalidierung zurückgegeben werden, enthalten Benutzerdetails im Format eines JSON-Objekts.
Auf der Seite Mein Profil wird das JSON-Objekt als HTML-Inhalt wiedergegeben.

Informationen zu Methoden und Funktionen

Das Node.js-SDK ist eine Node.js-Passstrategie, die Sie Ihrem Ordner Node.js modules hinzufügen. Dieses SDK basiert auch auf Node.js-Versprechungen.

Alle Drittanbieterabhängigkeiten, die das Node.js-SDK benötigt, werden in der package.json-Datei des SDK in der ZIP-Datei des SDK Node.js definiert, die Sie von der Oracle Identity Cloud Service-Konsole herunterladen. Sie müssen mindestens diese Gruppe von Modulen in der Node.js-Webanwendung verwenden.

"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"
  },

Eine Node.js-Webanwendung wurde mit den Modulen Node.js express und express-handlebars entwickelt, die URL-Routen in Form einer app.get()-Funktion für jede URL implementiert.

Das Node.js-SDK erfordert eine JSON-Variable, die mit Oracle Identity Cloud Service-Verbindungsinformationen geladen ist. Die Webanwendung Node.js verwendet die Variable ids, um diese Informationen zu speichern:

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;

Im Folgenden finden Sie eine kurze Erläuterung der einzelnen erforderlichen Attribute für dieses SDK:

Name	Beschreibung
`ClientId`	Der Wert der Client-ID, die generiert wird, nachdem Sie die Node.js-Webanwendung in der Oracle Identity Cloud Service-Konsole registriert haben.
`ClientSecret`	Der Wert des Client Secret, das generiert wird, nachdem Sie die Node.js-Webanwendung in der Oracle Identity Cloud Service-Konsole registriert haben.
`ClientTenant`	Das Domainpräfix der Oracle Identity Cloud Service-Instanz. Dieses Präfix ähnelt in der Regel `idcs-abcd1234`.
`IDCSHost`	Das Domainsuffix der Oracle Identity Cloud Service-Instanz. Zur Laufzeit wird der Platzhalter %tenant% durch den Wert des Attributs ClientTenant ersetzt.
`AudienceServiceUrl`	Die vollqualifizierte Domainnamen-URL Ihrer Oracle Identity Cloud Service-Instanz.
`TokenIssuer`	Für dieses Attribut empfiehlt Oracle, dass Sie den Wert `https://identity.oraclecloud.com/` beibehalten.
`scope`	Der Geltungsbereich steuert die Daten, auf die die Anwendung im Namen des Oracle Identity Cloud Service-Benutzers zugreifen oder diese verarbeiten kann. Wenn die Anwendung das SDK zur Authentifizierung eines Benutzers verwendet, lautet der Geltungsbereich `openid`. Wenn die Anwendung das SDK verwendet, um Details zum Benutzer abzurufen, lautet der Geltungsbereich `urn:opc:idm:t.user.me openid`.
`ConsoleLog`	Aktiviert SDK-Log.
`LogLevel`	Gibt die Logebene des SDK an.

Die Anwendung verwendet sowohl die Attribute logoutSufix als auch redirectURL, um Hardcode für diese Werte zu vermeiden. Das SDK benötigt sie nicht.

Die Anwendung Node.js implementiert die URL-Route /oauth/oracle. Wenn sich ein Benutzer bei Oracle Identity Cloud Service authentifiziert, sendet der Webbrowser eine GET-Anforderung an diese URL. Diese Route verwendet das SDK, um die Autorisierungs-URL von Oracle Identity Cloud Service zu generieren.

//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);
        })
});

Diese Funktion lädt die JSON-Parameter in eine Variable, initialisiert einen Authentifizierungsmanager und verwendet die Funktion IdcsAuthenticationManager.getAuthorizationCodeUrl() des Node.js-SDK, um die Autorisierungscode-URL zu generieren. Diese Funktion verwendet das Versprechen, entweder den Webbrowser des Benutzers umzuleiten, wenn die Autorisierungscode-URL generiert wird, oder einen Fehler im Browser darzustellen.

Die folgenden Parameter werden zum Generieren der Autorisierungscode-URL verwendet:

Name	Beschreibung
`auth.oracle.redirectURL`	Nachdem sich ein Benutzer angemeldet hat, leitet Oracle Identity Cloud Service den Webbrowser des Benutzers zu dieser URL um. Diese URL muss mit der URL übereinstimmen, die Sie für die vertrauenswürdige Anwendung in der Identity Cloud Service-Konsole konfigurieren. Weitere Informationen zum Angeben einer Umleitungs-URL für die Node.js-Webanwendung finden Sie unter Node.js-Anwendung registrieren.
`auth.oracle.scope`	Der Authentifizierungsgeltungsbereich OAuth oder OpenID Connect. Diese Anwendung erfordert nur die Authentifizierung `openid`.
`state`	Das OAuth-Protokoll definiert diesen Parameter. Die Beispielwebanwendung Node.js verwendet diesen Code, um zu prüfen, ob die Kommunikation mit Oracle Identity Cloud Service hergestellt werden kann. In diesem Beispiel lautet der Wert für diesen Parameter `1234`.
`response_type`	Der für den Autorisierungscode-Zuteilungstyp erforderliche Parameter. In diesem Beispiel lautet der Wert für diesen Parameter `code`.

Nachdem sich der Benutzer angemeldet hat, leitet Oracle Identity Cloud Service den Webbrowser des Benutzers an eine Callback-URL um, die der Entwickler implementieren muss. Die Webanwendung Node.js verwendet die Route /callback, um diese Anforderung zu verarbeiten.

//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);
        })
});

Die Anwendung Node.js verwendet den Autorisierungscode, um ein Zugriffstoken anzufordern. Das Zugriffstoken wird als Cookie gespeichert, das dann zur späteren Verwendung an den Webbrowser gesendet wird.

Die Funktion IdcsAuthenticationManager.authorizationCode() des Node.js-SDK verwendet auch Promise (eine Then-Catch-Anweisung), um das Zugriffstoken als Cookie festzulegen und den Browser auf die Seite /auth.html umzuleiten.

Das Node.js-SDK basiert auf dem Node.js-Pass-Framework. Daher muss der Browser das Zugriffstoken als Headervariable an den URL-Handler /auth weiterleiten und die Methode passport.authenticate() mit dem Oracle Identity Cloud Service-Strategienamen als Parameter verwenden:

//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');
});

Nachdem die Methode passport.authenticate() die Session der Anwendung erstellt hat, leitet die Funktion den Webbrowser des Benutzers zu einer geschützten URL in der Anwendung /home um. Neben /home verfügt die Webanwendung Node.js über eine andere geschützte URL: /myProfile.

Jede geschützte URL muss prüfen, ob die Session des Benutzers zuvor erstellt wurde. Die folgende Funktion wird von jeder app.get()-Funktion für diese URLs verwendet.

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

Die Anwendung Node.js verarbeitet die Route /myProfile und ruft die in der Session festgelegten Informationen wie folgt ab:

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);
   })
});

Nachdem das IdcsAuthenticationManager-Objekt initialisiert wurde, verwendet der Handler der /myProfile-Route die IdcsAuthenticationManager.validateIdToken()-Funktion des SDK, um Benutzerinformationen wie Anzeigename, Benutzer-ID und die Liste der Gruppen und Anwendungsrollen abzurufen, die dem Benutzer zugewiesen sind. Das JSON-Objekt wird dann zur Wiedergabe im Webbrowser als Zeichenfolge in die Datei myProfile.handlebars geparst.

Um den Benutzer von Single Sign-On zwischen der Anwendung und Oracle Identity Cloud Service abzumelden, implementiert die Webanwendung Node.js die Route /logout wie folgt:

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);
    }
  })
});

Diese Route invalidiert die Session der Anwendung, entfernt zuvor festgelegte Objekte und Cookies und leitet den Webbrowser des Benutzers dann an die OAuth-Abmelde-URL von Oracle Identity Cloud Service um.