On-Behalf-Of (OBO)-Authentifizierung | Scheer IMC

Die On-Behalf-Of (OBO)-Authentifizierung ermöglicht es einer externen Anwendung oder Integration, im Namen eines bestimmten Nutzers auf die APIs der imc Learning Suite (LMS) zuzugreifen.

Dies kann nützlich sein, wenn ein externes System Aktionen im LMS im Kontext des aktuell authentifizierten Nutzers ausführen muss, anstatt für alle Requests ein einziges technisches Konto oder Servicekonto zu verwenden.

Beispielsweise kann eine externe Anwendung die Identität des mit ihr interagierenden Nutzers bereits kennen und muss die LMS-APIs als eben dieser Nutzer aufrufen. Mit der OBO-Authentifizierung kann die Anwendung ein Zugriffstoken anfragen, das den jeweiligen LMS-Nutzer repräsentiert, und dieses Token für nachfolgende API-Requests verwenden.

Die OBO-Authentifizierung ist insbesondere dann von Bedeutung, wenn:

API-Requests im Kontext einzelner Nutzer ausgeführt werden sollen.
verschiedene Nutzer durch ihre jeweiligen LMS-Identitäten repräsentiert werden sollen.
die Verwendung eines einzigen gemeinsamen technischen Kontos für alle API-Requests für die Integration nicht geeignet ist.

Wenn eine Integration lediglich eine System-zu-System-Kommunikation unter Verwendung einer einzigen technischen Identität erfordert, ist eine OBO-Authentifizierung gegebenenfalls nicht erforderlich.

In den folgenden Abschnitten werden die notwendige Konfiguration, die JWT-Generierung und der Token-Austausch für die Verwendung der OBO-Authentifizierung beschrieben.

Konfiguration

Für die On-Behalf-Of (OBO)-Authentifizierung ist ein sicherer encryptionKey erforderlich. Sie müssen den Key im Verzeichnis imc-ms-config/application.yml konfigurieren, damit er dem System zur Verfügung steht.

Gemäß der JWT-JWA-Spezifikation (RFC 7518, Abschnitt 3.2) müssen Keys, die mit HMAC-SHA-Algorithmen verwendet werden, mindestens eine Größe von 256 Bit haben. Daher muss der konfigurierte encryptionKey mindestens 256 Bit an Key-Material bereitstellen.

auth:
  jwt:
    issuer: ${endpoint.extern.url}
    subject:
      encryptionKey:

Notieren Sie sich den konfigurierten Issuer, da der genaue Wert bei der Generierung des JSON Web Tokens (JWT) notwendig ist. Wenn der Issuer mithilfe eines Platzhalters konfiguriert wurde, lösen Sie die entsprechende Konfiguration in derselben Datei application.yml auf.

endpoint:
  extern:
    host: customer.imc-learning.com
    port: 443
    https: true # required in ils/application.properties
    protocol: HTTPS # this is used in systemintegration.xml where only uppercase is allowed
    scheme: https # this is used for various purposes (issuer in idm, url mapping like cors-filters, ...)
    url: ${endpoint.extern.scheme}://${endpoint.extern.host}:${endpoint.extern.port}

Mit der oben genannten Beispielkonfiguration wird der Issuer wie folgt aufgelöst: https://customer.imc-learning.com:443

Scheer IMC unterstützt Sie gerne bei der Einrichtung der Einstellungen für den encryptionKey oder führt die Konfiguration für Sie durch und stellt Ihnen die notwendigen Angaben zur Verfügung.

JWT-Generierung

Sobald Sie die Konfiguration abgeschlossen haben, können Sie ein JWT für den Nutzer generieren, dessen Identität übernommen werden soll. Das folgende Java-Beispiel erstellt ein JWT für den OBO-Token-Austausch:

Java

SecretKey key = Keys.hmacShaKeyFor(encryptionKey.getBytes(StandardCharsets.UTF_8));

Instant now = Instant.now();
Instant expiresAt = now.plusSeconds(1 * 60 * 60); // e.g. 1 hour

String jwt = Jwts.builder()
        .setHeaderParam("typ", "JWT")
        .setSubject("imc_learner@im-c.de") // Email address of the user to impersonate
        .setIssuer("https://customer.imc-learning.com:443") // Must match the configured system
        .setIssuedAt(Date.from(now))
        .setExpiration(Date.from(expiresAt))
        .signWith(key, SignatureAlgorithm.HS256)
        .compact();

Wichtig: Die System-URL für den Zugriff auf die API und der konfigurierte JWT-Issuer können voneinander abweichen. Der iss-Claim im JWT muss genau mit dem in der Datei application.yml konfigurierten Issuer übereinstimmen.

OBO-Token-Austausch

POST {systemURL}/idm/jwt/service/impersonate

curl --location --request POST 'https://{systemURL}/idm/jwt/service/impersonate?grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange&client_id={client}&client_secret={clientSecret}&subject_token={jwtToken}&subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt' \

API-Parameter	Wert	Beschreibung
grant_type	urn:ietf:params:oauth:grant-type:token-exchange	Gibt den OAuth 2.0-Autorisierungstyp für den Token-Austausch an
client_id		Die Client-ID, wie sie in der Datei `application.yml` konfiguriert wurde. Sie müssen die Identitätsübernahme für diesen Mandant aktivieren.
client_secret		Das dem konfigurierten Mandanten zugeordnete Client Secret
subject_token		Das JWT, das die Identität des Nutzers enthält, die übernommen werden soll
subject_token_type	urn:ietf:params:oauth:token-type:jwt	Gibt an, dass das bereitgestellte `subject_token` ein JWT ist

Die API gibt eine Antwort wie die folgende zurück:

JSON

{
    "refresh_token": "XXX",
    "access_token": "XXX",
    "token_type": "Bearer",
    "expires_in": 86400
}

Sie können nun den zurückgegebenen access_token verwenden, um API-Requests im Namen des Nutzers durchzuführen, der im sub-Claim des JWT angegeben ist. Mit dem refresh_token können Sie bei Bedarf einen neuen Access-Token (Zugriffstoken) abrufen.