opendaylight/adsal/sal/api/src/main/java/org/opendaylight/controller/sal/authorization/IResourceAuthorization.java

   1
   2 /*
   3  * Copyright (c) 2013 Cisco Systems, Inc. and others.  All rights reserved.
   4  *
   5  * This program and the accompanying materials are made available under the
   6  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
   7  * and is available at http://www.eclipse.org/legal/epl-v10.html
   8  */
   9
  10 package org.opendaylight.controller.sal.authorization;
  11
  12 import java.util.List;
  13 import java.util.Set;
  14
  15 import org.opendaylight.controller.sal.utils.Status;
  16
  17 /**
  18  * Interface for applications which maintain an authorization
  19  * database for their resources. Respective application web bundle
  20  * and User Manager make use of this interface to retrieve
  21  * authorization information at user or and role level.
  22  */
  23 public interface IResourceAuthorization {
  24
  25     /**
  26      * Create a Role name for the application
  27      *
  28      * @param role  the role name
  29      * @param userLevel the user level in the application context
  30      * @return the status of the request
  31      */
  32     public Status createRole(String role, AppRoleLevel userLevel);
  33
  34     /**
  35      * Remove a Role
  36      *
  37      * @param role the role name
  38      * @return the status of the request
  39      */
  40     public Status removeRole(String role);
  41
  42     /**
  43      * Return the list of roles configured for the application
  44      *
  45      * @return the list of roles
  46      */
  47     public List<String> getRoles();
  48
  49     /**
  50      * Returns the application role level for the specified role. If the role is
  51      * not known to this application NOUSER will be returned as specified in
  52      * {@link AppRoleLevel}
  53      *
  54      * @param roleName
  55      *            the role name to query
  56      * @return the application level of the given role in the application
  57      *         context as specified by {@link AppRoleLevel}. If the role is not
  58      *         part of this application's roles, NOUSER is returned.
  59      */
  60     public AppRoleLevel getApplicationRoleLevel(String roleName);
  61
  62     /**
  63      * Returns whether the specified role is part of this application's roles
  64      *
  65      * @param roleName the role name to test
  66      * @return  true if the role belongs to this application, false otherwise
  67      */
  68     public boolean isApplicationRole(String roleName);
  69
  70     /**
  71      * Create a resource group for application.
  72      *
  73      * NOTE: Resource addition is "best effort", if an object is not of correct type,
  74      * it is discarded.
  75      *
  76      * @param groupName
  77      *            the name for the resource group
  78      * @param resources
  79      *            the list of resources for the group
  80      * @return the status of the request
  81      */
  82     public Status createResourceGroup(String groupName, List<Object> resources);
  83
  84     /**
  85      * Removes a resource group
  86      *
  87      * @param groupName the name of the group
  88      * @return the status of the request
  89      */
  90     public Status removeResourceGroup(String groupName);
  91
  92     /**
  93      * Returns the list of resource groups configured for the application
  94      *
  95      * @return the list of resource group names
  96      */
  97     public List<String> getResourceGroups();
  98
  99     /**
 100      * Assign a resource group to a role
 101      *
 102      * @param groupName the name of the resource group
 103      * @param privilege the access privilege role will have on the resource group
 104      * @param role the role name
 105      * @return the status of the request
 106      */
 107     @Deprecated
 108     public Status assignResourceGroupToRole(String groupName,
 109             Privilege privilege, String role);
 110
 111     /**
 112      * Assign a resource group to a role. The access privilege on the resources
 113      * is inferred by the AppRoleLevel associated to role.
 114      *
 115      * @param groupName the name of the resource group
 116      * @param role the role name
 117      * @return the status of the request
 118      */
 119     public Status assignResourceGroupToRole(String groupName, String role);
 120
 121     /**
 122      * Unassign the passed resource group from the specified role
 123      *
 124      * @param groupName the name of the resource group
 125      * @param role the role name
 126      * @return the status of the request
 127      */
 128     public Status unassignResourceGroupFromRole(String groupName, String role);
 129
 130     /**
 131      * Returns the list of resource groups the given Role is authorized to use
 132      * The returning object expresses the resource group name and the access
 133      * its privilege for the given user role
 134      *
 135      * @param role  the role name
 136      * @return list of resources
 137      */
 138     public List<ResourceGroup> getAuthorizedGroups(String role);
 139
 140     /**
 141      * Returns the list of resources contained in the given resource group
 142      *
 143      * @param groupName the resource group name
 144      * @return
 145      */
 146     public List<Object> getResources(String groupName);
 147
 148     /**
 149      * Returns the list of authorized resources for the given role
 150      * For each resource only the highest privilege occurrence is returned
 151      * @param role  the role name
 152      * @return the list of Resource
 153      */
 154     public List<Resource> getAuthorizedResources(String role);
 155
 156     /*
 157      * Per user name API
 158      */
 159     /**
 160      * Returns the controller user role level the passed user name is associated with
 161      *
 162      * @param userName the user name
 163      * @return the user role level as specified in {@link UserLevel}
 164      */
 165     public UserLevel getUserLevel(String userName);
 166
 167     /**
 168      * Returns the application context user role level the passed user name is associated with
 169      *
 170      * @param userName the user name
 171      * @return the user role level as specified in {@link AppRoleLevel}
 172      */
 173     public AppRoleLevel getUserApplicationLevel(String userName);
 174
 175     /**
 176      * Returns the list of resources (resource + privilege) associated
 177      * with the passed user name for this application context
 178      * For each resource only the highest privilege occurrence is returned
 179      *
 180      * @param userName the user name
 181      * @return the list of resources associated with this user name in this application context
 182      */
 183     public Set<Resource> getAllResourcesforUser(String userName);
 184
 185     /**
 186      * Returns the highest privilege that the user has on the specified
 187      * resource in this application context
 188      *
 189      * @param userName the user name
 190      * @param resource the given resource
 191      * @return the privilege the user has on the passed resource
 192      */
 193     public Privilege getResourcePrivilege(String userName, Object resource);
 194
 195     /**
 196      * Add a resource to a group
 197      *
 198      * @param groupName
 199      *            the resource group
 200      * @param resource
 201      *            the resource object
 202      * @return the status of the request
 203      */
 204     public Status addResourceToGroup(String groupName, Object resource);
 205
 206     /**
 207      * Remove a resource from a group
 208      *
 209      * @param groupName
 210      *            the resource group
 211      * @param resource
 212      *            the resource object
 213      * @return the status of the request
 214      */
 215     public Status removeResourceFromGroup(String groupName, Object resource);
 216
 217     /**
 218      * Return whether the specified user has access to this application. In
 219      * other words if the user is associated any roles belonging to this
 220      * application.
 221      *
 222      * @param userName
 223      *            the user name
 224      * @return true if the user has access to this application's resources,
 225      *         false otherwise
 226      */
 227     boolean isApplicationUser(String userName);
 228 }