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
Obtain JWT tokens from the JWT token generation
endpoint. - Obtain tokens with an endpoint from the jwt-1.0 feature without
programming.
- 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.
- 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.
- 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).
- Build JSON Web Tokens in Liberty programmatically.
- In the server.xml file, add the jwt-1.0 feature.
<featureManager>
<feature>jwt-1.0</feature>
...
</featureManager>
- 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
- 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.
- 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");
- 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");
- Modifiez l'algorithme de signature et la clé de signature configurés.
jwtBuilder.signWith("new_algorithm", new_key);
- 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();