[17.0.0.3 und höher]

MicroProfile-JWT konfigurieren

Sie können einen Liberty-Server so konfigurieren, dass er ein MicroProfile-JWT (JSON Web Token) als Authentifizierungstoken akzeptiert.

Vorbereitende Schritte

Installieren Sie Java™ Platform, Standard Edition (Java SE) 8 oder höher, um das Feature mpJwt-1.0 zu verwenden.

Informationen zu diesem Vorgang

MicroProfile 1.2 definiert einen interoperablen JSON-Web-Token-Standard (MP-JWT), der drei Komponenten beinhaltet:
  • Das Tokenformat und den Anspruch.
  • Die org.eclipse.microprofile.jwt.JsonWebToken-Schnittstelle, eine java.security.Principal-Schnittstellenerweiterung, die diese Gruppe von Ansprüchen mithilfe von Accessoren des Typs "get style" zur Verfügung stellt.
  • Zuordnung des JSON Web Token und der Ansprüche zu verschiedenen Java EE-Container-APIs.

Suchen Sie die MP-JWT-Spezifikation und API unter JWT RBAC for MicroProfile.

Jede vertrauenswürdige Partei, die MP-JWT-Token besitzt, kann dieses Token verwenden, um auf die zugeordneten Ressourcen in Liberty zuzugreifen, indem das Token in Berechtigungsheadern gesendet wird. Das Sendeformat des Tokens unterliegt der Spezifikation RFC 6750 (The OAuth 2.0 Authorization Framework: Bearer Token Usage). Beispiel:

GET /resource/1 HTTP/1.1
Host: example.com
Authorization: Bearer <MP-JWT-Token>
Der Liberty-Ressourcenserver validiert das MP-JWT-Token, erstellt das authentifizierte JSON Web Token und stellt das JSON Web Token und die Tokenansprüche über CDI-Injektion oder den JAX-RS-Sicherheitskontext zur Verfügung. Das JWT-Token muss eine Liste mit Ansprüchen enthalten, um als MP-JWT-Token akzeptiert zu werden. Das folgende Beispiel zeigt ein MP-JWT-Token:
{
    "typ": "JWT",
    "alg": "RS256",
    "kid": "abc-1234567890"
}
{
       "iss": "https://server.example.com",
       "aud": "s6BhdRkqt3",
       "jti": "a-123",
       "exp": 1311281970,
       "iat": 1311280970,
       "sub": "24400320",
       "upn": "jdoe@server.example.com",
       "groups": ["red-group", "green-group", "admin-group", "admin"],
}

