API REST de contrôle d'accès au portail

Vous pouvez accéder et modifier à distance les informations de contrôle d'accès pour des ressources via le protocole HTTP à l'aide des API REST de contrôle d'accès au portail.

L'API REST de contrôle d'accès au portail fournit les URI suivants :
Flux Member
ac:member:oid:<principalID>@role:<roleTypeName>@oid:<resourceID>
Flux Member Collection
ac:member:<roleTypeName>@oid:<resourceID>
Flux Role
ac:role:<roleTypeName>@oid:<resourceID>
Flux Role Collection
ac:role:oid:<resourceID>
Flux Resource Config
ac:resourceconfig:oid:<resourceID>
Flux Allowed Access
ac:access:oid:<resourceID>
Notes :
  • Le flux Member Collection est défini en tant que collection.
  • Le flux Role Collection est défini en tant que collection.
  • Le flux Member Collection autorise la méthode HTTP POST.
  • Les valeurs <roleTypeName> disponibles sont répertoriées dans le tableau présenté dans la rubrique Rôles.

Méthodes HTTP prises en charge

Tableau 1. Méthodes HTTP prises en charge pour les flux
Nom du flux méthode GET POST PUT DELETE
Membre 405 405 405 Supprime un membre du rôle indiqué.
Member Collection Renvoie tous les membre d'un rôle. Ajoute un principal au rôle indiqué. 405 405
Rôle Renvoie un rôle. 405 405 405
Role Collection Renvoie tous les rôles d'une ressource. 405 405 405
Resource Config Renvoie la configuration d'une ressource. 405 Modifie la configuration d'une ressource. 405
Allowed Access Renvoie tous les niveaux d'accès qui ont été accordés à l'utilisateur actif ou dont celui-ci a hérité. 405 405 405

Eléments de réponse communs

Les requêtes GET exécutées sur chacun des flux renvoient l'infrastructure XML suivante : Elle contient un lien vers elle-même, le titre du flux, l'ID du flux, l'URI du flux et l'horodatage de création du flux. Pour les flux de collection, le premier élément est un élément atom:feed qui inclut des éléments opensearch. Pour les autres flux, le premier élément est un élément atom:entry.
<?xml version="1.0" encoding="UTF-8"?>
<atom:feed xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:xhtml="http://www.w3.org/1999/xhtml" 
  xmlns:atom="http://www.w3.org/2005/Atom"
  xmlns:model="http://www.ibm.com/xmlns/prod/websphere/portal/v6.0.1/portal-model-elements"
  xmlns:ac="http://www.ibm.com/xmlns/prod/lotus/access-control/v1.0" 
  xmlns:portal="http://www.ibm.com/xmlns/prod/websphere/portal/v6.0.1/portal-model"
  xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/" 
  xmlns:base="http://www.ibm.com/xmlns/prod/websphere/portal/v6.0/ibm-portal-composite-base"
  xml:base="http://localhost:10039/wps/mycontenthandler/!ut/p/digest!F4eOOrdKv7QXA2o0iUT9A/T9A
                 /ac/member:User@oid:ibm.portal.Home">
  <atom:author>
    <atom:name>HCL Digital Experience Portal/6.1.0.3</atom:name>
  </atom:author>
  <atom:title>MemberCollection</atom:title>
  <atom:id>ac:member:User@oid:ibm.portal.Home</atom:id>
  <atom:link href="/wps/mycontenthandler/!ut/p/digest!F4eOOrdKv7QXA2o0iUT9A/ac/member:User@oid:ibm.portal.Home" 
             rel="self"
             type="application/atom+xml"/>
  <opensearch:startIndex>0</opensearch:startIndex>
  <opensearch:itemsPerPage>2147483647</opensearch:itemsPerPage>
  <opensearch:totalResults>0</opensearch:totalResults>
  <atom:updated>2009-10-01T06:03:51.850Z</atom:updated>
</atom:feed>

Eléments de réponse communs pour les flux de collection

