[17.0.0.3 and later]

Configuration du jeton Web JSON MicroProfile

Vous pouvez configurer un serveur Liberty pour accepter un jeton Web JSON MicroProfile en tant que jeton d'authentification.

Avant de commencer

Installez Java™ Platform, Standard Edition (Java SE) 8 ou une version ultérieure pour utiliser la fonction mpJwt-1.0.

Pourquoi et quand exécuter cette tâche

MicroProfile 1.2 définit un jeton Web JSON interopérable (MP-JWT) standard qui comprend trois parties :
  • Le format du jeton et la revendication
  • L'interface org.eclipse.microprofile.jwt.JsonWebToken, une extension d'interface java.security.Principal qui rend cet ensemble de revendications disponible via des accesseur de style get
  • Le mappage du jeton Web JSON et des revendications vers plusieurs API de conteneur Java EE

Vous trouverez la spécification MP-JWT et l'API sous JWT RBAC for MicroProfile.

Toute personne de confiance en possession d'un jeton MP-JWT peut utiliser ce jeton pour accéder aux ressources associées dans Liberty en envoyant le jeton au dessus de l'en-tête d'autorisation. Le format WF du jeton doit suivre la spécification RFC 6750, The OAuth 2.0 Authorization Framework: Bearer Token Usage, comme dans l'exemple suivant :

GET /resource/1 HTTP/1.1
Host: example.com
Authorization: Bearer <MP-JWT token>
Le serveur de ressource Liberty valide le jeton MP-JWT, crée le jeton Web JSON authentifié et rend le jeton Web JSON et les revendications du jeton disponible via l'injection CDI ou via le contexte de sécurité JAX-RS. Pour être accepté en tant que jeton MP-JWT, le jeton JWT doit contenir une liste de revendications. L'exemple suivant illustre un jeton MP-JWT :
{
    "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"],
}

