Securing JAX-RS 2.0 resource by using annotations
Vous pouvez sécuriser les ressources Java™ API for RESTful Web Services (JAX-RS) en utilisant des annotations qui définissent des paramètres de sécurité.
Avant de commencer
Pour cette tâche, vous devez avoir développé l'application et identifié les ressources JAX-RS à protéger en utilisant des annotations pour la sécurité.
Pourquoi et quand exécuter cette tâche
- @PermitAll
- Indique que tous les rôles de sécurité sont autorisés à accéder aux ressources JAX-RSS.
- @DenyAll
- Indique qu'aucun rôle n'est autorisé à accéder aux ressources JAX-RS.
- @RolesAllowed
- Indique que les rôles de sécurité sont autorisés à accéder aux ressources JAX-RS.
Vous pouvez définir les annotations au niveau de la classe ou de la méthode. Les règle suivantes régissent les annotations de sécurité :
- Les annotations au niveau de la méthode prévalent sur les annotations au niveau de la classe.
- Dans le fragment de code suivant, la ressource JAX-RS référencée par les annotations @GET et @Path des /adresses correspondante à la méthode getList() n'est pas limitée et elle est soumise à la consommation publique. Toutefois, la ressource référencée par les annotations @PUT et @Path des /adresses et la méthode updateList() correspondante nécessitent le rôle Manager, par exemple :
@Path(value="/addresses") @PermitAll public class AddressBookResource { @GET @Produces(value="text/plain") public String getList() { } @PUT @RolesAllowed(“Manager”) public void updateList(String[] books) { } }
- Les annotations de sécurité s'excluent mutuellement.
- Cela implique que chaque ressource est régie uniquement par au plus l'une des annotations de sécurité. L'exemple suivant n'est pas valide, car @PermitAll et @RolesAllowed sont définis :
@Path(value="/addresses") @PermitAll @RolesAllowed(“Employee”) public class AddressBookResource { @GET @Produces(value="text/plain") public String getList() { } }
Dans l'exemple de code précédent, l'annotation @RolesAllowed prévaut et l'annotation @PermitAll est ignorée. De même, si l'annotation @RolesAllowed et l'annotation @DenyAll sont définies, l'annotation @DenyAll prévaut.
De même, si les annotations @PermitAll et @DenyAll sont définies au niveau de la méthode ou de la classe, l'annotation @DenyAll prévaut et elle assure la sécurité en se conformant au principe par défaut de sécurité.
Si les annotations @PermitAll, @DenyAll et @RolesAllowed existent au niveau de la méthode ou de classe, elles prévalent sur les annotation @RolesAllowed and @PermitAll. La liste suivante affiche l'ordre de priorité de ces annotations :- @DenyAll
- @RolesAllowed
- @PermitAll
- Règle d'héritage
- Les annotations JSR 250 ajoutées au niveau de la classe affectent uniquement les classes qu'elle annotent et les méthodes correspondantes des sous-ressources. Les annotations définie au niveau de la classe n'affectent pas les ressources héritées d'une superclasse.
- Règles des méthodes de remplacement
- Les annotations dans les ressources qui correspondent à des méthodes remplacées dans les sous-classes prévalent sur les annotations incluses dans la classe parente. Dans le fragment de code suivant, le rôle LocalAdministrator est utilisé pour accéder à la sous-ressource /addresses/local, par exemple :
@Path(value="/addresses") @PermitAll public class AddressBookResource { @GET @Produces(value="text/plain") public String getList() { } @PUT @RolesAllowed(“Administrator”) public void updateList(String books) { } } @Path(value="/addresses") @PermitAll public class LocalAddressBookResource extends AddressBookResource { @PUT @RolesAllowed(“LocalAdministrator”) @Path(value=”local”) public void updateList(String books){ } }
- Remarque sur @RolesAllowed
- Une ressources peut avoir plusieurs annotations @RolesAllowed simultanément. Par exemple, vous pouvez obtenir :
en utilisant le fragment de code suivant :@RolesAllowed("role1") @RolesAllowed("role2") public String foo() { }
@RolesAllowed({"role1", "role2"}) public String foo() { }
- Remarques relative à l'utilisation des annotations de sécurité et la configuration des contraintes de sécurité
-
Les annotations de sécurité suivent le modèle de sécurité déclaratif. Les contraintes de sécurité définies dans le descripteur de déploiement, le fichier web.xml, prévalent sur les contraintes de sécurité annotées par programme dans l'application. Il est important que les développeurs des ressources JAX-RS équilibrent les contraintes de sécurité configurables et les contraintes de sécurité annotées. Les contraintes annotées complètent les contraintes de sécurité configurées. L'environnement d'exécution JAX-RS recherche les contraintes annotées après que l'environnement d'exécution du conteneur Web a recherché les contraintes de sécurité définies dans le fichier web.xml.
Définissez les contraintes d'authentification dans le fichier web.xml. Dans l'exemple de fichier suivant web.xml, la contrainte de sécurité SecurityConstraint_1 est définie. Cette contrainte est utilisée pour demander l'authentification auprès de l'application. En outre, la contrainte de sécurité SecurityConstraint_1 définit les contraintes dans les modèles URL correspondant aux ressources JAX-RS. Lorsqu'une ressource JAX-RS faisant l'objet d'un accès correspond à l'une de ces contraintes, des vérifications d'autorisation sont exécutées. Ces vérifications sont exécutées pour les annotations de sécurité déclaratives uniquement après que les contraintes définies ont été vérifiées.<web-app id="WebApp_someID"> <servlet> <servlet-name>AddressBookAppSample</servlet-name> <servlet-class> com.ibm.websphere.jaxrs.server.IBMRestServlet </servlet-class> <init-param> <param-name>javax.ws.rs.Application</param-name> <param-value>jaxrs.sample.AddressBookApplication</param-value> </init-param> <load-on-startup>1</load-on-startup> </servlet> <servlet-mapping> <servlet-name>AddressBookApp</servlet-name> <url-pattern>/*</url-pattern> </servlet-mapping> <security-constraint id="SecurityConstraint_1"> <web-resource-collection id="WebResourceCollection_1"> <web-resource-name>AddressBookAppSample</web-resource-name> <description>Protection area for Rest Servlet</description> <url-pattern>/*</url-pattern> <http-method>GET</http-method> <http-method>POST</http-method> <http-method>PUT</http-method> </web-resource-collection> <auth-constraint id="AuthConstraint_1"> <description>Role1 for this rest servlet</description> <role-name>Role</role-name> </auth-constraint> <user-data-constraint id="UserDataConstraint_1"> <transport-guarantee>CONFIDENTIAL</transport-guarantee> </user-data-constraint> </security-constraint> <security-role id="SecurityRole_1"> <description>This Role is used to drive authentication</description> <role-name>Role1</role-name> </security-role> <login-config> <auth-method>BASIC</auth-method> <realm-name>test realm</realm-name> </login-config> </web-app>
Dans l'exemple de fichier web.xml précédent, Role1 est utilisé pour l'ensemble de l'application. Si vous définissez uniquement des annotations de sécurité déclaratives et que vous n'utilisez pas les contraintes d'autorisation du fichier web.xml, vous pouvez associer ce rôle pour l'application JAX-RS application au sujett spécial AllAuthenticated pour l'authentification des utilisateurs.
Procédure
- Déterminez si des contraintes de sécurité sont définies par le fichier web.xml pour l'application JAX-RS.
- Configurez le fichier web.xml pour ajouter des contraintes de sécurité. Les contraintes de sécurité définies dans le descripteur de déploiement, le fichier web.xml, prévalent sur les contraintes de sécurité annotées par programme dans l'application.
- Déterminez si vous voulez ajouter des annotations de sécurité en plus de contraintes de sécurité dans le fichier web.xml. Déterminez si vous voulez ajouter l'une des annotations @PermitAll, @DenyAll et @RolesAllowed pour étendre la sécurité des ressources JAX-RS. Tenez compte des règles d'ajout d'annotations de sécurité en termes de priorité et d'héritage, par exemple (voir ci-dessus).
Résultats
Vous avez défini des ressources JAX-RS en utilisant des annotations de sécurité déclaratives.
Exemple
@Path(value="/addresses")
@PermitAll
public class AddressBookResource {
@GET
@Produces(value="text/plain")
public String getList() {
}
@RolesAllowed(“Administrator”)
@PUT
public void updateList(String books) {
}
}