Pour les flux de collection, le flux contient une liste d'éléments atom:entry. Chaque entrée contient les informations supplémentaires suivantes : l'ID de l'entrée, son URI, des liens supplémentaires, et un objet de contenu qui contient les informations proprement dites.
<atom:entry>
  <atom:id>ac:member:oid:8eAe13RO6G4CL3TGMIPDKBQ6MGHE53P02OTDI3T26M14LRSA6PDE@role:User@oid:
           6_CGAH47L00GN960I4GOF1G510I3</atom:id>
  <atom:title>MemberCollection</atom:title>
  <atom:updated>2009-10-01T05:56:58.341Z</atom:updated>
  <atom:link href="/wps/mycontenthandler/!ut/p/digest!F4eOOrdKv7QXA2o0iU-T9A
                   /ac/member:oid:8eAe13RO6G4CL3TGMIPDKBQ6MGHE53P02OTDI3T26M14LRSA6PDE@role
   :User@oid:6_CGAH47L00GN960I4GOF1G510I3" rel="edit" type="application/atom+xml"/>
  <atom:content type="application/xml">
    <ac:member ac:id="8eAe13RO6G4CL3TGMIPDKBQ6MGHE53P02OTDI3T26M14LRSA6PDE" 
               ac:DN="all authenticated portal users" ac:type="virtual"/>
  </atom:content>
</atom:entry>

Variables d'URI et intervalles de valeurs

<roleTypeName>
Nom insensible à la casse d'un type de rôle défini, par exemple, Manager, EDitor, usEr.
<resourceID>
ObjectID ou uniqueName d'une ressource, par exemple, ibm.portal.Home or 8eAe13RO6G4CL3TGMIPDKBQ6MGHE53P02OTDI3T26M14LRSA6PDE.
<principalID>
ObjectID d'un principal (utilisateur ou groupe), par exemple, 8eAe13RO6G4CL3TGMIPDKBQ6MGHE53P02OTDI3T26M14LRSA6PDE.

Flux Member et méthode DELETE

URI - ac:member:oid:<principalID>@role:<roleTypeName>@oid:<resourceID>

Paramètres - Aucun.

Méthode HTTP DELETE
  • Supprime le principal à partir du type de rôle RoleType sur la ressource indiquée.
  • API Java™ de contrôle d'accès au portail équivalente 
    accessControlHome.getRoleDataController(resourceID)
    .
  • Renvoie 200 si la conversion aboutit.
  • Renvoie 404 si la conversion de resourceID échoue.
  • Renvoie 400 si
    • roleTypeName n'est pas applicable.
    • Le rôle n'existe pas.
    • La résolution de principalID est impossible.
    • L'utilisateur en cours ne dispose pas des droits d'accès requis.

Flux Member Collection et méthode GET

URI - ac:member:<roleTypeName>@oid:<resourceID>

Paramètres -
start-index=n
Indique que le membre n-th du rôle figure en premier dans la liste de résultats.
max-results=m
Demande d'inclure au moins m membres dans la liste des résultats.
Méthode HTTP GET
  • Indique tous les membres mappés à un rôle unique pour une ressource.
  • Equivalent dans l'API Java™ de Portal Access Control : accessControlHome.getRoleData(resourceID).getMappedPrincipals(roleType)
  • Returns 200 if successful.
  • Returns 404 if resourceID cannot be resolved.
  • Renvoie 400 si roleTypeName ne s'applique pas.
L'exemple de code illustré ci-après est le résultat de la méthode GET. Chaque élément d'entrée de la collection de membres contient un unique élément de membre qui spécifie l'identité du membre. Vous pouvez utiliser le lien d'édition pour supprimer le membre du rôle (DELETE sur le flux Member).
<atom:entry ...>
...
<atom:title>MemberCollection</atom:title>
<atom:entry>
 <atom:id>ac:member:oid:8eAe13RO6G4CL3TGMIPDKBQ6MGHE53P02OTDI3T26M14LRSA6PDE@role:User@oid:
          6_CGAH47L00GN960I4GOF1G510I3</atom:id>
 <atom:title>MemberCollection</atom:title>
 <atom:updated>2009-10-01T05:56:58.341Z</atom:updated>
 <atom:link href="/wps/mycontenthandler/!ut/p/digest!F4eOOrdKv7QXA2o0iUT9A
                  /ac/member:oid:8eAe13RO6G4CL3TGMIPDKBQ6MGHE53P02OTDI3T26M14LRSA6PDE@role:
    Privileged%25252520User@oid:6_CGAH47L00GN960I4GOF1G510I3" 
    rel="edit" type="application/atom+xml"/>
 <atom:content type="application/xml">
  <ac:member ac:id="8eAe13RO6G4CL3TGMIPDKBQ6MGHE53P02OTDI3T26M14LRSA6PDE"
             ac:DN="all authenticated portal users" ac:type="virtual"/>
 </atom:content>
