1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.shiro.authz;
20
21 import java.io.Serializable;
22 import java.util.Collection;
23
24 /**
25 * <code>AuthorizationInfo</code> represents a single Subject's stored authorization data (roles, permissions, etc.)
26 * used during authorization (access control) checks only.
27 * <p/>
28 * Roles are represented as a <code>Collection</code> of Strings
29 * ({@link java.util.Collection Collection}<{@link String String}>), typically each element being the Role name.
30 * <p/>
31 * {@link Permission Permission}s are provided in two ways:
32 * <ul>
33 * <li>A <code>Collection</code> of Strings, where each String can usually be converted into <code>Permission</code>
34 * objects by a <code>Realm</code>'s
35 * {@link org.apache.shiro.authz.permission.PermissionResolver PermissionResolver}</li>
36 * <li>A <code>Collection</code> of {@link Permission Permission} objects</li>
37 * </ul>
38 * Both permission collections together represent the total aggregate collection of permissions. You may use one
39 * or both depending on your preference and needs.
40 * <p/>
41 * Because the act of authorization (access control) is orthogonal to authentication (log-in), this interface is
42 * intended to represent only the account data needed by Shiro during an access control check
43 * (role, permission, etc.). Shiro also has a parallel
44 * {@link org.apache.shiro.authc.AuthenticationInfo AuthenticationInfo} interface for use during the authentication
45 * process that represents identity data such as principals and credentials.
46 * <p/>
47 * Because many if not most {@link org.apache.shiro.realm.Realm Realm}s store both sets of data for a Subject, it might be
48 * convenient for a <code>Realm</code> implementation to utilize an implementation of the
49 * {@link org.apache.shiro.authc.Account Account} interface instead, which is a convenience interface that combines both
50 * <code>AuthenticationInfo</code> and <code>AuthorizationInfo</code>. Whether you choose to implement these two
51 * interfaces separately or implement the one <code>Account</code> interface for a given <code>Realm</code> is
52 * entirely based on your application's needs or your preferences.
53 *
54 * @see org.apache.shiro.authc.AuthenticationInfo AuthenticationInfo
55 * @see org.apache.shiro.authc.Account
56 * @since 0.9
57 */
58 public interface AuthorizationInfo extends Serializable {
59
60 /**
61 * Returns the names of all roles assigned to a corresponding Subject.
62 *
63 * @return the names of all roles assigned to a corresponding Subject.
64 */
65 Collection<String> getRoles();
66
67 /**
68 * Returns all string-based permissions assigned to the corresponding Subject. The permissions here plus those
69 * returned from {@link #getObjectPermissions() getObjectPermissions()} represent the total set of permissions
70 * assigned. The aggregate set is used to perform a permission authorization check.
71 * <p/>
72 * This method is a convenience mechanism that allows Realms to represent permissions as Strings if they choose.
73 * When performing a security check, a <code>Realm</code> usually converts these strings to object
74 * {@link Permission Permission}s via an internal
75 * {@link org.apache.shiro.authz.permission.PermissionResolver PermissionResolver}
76 * in order to perform the actual permission check. This is not a requirement of course, since <code>Realm</code>s
77 * can perform security checks in whatever manner deemed necessary, but this explains the conversion mechanism that
78 * most Shiro Realms execute for string-based permission checks.
79 *
80 * @return all string-based permissions assigned to the corresponding Subject.
81 */
82 Collection<String> getStringPermissions();
83
84 /**
85 * Returns all type-safe {@link Permission Permission}s assigned to the corresponding Subject. The permissions
86 * returned from this method plus any returned from {@link #getStringPermissions() getStringPermissions()}
87 * represent the total set of permissions. The aggregate set is used to perform a permission authorization check.
88 *
89 * @return all type-safe {@link Permission Permission}s assigned to the corresponding Subject.
90 */
91 Collection<Permission> getObjectPermissions();
92 }