org.camunda.bpm.engine.authorization.Authorization Maven / Gradle / Ivy
/*
* Copyright Camunda Services GmbH and/or licensed to Camunda Services GmbH
* under one or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information regarding copyright
* ownership. Camunda licenses this file to you under the Apache License,
* Version 2.0; you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.camunda.bpm.engine.authorization;
import org.camunda.bpm.engine.identity.Group;
import org.camunda.bpm.engine.identity.User;
import java.util.Date;
/**
* An {@link Authorization} assigns a set of {@link Permission Permissions}
* to an identity to interact with a given {@link Resource}.
* EXAMPLES:
*
* - User 'jonny' is authorized to start new instances of the 'invoice' process
* - Group 'marketing' is not authorized to cancel process instances.
* - Group 'marketing' is not allowed to use the tasklist application.
* - Nobody is allowed to edit process variables in the cockpit application,
* except the distinct user 'admin'.
*
*
* Identities
* Camunda Platform distinguishes two types of identities: users and
* groups. Authorizations can either range over all users
* (userId = {@link #ANY}), an individual {@link User} or a {@link Group} of users.
*
* Permissions
* A {@link Permission} defines the way an identity is allowed to interact
* with a certain resource. Examples of permissions are {@link Permissions#CREATE CREATE},
* {@link Permissions#READ READ}, {@link Permissions#UPDATE UPDATE},
* {@link Permissions#DELETE DELETE}, ... See {@link Permissions} for a set of
* built-in permissions.
*
* A single authorization object may assign multiple permissions to a single user
* and resource:
*
* authorization.addPermission(Permissions.READ);
* authorization.addPermission(Permissions.UPDATE);
* authorization.addPermission(Permissions.DELETE);
*
* On top of the built-in permissions, Camunda Platform allows using custom
* permission types.
*
* Resources
* Resources are the entities the user interacts with. Examples of resources are
* {@link Resources#GROUP GROUPS}, {@link Resources#USER USERS},
* process-definitions, process-instances, tasks ... See {@link Resources} for a set
* of built-in resource. The Camunda Platform framework supports custom resources.
*
* Authorization Type
* There are three types of authorizations:
*
* - Global Authorizations ({@link #AUTH_TYPE_GLOBAL}) range over
* all users and groups (userId = {@link #ANY}) and are usually used for fixing the
* "base" permission for a resource.
* - Grant Authorizations ({@link #AUTH_TYPE_GRANT}) range over
* users and groups and grant a set of permissions. Grant authorizations are commonly
* used for adding permissions to a user or group that the global authorization does not grant.
* - Revoke Authorizations ({@link #AUTH_TYPE_REVOKE}) range over
* users and groups and revoke a set of permissions. Revoke authorizations are commonly
* used for revoking permissions to a user or group the the global authorization grants.
*
*
*
* Authorization Precedence
* Authorizations may range over all users, an individual user or a group of users.
* They may apply to an individual resource instance or all instances of the same type
* (resourceId = {@link #ANY}). The precedence is as follows:
*
* - An authorization applying to an individual resource instance precedes an authorization
* applying to all instances of the same resource type.
* - An authorization for an individual user precedes an authorization for a group.
* - A Group authorization precedes a {@link #AUTH_TYPE_GLOBAL GLOBAL} authorization.
* - A Group {@link #AUTH_TYPE_REVOKE REVOKE} authorization precedes a Group
* {@link #AUTH_TYPE_GRANT GRANT} authorization.
*
*
*
* @author Daniel Meyer
* @since 7.0
*
*/
public interface Authorization {
/**
* A Global Authorization ranges over all users and groups (userId = {@link #ANY}) and are
* usually used for fixing the "base" permission for a resource.
*/
public static final int AUTH_TYPE_GLOBAL = 0;
/**
* A Grant Authorization ranges over a users or a group and grants a set of permissions.
* Grant authorizations are commonly used for adding permissions to a user or group that
* the global authorization revokes.
*/
public static final int AUTH_TYPE_GRANT = 1;
/**
* A Revoke Authorization ranges over a user or a group and revokes a set of permissions.
* Revoke authorizations are commonly used for revoking permissions to a user or group the
* the global authorization grants.
*/
public static final int AUTH_TYPE_REVOKE = 2;
/** The identifier used for relating to all users or all resourceIds.
* Cannot be used for groups.*/
public static final String ANY = "*";
/** allows granting a permission. Out-of-the-box constants can be found in {@link Permissions}.
* */
public void addPermission(Permission permission);
/** allows removing a permission. Out-of-the-box constants can be found in {@link Permissions}.
* */
public void removePermission(Permission permission);
/**
* Allows checking whether this authorization grants a specific permission.
*
* @param perm the permission to check for
* @throws IllegalStateException if this {@link Authorization} is of type {@link #AUTH_TYPE_REVOKE}
*/
public boolean isPermissionGranted(Permission permission);
/**
* Allows checking whether this authorization revokes a specific permission.
*
* @param perm the permission to check for
* @throws IllegalStateException if this {@link Authorization} is of type {@link #AUTH_TYPE_GRANT}
*/
public boolean isPermissionRevoked(Permission permission);
/**
* Allows checking whether this authorization grants every single permission.
*
* @return true if every single permission is granted otherwise false
* @throws IllegalStateException if this {@link Authorization} is of type {@link #AUTH_TYPE_REVOKE}
*/
boolean isEveryPermissionGranted();
/**
* Allows checking whether this authorization revokes every single permission.
*
* @return true if every single permission is revoked otherwise false
* @throws IllegalStateException if this {@link Authorization} is of type {@link #AUTH_TYPE_GRANT}
*/
boolean isEveryPermissionRevoked();
/**
* Allows checking whether this authorization grants / revokes a set of permissions.
* Usually the set of built-in permissions is used: {@link Permissions#values()}
*
* The return value of this method depends on the type of the authorization:
*
* - For {@link #AUTH_TYPE_GLOBAL}: all permissions in the parameter list granted by this authorization are returned.
* - For {@link #AUTH_TYPE_GRANT}: all permissions in the parameter list granted by this authorization are returned.
* - For {@link #AUTH_TYPE_REVOKE}: all permissions in the parameter list revoked by this authorization are returned.
*
*
* @param an array of permissions to check for.
* @return Returns the set of {@link Permission Permissions} provided by this {@link Authorization}.
* */
public Permission[] getPermissions(Permission[] permissions);
/**
* Sets the permissions to the provided value. Replaces all permissions.
*
* The effect of this method depends on the type of this authorization:
*
* - For {@link #AUTH_TYPE_GLOBAL}: all provided permissions are granted.
* - For {@link #AUTH_TYPE_GRANT}: all provided permissions are granted.
* - For {@link #AUTH_TYPE_REVOKE}: all provided permissions are revoked.
*
*
* @param a set of permissions.
* */
public void setPermissions(Permission[] permissions);
/** @return the ID of the {@link Authorization} object */
public String getId();
/**
* set the id of the resource
*/
public void setResourceId(String resourceId);
/**
* @return the id of the resource
*/
public String getResourceId();
/**
* sets the type of the resource
*/
public void setResourceType(int resourceTypeId);
/**
* sets the type of the resource
*/
public void setResource(Resource resource);
/**
* @return the type of the resource
*/
public int getResourceType();
/**
* set the id of the user this authorization is created for
*/
public void setUserId(String userId);
/**
* @return the id of the user this authorization is created for
*/
public String getUserId();
/**
* set the id of the group this authorization is created for
*/
public void setGroupId(String groupId);
/**
* @return the id of the group this authorization is created for
*/
public String getGroupId();
/**
* The type og the authorization. Legal values:
*
* - {@link #AUTH_TYPE_GLOBAL}
* - {@link #AUTH_TYPE_GRANT}
* - {@link #AUTH_TYPE_REVOKE}
*
*
* @return the type of the authorization.
*
*/
public int getAuthorizationType();
/**
* The removal time indicates the date a historic instance authorization is cleaned up
*
* A removal time can only be assigned to a historic instance authorization. An authorization
* belongs to a historic instance when its resource type is {@link Resources#HISTORIC_TASK}.
*
* @return
* - the date the historic instance authorization is cleaned up
*
- {@code null} if not related to a historic instance resource
*
- {@code null} if removal time strategy is end and the top-level instance is not finished
*/
Date getRemovalTime();
/**
* The process instance id of the top-level (root) process instance the historic instance
* authorization is related to
*
* A root process instance id is only assigned to a historic instance authorization. An
* authorization is related to a historic instance when its resource type is
* {@link Resources#HISTORIC_TASK}.
*
* @return
* - the process instance id of the top-level (root) process instance
*
- {@code null} if not related to a historic instance resource
*/
String getRootProcessInstanceId();
}