</atom:entry>

Flux Member Collection et méthode POST

URI - ac:member: <roleTypeName>@oid:<resourceID>

Paramètres - Aucun.

Méthode HTTP POST
  • Ajoute le principal indiqué dans le contenu au type de rôle RoleType indiqué sur la ressource indiquée.
  • Equivalent Portal Access Control Java™ API 
    accessControlHome.getRoleDataController(resourceID).addPrincipalsToRole(RoleType, Collection<Principal>)
  • Renvoie 201 si la conversion aboutit.
  • Renvoie 404 si
    • La résolution de resourceID est impossible.
    • La résolution du principal indiqué est impossible à partir de son nom distinctif (DN) ou de son adresse électronique.
  • Returns 400 if
    • roleTypeName n'est pas applicable.
    • Le principal spécifié ne peut pas être résolu à partir de son oid.
    • L'utilisateur en cours ne dispose pas des droits d'accès requis.

Le contenu de la méthode POST pour le flux Member Collection se présente comme suit :

UID - ac:member: <roleTypeName>@oid:<resourceID>

Le contenu doit au moins comprendre ce qui suit : 
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom">
  <atom:content type="application/xml">
    <ac:member xmlns:ac="http://www.ibm.com/xmlns/prod/lotus/access-control/v1.0" 
                    ac:id="9eAe6BD86PGCHPD6JMCCG1D8MMG63JD0JM4C3BDAJMK66BC46O"/>
  </atom:content>
</atom:entry>
Au lieu de l'élément ac:id, qui est utilisé pour identifier un principal à l'aide de l'ObjectID, vous pouvez utiliser les identificateurs suivants :
ac:DN="uid=wpsadmin,o=defaultWIMFileBasedRealm"
Indique le principal à l'aide du nom distinctif. Le type peut être user, group ou virtual (pour un principal virtuel). La valeur par défaut est user. Les principaux virtuels valides sont définis dans les documents Javadoc suivants : com.ibm.portal.um.PumaEnvironment.VirtualPrincipalNames. Actuellement, il s'agit de all authenticated portal users, all portal user groups et anonymous portal user.
ac:email="wpsadmin@de.ibm.com"
Identifie les utilisateurs via leur adresses électronique.

Flux Role et méthode GET

URI - ac:role:<roleTypeName>@oid:<resourceID>

Paramètres
resolve-membership
Spécifiez la valeur true ou false. Si la valeur est true, les membres sont inclus. La valeur par défaut est false.
Méthode HTTP GET
  • Renvoie des informations sur un rôle disponible pour une ressource donnée.
  • Le rôle est disponible si au moins un principal y est mappé, sinon la méthode renvoie 404.
  • API Java™ de contrôle d'accès au portail équivalente : accessControlHome.getRoleData(resourceID).getRole(RoleType).
  • Returns 200 if successful.
  • Returns 404 if
    • La résolution de resourceID est impossible.
    • Le rôle pour l'élément roleTypeName spécifié n'est pas disponible.
  • Returns 400 if roleTypeName is not applicable.
La méthode GET renvoie le résultat suivant : 
<atom:entry ...>
  ...
  <atom:title>Role</atom:title>
  <atom:id>ac:role:User@oid:myPage</atom:id>
  <atom:link href="/wps/mypoc/!ut/p/digest!TSVlGy5DI0S5vyp5i;yTw
                   /ac/role:User@oid:myPage?mode=download&amp;resolve-membership=true"
    rel="self" type="application/atom+xml"/>
  <atom:updated>2009-10-01T12:35:05.442Z</atom:updated>
  <atom:link ac:rel="members" href="/wps/mycontenthandler/!ut/p/digest!TSVlGy5DI0S5vyp5i;yTw
            /ac/member:User@oid:6_M8768B1A00FT20I480O8A53000?
   resolve-membership=true" rel="related" type="application/atom+xml"/>
 <atom:content type="application/xml">
  <ac:role ac:type="User">
   <ac:member
     ac:id="8eAeI9EE3J5C63C8JM064RD2JMG613C2MM4C6BP4MM072JD6MI17P9E03R86H1"ac:display-name="wpsadmins"
     ac:DN="cn=wpsadmins,o=defaultWIMFileBasedRealm" ac:type="group"/>
  </ac:role>
 </atom:content>
