[16.0.0.4 and later]

Building JSON Web Tokens in Liberty

You can programmatically build JSON Web Token (JWT) tokens by configuring the JWT builder element in the server configuration and implementing the com.ibm.websphere.security.jwt.JwtBuilder and com.ibm.websphere.security.jwt.JwtToken APIs in your applications.

Pourquoi et quand exécuter cette tâche

For information about JWT APIs, see the JSON Web Token Java documentation or the API documentation included in the product in the ${wlp.install.dir}/dev directory.

Procédure

  1. [18.0.0.1 and later]Obtain JWT tokens from the JWT token generation endpoint.
    1. Obtain tokens with an endpoint from the jwt-1.0 feature without programming.
    2. Authenticate your credentials to access the endpoint at https://<host>:<port>/jwt/api/ibm/<configId>/token if you did not include credentials in the request. After authentication succeeds, an MP-JWT format token is returned in JSON form. The token contains the user and groups for the user as recorded in the user registry of the server.
    3. Set other token attributes, such as issuer and expiration time, from the attributes of the JWTBuilder element in the server.xml file with the <configId> ID.
    4. If you do not define JWTBuilder elements in the server.xml file, use defaultJWT as the <configId> ID. Find the available JWT Builder configuration attributes at jwtBuilder - JWT Builder (jwtBuilder).
  2. Build JSON Web Tokens in Liberty programmatically.
  3. In the server.xml file, add the jwt-1.0 feature.
    <featureManager>
        <feature>jwt-1.0</feature>
        ...
    </featureManager>
  4. Configurez le générateur JWT en modifiant l'élément jwtBuilder.

    Pour obtenir des informations sur les attributs jwtBuilder que vous pouvez configurer, consultez Générateur JWT (jwtBuilder).

    Lorsque vous ajoutez la fonction jwt-1.0 et enregistrez vos modifications, Liberty ajoute l'élément jwtBuilder par défaut suivant.
    <jwtBuilder id="defaultJWT">
    </jwtBuilder>
    Dans cette configuration par défaut, les valeurs suivantes sont implicites :
    • La revendication exp est de 2 heures après l'heure de création du jeton. Vous pouvez configurer cette valeur sur l'attribut expiry.
    • La revendication iss est mise à https://<nom_hôte>:<port_ssl>/jwt/defaultJWT. Configurez l'émetteur sur l'attribut issuer.
    • Le JWT est signé à l'aide de l'algorithme RS256 avec une clé privée dans le magasin de clés par défaut du serveur. Cette configuration suppose qu'un magasin de clés par défaut est configuré pour le serveur, que le magasin de clés par défaut contient une clé privé unique et que la clé privée peut être utilisée pour signer. Si vous spécifiez un magasin de clés différent sur l'attribut keyStoreRef, la clé privée du magasin de clés spécifié est utilisée. Si l'attribut keyAlias n'est pas configuré et le magasin de clés contient une seule clé privée, cette clé privée est utilisée dans la signature.

    Vous pouvez reconfigurer cet élément jwtBuilder par défaut ou créer un ou plusieurs autres éléments jwtBuilder. Chaque élément jwtBuilder doit avoir une chaîne à URL sécurisée unique spécifiée comme attribut id. Si l'ID est manquant, l'élément jwtBuilder n'est pas traité.

    Si le jeton JWT est signé à l'aide de l'algorithme RS256, vous pouvez configurer le générateur JWT pour signer le jeton JWT avec la clé Web JSON (JWK) en définissant jwkEnabled="true". Lorsque la clé JWK est activée, le générateur JWT génère dynamiquement des paires de clés et signe le jeton JWT avec la clé privée. Pour valider la signature, le consommateur JWT peut extraire la clé de l'API JWK, qui a le format suivant :
    https://<nom_hôte>:<port_ssl>/jwt/ibm/api/<id_config_jwtBuilder>/jwk
  5. Générez des jetons JWT par programmation en implémentant les API com.ibm.websphere.security.jwt.JwtBuilder et com.ibm.websphere.security.jwt.JwtToken dans votre application.

    Pour plus d'informations, veuillez vous reporter à la documentation sur les jetons Web JSON Java.

    1. Créez un objet JwtBuilder.
      Si vous ne spécifiez pas un ID de configuration, l'objet est lié à la configuration de l'élément jwtBuilder par défaut.
      com.ibm.websphere.security.jwt.JwtBuilder jwtBuilder = JwtBuilder.create();
      Si vous spécifiez un ID de configuration, l'objet est lié à la configuration de l'élément jwtBuilder avec l'ID spécifié.
      com.ibm.websphere.security.jwt.JwtBuilder jwtBuilder = JwtBuilder.create("jwtBuilder_configuration_id");
    2. Modifiez les revendications dans le jeton.
      • Ajouter ou mettre à jour une revendication : jwtBuilder.claim("claim_name", "claim_value");
        jwtBuilder.claim("role", "monitor");
      • Supprimer une revendication : jwtBuilder.remove("claim_name");
        jwtBuilder.remove("role");
      • Extraire une revendication du registre d'utilisateur fédéré de Liberty : jwtBuilder.fetch("attribute_name");

        Cet appel d'extraction indique à l'objet JwtBuilder de rechercher le nom d'utilisateur identifié par la revendication sub du JWT dans le registre d'utilisateur fédéré. L'objet JwtBuilder extrait la valeur de l'attribut spécifié et crée une nouvelle revendication sur la base de cet attribut. Le nom de la nouvelle revendication est définie sur le nom d'attribut et la valeur de la nouvelle revendication est définie sur la valeur d'attribut.

      • Copiez une revendication à partir d'un objet JSON ou JWT existant : jwtBuilder.claimFrom(JSON_ou_JWT, "nom_revendication");
    3. Modifiez l'algorithme de signature et la clé de signature configurés.
      jwtBuilder.signWith("new_algorithm", new_key);
    4. Générez le jeton à l'aide de l'API com.ibm.websphere.security.jwt.JwtToken.
      JwtToken jwtToken = jwtBuilder.buildJwt();
      String jwtTokenString = jwtToken.compact();

Exemples d'API Jeton Web JSON

L'exemple suivant crée un nouveau JWT.
JwtBuilder jwtBuilder = JwtBuilder.create();
jwtBuilder.subject("tom@op.com").claim(Claims.AUDIENCE, "https://acme.com/rs").claim("iss","https://sso.com/ibm/op" ).claim("scope", "impersonator monitor").claim("uid", "hasys123haksiqws");
JwtToken goToken = jwtBuilder.buildJwt();
Le JWT obtenu est signé avec la clé privée par défaut du serveur et contient les revendications suivantes.
{
"aud": "https://acme.com/rs",
"iss": "https://sso.com/ibm/op",
"iat": 1388440863, "exp": 1388444763,
"uid": "hasys123haksiqws",
"sub": "tom@op.com",
"scope": "impersonator monitor"
}
L'exemple suivant génère le JWT newToken à partir d'un autre JWT, goToken.
JwtToken newToken = JwtBuilder.create().claim(Claims.AUDIENCE, "https://acme.com/rs").claimFrom(goToken, "sub").claim(goToken, "uid").claim(goToken, "scope").buildJwt();

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

Nom du fichier : twlp_sec_build_jwt.html