[16.0.0.3 and later]

Configuring JSON Web Token authentication for OpenID Connect

You can configure a Liberty server to accept a JSON Web Token (JWT) token as an authentication token from a trusted authentication proxy, a trusted service client, or an OAuth authorization server.

Pourquoi et quand exécuter cette tâche

To configure a Liberty server to accept a JWT token as an authentication token, enable the openidConnectClient-1.0 feature, set inboundPropagation="required", and configure a truststore and SSL. You can optionally specify additional JWT configuration, such as user registries, authentication filters, and claim-to-subject mapping. The configuration for using JWT as an authentication token is similar to Configuration d'un client OpenID Connect dans Liberty.

Any trusted party in possession of a JWT token can use that token to get access to the associated resources in Liberty. The Liberty resource server validates the JWT token and creates the authenticated subject from the JWT token. To be accepted as an authentication token, the JWT token must contain iss, sub, and exp claims and be signed with the RS256 or HS256 algorithm. Encrypted JWT is not supported. The following example shows a decoded JWT payload:
{
	"iss":"https://idp.acme.com:8020/jwt",
	"sub":"marissa@acme.com",
	"exp":1385066178,
	"aud":"https://resource.acme.com/services",
	"iat":1385062578,
	“groupIds”: [
	    “group1”, “group2”
	 ]  
}