</atom:entry>

Flux Role Collection et méthode GET

URI - ac:role:oid:<resourceID>

Paramètres -
filter
Indiquez l'une des valeurs suivantes :
  • type=<roleTypeName> pour renvoyer le rôle indiqué, s'il est disponible.
  • inUse pour renvoyer les rôles disponibles. Il s'agit de la valeur par défaut.
  • all pour renvoyer tous les types de rôles applicables.
start-index=n
Demande que le membre n-th du rôle figure en premier dans la liste des résultats.
max-results=m
Specifies that at most m members are included.
URI - ac:role:oid:<resourceID>
Méthode HTTP GET
  • Fournit des informations sur tous les rôles disponibles pour une ressource.
  • Un rôle est disponible si au moins un principal y est mappé.
  • Equivalent Portal Access Control Java™ API 
    accessControlHome.getRoleData(resourceID).getRoles()
  • Returns 200 if successful.
  • Returns 404 if resourceID cannot be resolved.
  • Renvoie 400 si l'élément roleTypeName spécifié ne s'applique pas.
La méthode GET renvoie le résultat suivant : 
<atom:feed ...>
  ...
  <atom:title>RoleCollection</atom:title>
  <atom:id>ac:role:oid:myPage</atom:id>
  <atom:link href="/wps/mypoc/!ut/p/digest!TSVlGy5DI0S5vyp5i;yTw/ac/role:oid:myPage?mode=download" 
        rel="self" type="application/atom+xml"/>
  <opensearch:startIndex>0</opensearch:startIndex>
  <opensearch:itemsPerPage>2147483647</opensearch:itemsPerPage>
  <opensearch:totalResults>1</opensearch:totalResults>
  <atom:updated>2009-10-01T12:46:16.509Z</atom:updated>
  <atom:entry>
  <atom:id>ac:role:User@oid:6_M8768B1A00FT20I480O8A53000</atom:id>
  <atom:title>RoleCollection</atom:title>
  <atom:updated>2009-10-01T12:46:16.509Z</atom:updated>
  <atom:link ac:rel="members" href="/wps/mycontenthandler/!ut/p/digest!TSVlGy5DI0S5vyp5i;yTw
            /ac/member:User@oid:6_M8768B1A00FT20I480O8A53000"
    rel="related" type="application/atom+xml"/>
  <atom:link href="/wps/mypoc/!ut/p/digest!TSVlGy5DI0S5vyp5i;yTw
                  /ac/role:User@oid:6_M8768B1A00FT20I480O8A53000?mode=download"
    rel="self" type="application/atom+xml"/>
  <atom:content type="application/xml">
   <ac:role ac:type="User"/>
  </atom:content>
 </atom:entry>
</atom:feed>

Flux Resource Config et méthode GET

UID - ac:resourceconfig:oid:<resourceID>

Paramètres - Aucun.

Méthode HTTP GET
  • Renvoie des informations sur la configuration des ressources suivantes :
    • Propriétaire
    • Blocs de rôles
    • IsPrivate
  • Equivalent Portal Access Control Java™ API 
    accessControlHome.getManagedProtectedResource(resourceID)
  • Returns 200 if successful.
  • Returns 404 if resourceID cannot be resolved.
La méthode GET renvoie le résultat suivant : 
<atom:entry ...>
 ...
 <atom:title>ResourceConfig</atom:title>
 <atom:id>ac:resourceconfig:oid:myPage</atom:id>
 <atom:link href="/wps/mycontenthandler/!ut/p/digest!TSVlGy5DI0S5vyp5i;yTw
                  /ac/resourceconfig:oid:myPage" rel="self" type="application/atom+xml"/>
 <atom:updated>2009-10-01T12:15:59.683Z</atom:updated>
 <atom:content type="application/xml">
  <ac:resource-config>
   <ac:ownerac:id="9eAePPC2JP8C2ROIJMG6M1D8JMG6PPD0JM0723P8JM06KPOC6IH66BOCMQC6N1" 
      ac:display-name="wpsadmin"
      ac:DN="uid=wpsadmin,o=defaultWIMFileBasedRealm" ac:type="user"/>
   <ac:role-block ac:block-type="inheritance" ac:type="Privileged User"/>
   <ac:role-block ac:block-type="propagation" ac:type="Delegator"/>
  </ac:resource-config>
 </atom:content>
