1 /*
2 * Licensed to The Apereo Foundation under one or more contributor license
3 * agreements. See the NOTICE file distributed with this work for additional
4 * information regarding copyright ownership.
5 *
6 *
7 * The Apereo Foundation licenses this file to you under the Educational
8 * Community License, Version 2.0 (the "License"); you may not use this file
9 * except in compliance with the License. You may obtain a copy of the License
10 * at:
11 *
12 * http://opensource.org/licenses/ecl2.txt
13 *
14 * Unless required by applicable law or agreed to in writing, software
15 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
16 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
17 * License for the specific language governing permissions and limitations under
18 * the License.
19 *
20 */
21
22 package org.opencastproject.security.api;
23
24 import org.opencastproject.mediapackage.Attachment;
25 import org.opencastproject.mediapackage.MediaPackage;
26 import org.opencastproject.mediapackage.MediaPackageException;
27 import org.opencastproject.util.data.Tuple;
28
29
30 /**
31 * Provides generation and interpretation of policy documents in media packages
32 */
33 public interface AuthorizationService {
34
35 /**
36 * Determines whether the current user can take the specified action on the media package.
37 *
38 * @param mp
39 * the media package
40 * @param action
41 * the action (e.g. read, modify, delete)
42 * @return whether the current user has the correct privileges to take this action
43 */
44 boolean hasPermission(MediaPackage mp, String action);
45
46 /**
47 * Determines whether the current user can take the specified action given the access control list.
48 * This is not restricted to access control lists in media packages, but works regardless of which entity the
49 * access control list belongs to.
50 *
51 * @param acl
52 * the access control list
53 * @param action
54 * the action (e.g. read, modify, delete)
55 * @return whether the current user has the correct privileges to take this action
56 */
57 boolean hasPermission(AccessControlList acl, String action);
58
59 /**
60 * Gets the active access control list associated with the given media package, as specified by its XACML
61 * attachments. XACML attachments are evaluated in the following order:
62 *
63 * <ol>
64 * <li>Use episode XACML attachment if present</li>
65 * <li>Use series XACML attachment if present</li>
66 * <li>Use non-specific XACML attachment if present. Note that the usage of this is deprecated!</li>
67 * <li>Use the global default ACL</li>
68 * </ol>
69 *
70 * Note that this is identical to calling {@link #getAcl(MediaPackage, AclScope)} with scope set to
71 * {@link AclScope#Series}.
72 *
73 * @param mp
74 * the media package
75 * @return the active access control list as well as the scope identifying the source of the access rules (episode,
76 * series, …).
77 */
78 Tuple<AccessControlList, AclScope> getActiveAcl(MediaPackage mp);
79
80 /**
81 * Gets the access control list for a given scope associated with the given media package, as specified by its XACML
82 * attachments. XACML attachments are evaluated in the following order:
83 *
84 * <ol>
85 * <li>Use episode XACML attachment if present. This applies only if scope is set to {@link AclScope#Episode}</li>
86 * <li>Use series XACML attachment if present. This applies only if scope is set to {@link AclScope#Episode} or
87 * {@link AclScope#Series}</li>
88 * <li>Use non-specific XACML attachment if present. Note that the usage of this is deprecated!</li>
89 * <li>Use the global default ACL</li>
90 * </ol>
91 *
92 * @param mp
93 * the media package
94 * @param scope
95 * the acl scope
96 * @return the access control list as well as the scope identifying the source of the access rules (episode,
97 * series, …) for the given media package and scope.
98 */
99 Tuple<AccessControlList, AclScope> getAcl(MediaPackage mp, AclScope scope);
100
101 /**
102 * Attaches the provided policies to a media package as a XACML attachment, replacing any previous policy element of
103 * the same scope.
104 *
105 * @param mp
106 * the media package
107 * @param scope
108 * scope of the ACL
109 * @param acl
110 * the tuples of roles to actions
111 * @return the mutated (!) media package with attached XACML policy and the XACML attachment
112 */
113 Tuple<MediaPackage, Attachment> setAcl(MediaPackage mp, AclScope scope, AccessControlList acl)
114 throws MediaPackageException;
115
116 /**
117 * Remove the XACML of the given scope.
118 *
119 * @param mp
120 * the media package
121 * @param scope
122 * scope of the ACL
123 * @return the mutated (!) media package with removed XACML policy
124 */
125 MediaPackage removeAcl(MediaPackage mp, AclScope scope);
126 }