001 /*
002 * Copyright (c) OSGi Alliance (2001, 2008). All Rights Reserved.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.osgi.service.useradmin;
017
018 /**
019 * The <code>Authorization</code> interface encapsulates an authorization context
020 * on which bundles can base authorization decisions, where appropriate.
021 * <p>
022 * Bundles associate the privilege to access restricted resources or operations
023 * with roles. Before granting access to a restricted resource or operation, a
024 * bundle will check if the <code>Authorization</code> object passed to it possess
025 * the required role, by calling its <code>hasRole</code> method.
026 * <p>
027 * Authorization contexts are instantiated by calling the
028 * {@link UserAdmin#getAuthorization} method.
029 *
030 * <p>
031 * <i>Trusting Authorization objects </i>
032 * <p>
033 * There are no restrictions regarding the creation of <code>Authorization</code>
034 * objects. Hence, a service must only accept <code>Authorization</code> objects
035 * from bundles that has been authorized to use the service using code based (or
036 * Java 2) permissions.
037 *
038 * <p>
039 * In some cases it is useful to use <code>ServicePermission</code> to do the code
040 * based access control. A service basing user access control on
041 * <code>Authorization</code> objects passed to it, will then require that a
042 * calling bundle has the <code>ServicePermission</code> to get the service in
043 * question. This is the most convenient way. The OSGi environment will do the
044 * code based permission check when the calling bundle attempts to get the
045 * service from the service registry.
046 * <p>
047 * Example: A servlet using a service on a user's behalf. The bundle with the
048 * servlet must be given the <code>ServicePermission</code> to get the Http
049 * Service.
050 * <p>
051 * However, in some cases the code based permission checks need to be more
052 * fine-grained. A service might allow all bundles to get it, but require
053 * certain code based permissions for some of its methods.
054 * <p>
055 * Example: A servlet using a service on a user's behalf, where some service
056 * functionality is open to anyone, and some is restricted by code based
057 * permissions. When a restricted method is called (e.g., one handing over an
058 * <code>Authorization</code> object), the service explicitly checks that the
059 * calling bundle has permission to make the call.
060 *
061 * @version $Revision: 5673 $
062 */
063 public interface Authorization {
064 /**
065 * Gets the name of the {@link User} that this <code>Authorization</code>
066 * context was created for.
067 *
068 * @return The name of the {@link User} object that this
069 * <code>Authorization</code> context was created for, or
070 * <code>null</code> if no user was specified when this
071 * <code>Authorization</code> context was created.
072 */
073 public String getName();
074
075 /**
076 * Checks if the role with the specified name is implied by this
077 * <code>Authorization</code> context.
078 * <p>
079 *
080 * Bundles must define globally unique role names that are associated with
081 * the privilege of accessing restricted resources or operations. Operators
082 * will grant users access to these resources, by creating a {@link Group}
083 * object for each role and adding {@link User} objects to it.
084 *
085 * @param name The name of the role to check for.
086 *
087 * @return <code>true</code> if this <code>Authorization</code> context implies
088 * the specified role, otherwise <code>false</code>.
089 */
090 public boolean hasRole(String name);
091
092 /**
093 * Gets the names of all roles implied by this <code>Authorization</code>
094 * context.
095 *
096 * @return The names of all roles implied by this
097 * <code>Authorization</code> context, or <code>null</code> if no roles
098 * are in the context. The predefined role <code>user.anyone</code>
099 * will not be included in this list.
100 */
101 public String[] getRoles();
102 }