</atom:entry>

Flux Resource Config et méthode PUT

UID - ac:resourceconfig:oid:<resourceID>

Paramètres
mode
Indiquez l'une des valeurs suivantes :
  • merge pour ajouter des blocs de rôles aux blocs de rôles existants. Le propriétaire change si vous définissez cette valeur.
  • update pour remplacer des propriétaires et des blocs de rôles existants. Les propriétaires et les blocs de rôles sont supprimés si vous ne les indiquez pas. Il s'agit de la valeur par défaut.
Méthode HTTP PUT
  • Mettre à jour la configuration des ressources suivantes :
    • Propriétaire
    • Blocs de rôles
  • Equivalent Portal Access Control Java™ API 
    accessControlHome.getManagedProtectedResource(resourceID)
  • Returns 200 if successful.
  • Returns 404 if resourceID cannot be resolved.
  • Renvoie 400 si l'utilisateur actif n'a pas les droits d'accès requis.

Le contenu de la méthode PUT pour le flux Resource Config se présente comme suit :

URI - ac:resourceconfig:oid:<resourceID>

Le contenu doit se présenter comme suit : 
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" 
      xmlns:ac="http://www.ibm.com/xmlns/prod/lotus/access-control/v1.0" >
  <atom:content type="application/xml">
    <ac:resource-config>
      <ac:owner ac:id="9eAe6BD86PGCHPD6JMCCG1D8MMG63JD0JM4C3BDAJMK6"/>
      <ac:role-block ac:block-type="inheritance" ac:type="MANAger"/>
      <ac:role-block ac:block-type="propagation" ac:type="Editor"/>
      <ac:role-block ac:block-type="propagation" ac:type="user"/>
    </ac:resource-config>
  </atom:content>
</atom:entry>

Les éléments owner et role-block sont facultatifs.

Au lieu de ac:id, qui permet d'identifier le propriétaire à l'aide de l'ObjectID, utiilsez les identificateurs suivants :
ac:DN="uid=wpsadmin,o=defaultWIMFileBasedRealm" ac:type=user
Indique le principal à l'aide du nom distinctif. Le type peut être user, group ou virtual (pour un principal virtuel). La valeur par défaut est user.
ac:email="wpsadmin@de.ibm.com"
Identifie les utilisateurs via leur adresses électronique.

Flux Allowed Access et méthode GET

UID - ac:access:oid:<resourceID>

Paramètres - Aucun.

Méthode HTTP GET
  • Renvoie des informations d'exécution sur la ressource pour l'utilisateur en cours, notamment tous les niveaux d'accès que l'utilisateur en cours possède sur la ressource.
  • API de contrôle d'accès au portail Java™ équivalente : il n'existe pas de correspondance exacte avec l'API Java™. Toutefois, l'API suivante est appelée pour tous les roleTypes applicables : 
    accessControlHome.getAccessControlRuntimeModel(resourceID).hasPermission(roleType)
  • Returns 200 if successful.
  • Returns 404 if resourceID cannot be resolved.
La méthode GET renvoie le résultat suivant : 
<atom:entry...>
 ...
 <atom:title>allowed-access</atom:title>
 <atom:id>ac:access:oid:ibm.portal.Home</atom:id>
 <atom:link href="/wps/mycontenthandler/!ut/p/digest!TSVlGy5DI0S5vyp5i;yTw
                  /ac/access:oid:ibm.portal.Home" rel="self" type="application/atom+xml"/>
 <atom:updated>2009-10-01T12:55:16.620Z</atom:updated>
 <atom:content type="application/xml">
  <ac:allowed-access xmlns:ac="http://www.ibm.com/xmlns/prod/lotus/access-control/v1.0" 
                     ac:user-owned="false">
   <ac:access-level ac:type="Administrator"/>
   <ac:access-level ac:type="Security Administrator"/>
   <ac:access-level ac:type="Delegator"/>
   <ac:access-level ac:type="Manager"/>
   <ac:access-level ac:type="Editor"/>
   <ac:access-level ac:type="Contributor"/>
   <ac:access-level ac:type="Privileged User"/>
   <ac:access-level ac:type="User"/>
  </ac:allowed-access>
 </atom:content>
</atom:entry>