Procédure

  1. Ajoutez la fonction mpJwt-1.0 et toute autre fonction nécessaire au fichier server.xml. Au minimum, la fonction mpJwt-1.0 nécessite AppSecurity-2.0 et jaxrs-2.0 et elle est fréquemment utilisée avec la fonction CDI (Contexts and Dependency Injection).
    <featureManager>
        <feature>mpJwt-1.0</feature>
        <feature>appSecurity-2.0</feature>
        <feature>jaxrs-2.0</feature>
        <feature>cdi-1.2</feature>
        ...
    </featureManager>
  2. Configurez l'élément mpJwt.
    1. Ajoutez l'attribut issuer. Entrez une valeur pour cette attribut qui corresponde à la revendication iss dans le jeton Web Java (JWT).
    2. Ajoutez l'attribut audiences si le JWT contient une revendication aud. Entrez une valeur pour cet attribut qui contienne une valeur de la revendication aud dans le JWT.
    3. Ajoutez l'attribut jwksUri. Entrez une valeur pour cet attribut qui corresponde à l'URL de la clé Web JSON (JWK). Le code suivant illustre un élément de configuration mpJwt typique avec JWK :
      <mpJwt 
           id="myMpJwt"
           jwksUri="https://example.com/api/jwk"
           issuer="https://example.com/api/v1"
           audiences="conferenceService">
      </mpJwt>
    4. Ajoutez l'attribut keyName si vous ajoutez la clé de validation de signature JWT au fichier truststore dans la configuration SSL (Secure Sockets Layer). L'attribut keyName spécifie l'alias de clé dans le fichier truststore. Le code suivant illustre un exemple de configuration mpJwt :
      <mpJwt 
           keyName="mpJwtValidationKey"
           issuer="https://example.com/api/v1"
           audiences ="conferenceService">
      </mpJwt>
  3. Configurez un fichier truststore incluant le certificat de noeud final JWK pour que le serveur Liberty puisse effectuer des connexions SSL vers le noeud final JWK.
    1. Configurez truststores sur les éléments keystore dans le fichier server.xml.
    2. Configurez le SSL pour faire référence à ce fichier truststore.
    3. Définissez la configuration SSL en tant que configuration SSL par défaut du serveur ou spécifiez l'ID truststore sur l'attribut sslRef de l'élément mpJwt.
    4. Si l'émetteur du JWT ne prend pas en charge le JWK et si le JWT est signé avec un certificat X.509, importez le certificat X.509 de l'émetteur dans le fichier truststore dans une configuration SSL. Pour plus d'informations, voir Activation de la communication SSL dans Liberty.
  4. Facultatif : Définissez des règles pour le mappage des revendications de JWT à des sujets d'authentification pour un JWT ne se trouvant pas au format MP-JWT. Par défaut, le programme utilise la revendication upn comme nom principal et comme nom de sécurité unique de l'utilisateur et le programme utilise la revendication de groupes comme nom de groupe pour le mappage du rôle de sécurité. Pour modifier le mappage par défaut, utilisez l'attribut userNameAttribute pour choisir une revendication pour le principal de l'utilisateur et utilisez l'attribut groupAttribute pour choisir une revendication pour le nom de groupe.
  5. Facultatif : Utilisez l'application JAX-RS pour accéder à la méthode d'accès get JsonWebToken en appelant l'API, javax.ws.rs.core.SecurityContext.getUserPrincipal(). Dans l'exemple suivant, le principal de l'utilisateur est transtypé en tant qu'instance de l'API org.eclipse.microprofile.jwt.JsonWebToken API, et l'application peut accéder à toutes les revendications via les méthodes d'accès get JsonWebToken :
    @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. Facultatif : Utilisez une application JAX-RS pour injecter l'API org.eclipse.microprofile.jwt.JsonWebToken via les types Raw Type, ClaimValue, javax.inject.Provider et JSON-P, comme illustré dans l'exemple suivant :
    @RequestScoped
    public class JwtEndpoint {
           @Inject
           private JsonWebToken jwtPrincipal;
           @GET
           @Path("/getInjectedPrincipal")
           public String getInjectedJWT() {
              return  this.jwtPrincipal.getName();
           }
    }
  7. Facultatif : Si votre programme réalise une sécurité prise en charge par l'application et si vous pouvez obtenir une API org.eclipse.microprofile.jwt.JsonWebToken du sujet, utilisez l'API com.ibm.websphere.security.auth.WSSubject.getCallerPrincipal(). Dans le contexte de sécurité en cours, le sujet contient deux principaux java.security.Principal. L'un des principaux est le jeton Web JSON.
  8. Facultatif : [17.0.0.4 and later]Sécurisez les ressources JAX-RS avec des annotations et les revendications de groupe du jeton JWT. Mappez les noms de rôle de sécurité qui sont utilisés dans l'aannotation @RolesAllowed pour regrouper des noms dans la revendication des groupes du jeton JWT. Si le nom de rôle et les noms de groupe sont identiques, vous pouvez omettre le mappage de rôle dans l'élément application-bnd. Toutefois, si le jeton JWT est un jeton MP-JWT qui contient des informations sur les groupes, effectuez un mappage dans l'élément application-bnd afin de déclarer l'association rôle/groupe. Pour plus d'informations, voir Sécurisation des resources JAX-RS à l'aide d'annotations, ID d'accès et autorisation et Autorisation pour les applications lorsqu'une liaison de mappage de rôle n'est pas fournie.
  9. Facultatif : [17.0.0.4 and later]Configurez le serveur Liberty pour qu'il vérifie le nom de principal utilisateur à partir du jeton JWT par rapport au registre d'utilisateurs Liberty configuré.

    Par défaut, le programme crée un objet de sécurité directement à partir du jeton JWT vérifié sans que le registre d'utilisateurs ne soit requis. Pour modifier ce comportement, vous ajoutez l'attribut de configuration mapToUserRegistry="true" dans le fichier server.xml. Le programme recherche le nom principal par rapport au registre d'utilisateurs configuré et crée un objet de sécurité en fonction des attributs utilisateur du registre d'utilisateurs.

  10. Facultatif : [17.0.0.4 and later]Configurez le serveur Liberty pour qu'il applique la fonction mpJwt-1.0 uniquement aux applications dont le nom de la méthode de connexion est MP-JWT.
    Par défaut, si la fonction mpJwt-1.0 est configurée, l'en-tête HTTP de toutes les demandes autorisées doit inclure un jeton JWT valide. Pour modifier le comportement par défaut de telle sorte que le jeton d'authentification JWT soit requis dans certaines applications uniquement, ajoutez l'attribut de configuration ignoreApplicationAuthMethod="false" à l'élément <mpJwt> dans le fichier server.xml. Ensuite, configurez l'application en procédant de l'une des deux manières suivantes :
    • L'application comporte une annotation @LoginConfig avec la méthode de connexion MP-JWT login déclarée comme méthode d'authentification.

      Par exemple, @LoginConfig(authMethod = "MP-JWT", realmName = "MP-JWT").

    • Le fichier web.xml associé à l'application comporte une déclaration pour la méthode d'authentification MP-JWT dans l'élément login-config.

      Par exemple, <login-config> <auth-method>MP-JWT</auth-method> <realm-name>MP-JWT</realm-name></login-config>.

  11. Facultatif : [17.0.0.4 and later]Configurez le serveur Liberty pour qu'il propage automatiquement le jeton MP-JWT comme jeton d'authentification lorsqu'il appelle d'autres services JAX-RS.

    Si le serveur Liberty agit également en tant que client JAX-RS 2.0, ajoutez l'instruction authnToken="mpjwt" à l'élément de configuration <webTarget>. Ensuite, le client Liberty JAX-RS ajoute automatiquement un jeton JWT en tant qu'en-tête d'autorisation dans l'appel de service JAX-RS. Par exemple, si vous ajoutez l'élément <webTarget uri="http://localhost:56789/protectedResourceWithMPJWT*" authnToken="mpjwt" /> au fichier server.xml, le jeton JWT est ajouté à l'en-tête d'autorisation lorsque le service http://localhost:56789/protectedResourceWithMPJWT/ est appelé.


Icône indiquant le type de rubrique Rubrique Tâche

Nom du fichier : twlp_sec_json.html