Vorgehensweise

  1. Fügen Sie das Feature mpJwt-1.0 und alle weiteren erforderlichen Features der Datei server.xml hinzu. Das Feature mpJwt-1.0 erfordert mindestens die Features AppSecurity-2.0 und jaxrs-2.0 und wird häufig mit dem CDI-Feature (Contexts and Dependency Injection) verwendet.
    <featureManager>
        <feature>mpJwt-1.0</feature>
        <feature>appSecurity-2.0</feature>
        <feature>jaxrs-2.0</feature>
        <feature>cdi-1.2</feature>
        ...
    </featureManager> 
  2. Konfigurieren Sie das Element mpJwt.
    1. Fügen Sie das Attribut issuer hinzu. Geben Sie einen Wert für dieses Attribut ein, der mit dem Anspruch iss im Java Web Token (JWT) übereinstimmt.
    2. Fügen Sie das Attribut audiences hinzu, wenn das JWT einen aud-Anspruch enthält. Geben Sie einen Wert für dieses Attribut ein, das einen Wert des aud-Anspruchs im JWT enthält.
    3. Fügen Sie das Attribut jwksUri hinzu. Geben Sie für dieses Attribut einen Wert ein, der mit der URL für den JWK (JSON Web Key) übereinstimmt. Der folgende Code zeigt ein typisches mpJwt-Konfigurationselement mit JWK:
      <mpJwt 
           id="myMpJwt"
           jwksUri="https://example.com/api/jwk"
           issuer="https://example.com/api/v1"
           audiences="conferenceService">
      </mpJwt>
    4. Fügen Sie das Attribut keyName hinzu, wenn Sie den JWT-Signaturvalidierungsschlüssel der truststore-Datei in der SSL-Konfiguration hinzufügen. Das Attribut keyName gibt den Schlüsselalias in der truststore-Datei an. Der folgende Code zeigt eine mpJwt-Beispielkonfiguration:
      <mpJwt 
           keyName="mpJwtValidationKey"
           issuer="https://example.com/api/v1"
           audiences ="conferenceService">
      </mpJwt>
  3. Konfigurieren Sie eine truststore-Datei, um das JWK-Endpunktzertifikat einzuschließen, damit der Liberty-Server SSL-Verbindungen zum JWK-Endpunkt herstellen kann.
    1. Konfigurieren Sie truststores für die keystore-Elemente in der server.xml-Datei.
    2. Konfigurieren Sie SSL, um diese truststore-Datei zu referenzieren.
    3. Legen Sie die SSL-Konfiguration als SSL-Standardkonfiguration für den Server fest oder geben Sie die truststore-ID über das sslRef-Attribut des mpJwt-Elements an.
    4. Wenn der JWT-Aussteller das JWK nicht unterstützt und das JWT mit einem X.509-Zertifikat signiert ist, importieren Sie das X.509-Zertifikat vom Aussteller in die truststore-Datei in eine SSL-Konfiguration.
  4. Optional: Definieren Sie Regeln für die Zuordnung von JWT-Ansprüchen zu Authentifizierungssubjekten für ein JWT, das nicht das MP-JWT-Format hat. Das Programm verwendet standardmäßig den upn-Anspruch als Principalnamen und eindeutigen Sicherheitsnamen des Benutzers, und das Programm verwendet den groups-Anspruch als Gruppennamen für die Sicherheitsrollenzuordnung. Verwenden Sie zum Ändern der Standardzuordnung das Attribut userNameAttribute, um einen Anspruch für den Benutzerprincipal auszuwählen, und verwenden Sie das Attribut groupAttribute, um einen Anspruch für den Gruppennamen auszuwählen.
  5. Optional: Verwenden Sie die JAX-RS-Anwendung, um auf den JsonWebToken-Getter durch Aufrufen der API javax.ws.rs.core.SecurityContext.getUserPrincipal(). Im folgenden Beispiel wird der Benutzerprinzipal als Instanz der API org.eclipse.microprofile.jwt.JsonWebToken umgesetzt, und die Anwendung kann auf über JsonWebToken-Getter auf alle Ansprüche zugreifen.
    @GET
    @Path("/getGroups")
    public Set<String> getGroups(@Context SecurityContext sec) {
           Set<String> groups = null;
           Principal user = sec.getUserPrincipal();
           if (user instanceof JsonWebToken) {
                    JsonWebToken jwt = (JsonWebToken) user;
                    groups= = jwt.getGroups();
           }
           return groups;
    }
  6. Optional: Verwenden Sie eine JAX-RS-Anwendung, um die org.eclipse.microprofile.jwt.JsonWebToken-API über die Typen Raw Type, ClaimValue, javax.inject.Provider und JSON-P einzufügen. Beispiel:
    @RequestScopedpublic class JwtEndpoint {
           @Inject
           private JsonWebToken jwtPrincipal;
           @GET
           @Path("/getInjectedPrincipal")
           public String getInjectedJWT() {
              return  this.jwtPrincipal.getName();
           }
    }
  7. Optional: Wenn Ihr Programm programmgestützte Sicherheit ausführt und Sie können eine org.eclipse.microprofile.jwt.JsonWebToken-API aus dem Subjekt abrufen, verwenden Sie die die API com.ibm.websphere.security.auth.WSSubject.getCallerPrincipal(). Im aktuellen Sicherheitskontext enthält das Subjekt zwei java.security.Principal-Principals. Ein Prinzipal ist das JSON Web Token.
  8. Optional: [17.0.0.4 und höher]Schützen Sie JAX-RS-Ressourcen mit Annotationen und die Gruppenansprüche der JWT. Ordnen Sie Sicherheitsrollennamen, die in der Annotation @RolesAllowed verwendet werden, Gruppennamen im Gruppenanspruch des JWT zu. Wenn der Rollenname und die Gruppennamen identisch sind, können Sie die Rollenzuordnung im Element application-bnd weglassen. Wenn jedoch das JWT ein MP-JWT ist, das Gruppeninformationen enthält, ordnen Sie dies im Element application-bnd zu, um die Rollen-zu-Gruppe-Zuordnung zu deklarieren. Weitere Informationen finden Sie unter JAX-RS-Ressourcen mit Annotationen sichern, Zugriffs-IDs und Berechtigung und Berechtigung für Anwendungen, wenn keine Rollenzuordnungsbindung bereitgestellt wird.
  9. Optional: [17.0.0.4 und höher]Konfigurieren Sie Liberty so, dass der Name des Benutzerprinzipals im JWT anhand der konfigurierten Liberty-Benutzerregistry überprüft werden kann.

    Standardmäßig erstellt das Programm ohne die Benutzerregistry-Anforderung ein Sicherheitsubjekt direkt aus dem geprüften JWT. Wenn Sie dieses Verhalten ändern möchten, fügen Sie das Konfigurationsattribut mapToUserRegistry="true" der Datei server.xml hinzu. Das Programm sucht in der konfigurierten Benutzerregistry nach dem Namen des Prinzipals und erstellt ein Sicherheitssubjekt auf der Basis von Benutzerattributen aus der Benutzerregistry.

  10. Optional: [17.0.0.4 und höher]Konfigurieren Sie Liberty so, dass das Feature mpJwt-1.0 nur auf Anwendungen angewendet wird, die MP-JWT als Anmeldemethodennamen haben.
    Wenn das Feature mpJwt-1.0 konfiguriert ist, müssen standardmäßig alle berechtigten Anforderungen ein gültiges JWT im HTTP-Header enthalten. Wenn Sie das Standardverhalten ändern möchten, sodass das JWT-Authentifizierungstoken nur bei einigen Anwendungen erforderlich ist, fügen Sie das Konfigurationsattribut ignoreApplicationAuthMethod="false" dem Element <mpJwt> in der Datei server.xml hinzu. Konfigurieren Sie die Anwendung anschließend auf eine der folgenden Arten:
    • Die Anwendung enthält eine @LoginConfig-Annotation, in der die MP-JWT-Anmeldemethode als Authentifizierungsmethode deklariert ist.

      Beispiel: @LoginConfig(authMethod = "MP-JWT", realmName = "MP-JWT").

    • Die web.xml-Datei für die Anwendung enthält eine Deklaration für die MP-JWT-Authentifizierungsmethode im Element login-config.

      Beispiel: <login-config> <auth-method>MP-JWT</auth-method> <realm-name>MP-JWT</realm-name></login-config>.

  11. Optional: [17.0.0.4 und höher]Konfigurieren Sie Liberty für die automatische Weitergabe von MP-JWT als Authentifizierungstoken, wenn Liberty andere JAX-RS-Services aufruft.

    Wenn Liberty auch als JAX-RS-2.0-Client fungiert, fügen Sie die Anweisung authnToken="mpjwt" dem Element <webTarget> hinzu. Der Liberty-JAX-RS-Client fügt dann automatisch dem JAX-RS-Serviceaufruf JWT als Berechtigungsheader hinzu. Wenn Sie beispielsweise das Element <webTarget uri="http://localhost:56789/protectedResourceWithMPJWT*" authnToken="mpjwt" /> der Datei server.xml hinzufügen, wird das JWT-Token dem Berechtigungsheader hinzugefügt, wenn der Service http://localhost:56789/protectedResourceWithMPJWT/ aufgerufen wird.


Symbol das den Typ des Artikels anzeigt. Taskartikel

Dateiname: twlp_sec_json.html