Procédure

  1. Ajoutez la fonction Liberty openidConnectClient-1.0 et toute autre fonction nécessaire dans le fichier server.xml. Au minimum, la fonction openidConnectClient-1.0 nécessite la fonction ssl-1.0. Ajoutez la déclaration d'élément suivante dans l'élément featureManager de votre fichier server.xml :
    <feature>openidConnectClient-1.0</feature> 	
    <feature>ssl-1.0</feature>
  2. Configurez un élément openidConnectClient et définissez inboundPropagation="required". Pour des informations sur les autres attributs de l'élément openidConnectClient, consultez OpenID Connect Client.

    L'exemple de configuration suivant suppose que l'émetteur du jeton JWT prend en charge une clé Web JSON (JWK) et qu'il est signé avec l'algorithme RS256.

    <openidConnectClient id="RS" inboundPropagation="required"		
      jwkEndpointUrl="https://acme.com/jwtserver/jwk" signatureAlgorithm="RS256"
      issuerIdentifier="https://idp.acme.com:8020/jwt" >		
    </openidConnectClient>
  3. Configurez un magasin de clés de confiance pour inclure le certificat de noeud final JWK de manière à ce que le serveur Liberty puisse effectuer des connexions SSL vers le noeud final JWK. Les magasins de clés de confiance sont configurés sur les éléments keyStore dans le fichier server.xml. Après avoir configuré SSL pour faire référence à ce magasin de clés de confiance, vous pouvez soit définir la configuration SSL en tant que configuration SSL par défaut du serveur ou spécifier l'ID du magasin de clés de confiance sur l'attribut sslRef de l'élément openidConnectClient.

    Si l'émetteur du JWT ne prend pas en charge les clés JWK et le JWT est signé avec un certificat X.509 à la place, importez le certificat X.509 de l'émetteur dans le magasin de clés de confiance. Dans l'élément openidConnectClient, spécifiez l'ID de magasin de clés de confiance sur l'attribut trustStoreRef et référencez le certificat sur l'attribut trustAliasName.

    Si le JWT est signé à l'aide d'une clé secrète partagée avec l'algorithme HMAC-SHA256, définissez la clé secrète partagée sur les attributs sharedKey ou clientSecret.

    Pour obtenir des informations sur les magasins de clés de confiances ou les magasins de clés, voir Activation de la communication SSL dans Liberty.

  4. Configurez l'attribut issuerIdentifier de l'élément openidConnectClient pour qu'il corresponde à la revendication iss de l'émetteur du JWT.

    Par exemple, si le jeton JWT contient "iss":"https://idp.acme.com:8020/jwt", définissez issuerIdentifier="https://idp.acme.com:8020/jwt".

  5. Facultatif : Configurez un registre d'utilisateurs. Par défaut, les revendications JWT vérifiées sont utilisées pour créer le sujet authentifié de l'appelant directement, sans mapper le JWT à un utilisateur, de sorte qu'aucun registre d'utilisateurs n'est nécessaire.

    Cependant, si l'attribut mapIdentityToRegistryUser de l'élément openidConnectClient est défini sur true, une entrée d'utilisateur pour l'identité appropriée doit être renvoyée du serveur d'autorisation pour que l'authentification et l'autorisation puisse se produire. Pour en savoir plus sur la configuration d'un registre d'utilisateurs, voir Configuration d'un registre d'utilisateurs dans Liberty.

  6. Facultatif : Configurez les filtres d'authentification comme décrit dans Filtres d'authentification.

    Si vous configurez un filtre d'authentification, référencez-le sur l'attribut authFilterRef de l'élément openidConnectClient.

    Si l'élément openidConnectClient n'est pas configuré avec un attribut authFilterRef, toute tentative de demande non authentifiée sera authentifié par cet élément openidConnectClient.

  7. Facultatif : Configurez le serveur de ressources Liberty pour travailler avec plusieurs émetteurs JWT ou serveurs de proxy d'authentification en configurant plusieurs éléments openidConnectClient et plusieurs filtres d'authentification.

    Chaque élément openidConnectClient définit une relation de confiance avec un émetteur JWT ou un proxy d'authentification et référence un filtre d'authentification.

  8. Facultatif : Définissez des règles pour mapper les revendications JWT à des sujets d'authentification.
    Le serveur de ressources Liberty utilise les revendications JWT pour créer des sujets d'authentification, et vous pouvez définir comment mapper les revendications JWT au sujet sur les attribut d'élément openidConnectClient suivants :
    • userIdentifier
    • userUniqueIdentifier
    • groupIdentifier
    • realmName
    • realmIdentifier
    Si realmName et realmIdentifier sont configurés, realmName a la priorité et realmIdentifier est ignoré.
    Si vous ne définissez pas le mappage revendication-à-sujet, les règles de mappage par défaut suivantes s'appliquent :
    • La revendication de sujet (sub) est utilisée comme le nom principal et le nom de sécurité unique de l'utilisateur.
    • La revendication d'émetteur (iss) est le domaine par défaut et elle est utilisée en tant que domaine du sujet. Si une revendication realmName est incluse dans le jeton JWT, la revendication realmName est utilisée en tant que domaine du sujet au lieu de la revendication iss.
  9. Facultatif : Configurez un cookie SSO. Le serveur Liberty attend de chaque demande un jeton JWT valide et ne crée ou n'utilise pas les cookies SSO pour l'authentification. Pour créer des cookies SSO, définissez authnSessionDisabled="false" sur l'élément openidConnectClient.
  10. Facultatif : Configurez le serveur Liberty pour recevoir les jetons JWT. Le client Web peut utiliser l'une des méthodes suivantes pour envoyer des jetons JWT dans les demandes de ressources envoyées aux serveurs de ressources Liberty. Si le jeton JWT est envoyé dans la zone Authorization ou dans un paramètre de corps à formulaire encodé, aucune configuration de serveur additionnelle n'est requise.
    Important : Les clients ne doivent pas utiliser plus d'une méthode dans chaque demande pour transmettre le jeton. Si l'attribut headerName est configuré, les jetons envoyés dans la zone d'en-tête Authorization ou dans un paramètre de corps à formulaire encodé sont ignorés. Si l'attribut headerName n'est pas configuré, l'en-tête Authorization est d'abord recherchée, suivie par le paramètre access_token.
    • Envoyer le jeton de la zone d'en-tête de demande Authorization.
      GET /resource HTTP/1.1
      Host: server.example.com
      Authorization: Bearer mF_9.B5f-4.1JqM
    • Envoyer le jeton du corps de l'entité de demande comme paramètre de corps à formulaire encodé.
      POST /resource HTTP/1.1
      Host: server.example.com
      Content-Type: application/x-www-form-urlencoded
      access_token=mF_9.B5f-4.1JqM
    • Envoyer le jeton sur une zone d'en-tête de demande personnalisée en configurant un nom d'en-tête sécurisé dans Liberty.

      Pour configurer le nom d'en-tête sécurisé, définissez headerName="<myJwtHeaderName>" sur l'élément openidConnectClient. Par exemple, si vous définissez headerName="jwt", vous pouvez envoyer le jeton sur la zone d'en-tête jwt comme illustré dans l'exemple suivant :
      GET /resource HTTP/1.1
      Host: server.example.com
      jwt: mF_9.B5f-4.1JqM
  11. Configurez les audiences du JWT. Pour définir une liste des audiences dignes de confiance, configurez l'attribut audiences sur l'élément openidConnectClient.
    Un jeton JWT valide doit répondre à l'une des conditions suivantes :
    • Si l'attribut audiences est configuré, la valeur de la revendication d'audience (aud) doit être l'une des audiences configurées. Pour ignorer la vérification d'audience, définissez audiences sur ALL_AUDIENCES.
    • Si l'attribut audiences n'est pas configuré mais le jeton JWT contient une revendication aud représentant une URL valide, l'URL du service des ressources doit avoir la valeur aud comme préfixe.
      Par exemple, l'audience suivante est valide car l'URL de ressource commence par la valeur de revendication aud :
      • Revendication d'audience : "aud":"https://<serveur>:<port>/something"
      • URL de ressource : https://<serveur>:<port>/something/specific
      L'audience suivante n'est pas valide car l'URL de ressource ne commence pas par la valeur de revendication aud.
      • Revendication d'audience : "aud":"https://<serveur>:<port>/something/specific"
      • URL de ressource : https://<serveur>:<port>/something
  12. Facultatif : Mappez par programme les jetons JWT aux sujets en implémentant l'interface de programmation de service (SPI) com.ibm.wsspi.security.oauth.UserCredentialResolver.

    Pour obtenir des informations sur l'interface, voir les informations sur l'interface SPI com.ibm.wsspi.security.oauth.UserCredentialResolver dans Programmation d'interfaces ou dans la documentation Java fournie avec le produit dans le répertoire ${wlp.install.dir}/dev/spi/ibm/.

Résultats

Vous avez créé la configuration minimale requise pour configurer un serveur Liberty pour accepter les jetons JWT comme jetons d'authentification.

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

Nom du fichier : twlp_sec_config_oidc_jwt.html