# Contents of /trunk/projects/grid/gms/doc/GMS.tex

Revision 5189 - (show annotations)
Wed Oct 24 23:40:14 2018 UTC (21 months, 1 week ago) by major.brian
File MIME type: application/x-tex
File size: 17293 byte(s)
GMS WD updates

 1 \documentclass[11pt,a4paper]{ivoa} 2 \input tthdefs 3 4 \title{Group Membership Service} 5 6 \ivoagroup{Grid and Web Services} 7 8 \author{Brian Major} 9 \author{Patrick Dowler} 10 \author{Marco Molinaro} 11 12 \editor{Brian Major} 13 14 % \previousversion[????URL????]{????Funny Label????} 15 \previousversion{This is the first public release} 16 17 \begin{document} 18 \begin{abstract} 19 20 The Group Membership Service (GMS) specification describes a service-oriented interface for determining whether a user is a member of a group. This information can be used to protect access to proprietary resources: clients can issue a call to GMS when an authorization decision needs to be made. Proprietary resources can be any number of things such as data, metadata or services. Because a single group can be used to protect multiple resources, GMS enables the creation of groups that represent teams with common authorization rights. GMS offers organizations an interoperable, flexible and scalable way of protecting a hetergenous set of resources. 21 22 \end{abstract} 23 24 \section*{Acknowledgments} 25 26 ???? Or remove the section header ???? 27 28 \section*{Conformance-related definitions} 29 30 The words MUST'', SHALL'', SHOULD'', MAY'', RECOMMENDED'', and 31 OPTIONAL'' (in upper or lower case) used in this document are to be 32 interpreted as described in IETF standard RFC2119 \citep{std:RFC2119}. 33 34 The \emph{Virtual Observatory (VO)} is a 35 general term for a collection of federated resources that can be used 36 to conduct astronomical research, education, and outreach. 37 The \href{http://www.ivoa.net}{International 38 Virtual Observatory Alliance (IVOA)} is a global 39 collaboration of separately funded projects to develop standards and 40 infrastructure that enable VO applications. 41 42 43 \section{Introduction} 44 45 Through standard IVOA protocols, many astronomy data centres and institutes offer users access to datasets (SODA \citep{std:SODA}, Datalink \citep{std:Datalink}, etc), metadata (TAP \citep{std:TAP}) and storage (VOSpace \citep{std:VOSpace}). In some cases this information is proprietary--it is only allowed to be accessed by certain individuals. Due to the wide variety and inherently institute-specific set of rules that may define how the information is proprietary, it is beneficial to the owners and maintainers of the rules to have a standard way of describing who has access to what resources. Additionally, the rules describing resource access may be determined by an entity external to the holder of these resources. To these ends, this document sets out a standard, programatic, and interoperable method of determining whether a given user is allowed to access a given resource. 46 47 The ideas presented by GMS enable data centres to do authorization checks in an interoperable fashion. In the context of authorization, interoperability can viewed on two levels: interoperability amongst the cooperating services \emph{within} a data centre, and interoperability \emph{between} data centres. Because of the orthogonal nature of authorization, these levels amount to the same problem. 48 49 Interoperability aside, GMS describes a simple, general, maintainable, and scalable approach to performing authorization, and so is a recommended architectural pattern for managing access to proprietary resources. 50 51 \subsection{Proprietary resources} 52 53 Most facilities have a period of time in which only the Principal Investigator's team has access to observation metadata and data files. Even without a proprietary period, time is required to verify and validate observations before they can be made public. 54 55 Projects also frequently create higher level products such as catalogs and images. When these products are stored in a data centre, they must be accessible to only those who are authorized. 56 57 Proprietary information exists. For it to be made available in a data centre to those with authorization, a way of performing that authorization check is required. 58 59 \subsection{Role within the VO Architecture} 60 61 \begin{figure} 62 \centering 63 64 % Get the architecture diagram from the TCG chair 65 66 % If they give you a PDF, for now dumb it down to a png by 67 % convert -antialias -density 72x72 archdiag.pdf archdiag.png 68 % Oh -- Notes don't need this; you'd have to remove archdiag.png 69 % from FIGURES in the Makefile, too. 70 71 \includegraphics[width=0.9\textwidth]{archdiag.png} 72 \caption{Architecture diagram for this document} 73 \label{fig:archdiag} 74 \end{figure} 75 76 Fig.~\ref{fig:archdiag} shows the role this document plays within the 77 IVOA architecture \citep{note:VOARCH}. 78 79 GMS can be used by any software that needs to check, for authorization purposes, whether a user is a member of group. Because of this general use case, GMS cuts through all of the IVOA and lies squarely in the middle of the SHARING technical resource in the IVOA architecture diagram. 80 81 \subsection{Use Cases} 82 83 Asside from the main use case of restricting access to proprietary resources, GMS supports a number of other use cases, of both the user and system variety. 84 85 \paragraph{Proprietary information} Restricting access to proprietary resources to certain users. 86 87 \paragraph{Homogeneity} Using the same mechanism to control access to proprietary resources in a data centre or in multiple data centres. 88 89 \paragraph{Scalability} A distributed mechanism that scales linearly with the resources being protected. 90 91 \paragraph{Remotely managing access} A project may wish to control access to resources that reside externally. 92 93 \paragraph{Access rule sharing} A project may consist of a variety of resources that can be all managed by the same access rules. 94 95 \paragraph{Extending the services of a data centre} A project that has hosted data and metadata at a data centre may wish to create value-added services outside of the data centre itself. If some of the data or metadata is proprietary, the extended services may need to determine if a user is allowed to perform certain action on that data or metadata. 96 97 \paragraph{Cooperating institutes} Two or more institutes may work together on a single project that involves proprietary resources so require a common mechanism for protecting those resources. 98 99 \subsection{Definitions} 100 101 \paragraph{Authentication} User identification through credentials or identity provider. See IVOA Single-Sign-On Profile: Authentication Mechanisms. \citep{std:SSOAUTH} 102 103 \paragraph{Authorization} Making the decision of whether to grant a user permission to a given resource. The decision can involve knowing the user's identity. 104 105 \paragraph{Resource} Something that may require authorization for access. For example, a service, a data file, metadata. 106 107 \paragraph{User} An individual identified by authentication. 108 109 \paragraph{Group} A set of users. 110 111 \paragraph{Grant} Authorizing access to a protected resource by assigning a group. 112 113 \paragraph{Revoke} Removing access to a protected resource by removing an assigned group. 114 115 \paragraph{Owner} A user or group of users who may grant or revoke access to a specific resource. 116 117 \section{Authorization Requirements} 118 119 When looking at a system that has proprietary resources that need to be protected, it is clear that there are two distinct phases to authorization: the assignment of the rules protecting the resources, and the attempts by various users to gain access to those resources. They are described here: 120 121 \begin{enumerate} 122 \item The owner(s) of a resource may, at any time, change the rules by which a resource may be accessed. This is the \emph{granting and revoking of access}. 123 \item When users try to access resources, the granting rules for that resource are evaluated at runtime. This is the \emph{authorization check}. 124 \end{enumerate} 125 126 With these phases in mind and with the use cases defined, we can state that the goals of authorization are to: 127 128 \begin{itemize} 129 \item To allow for restricted access certain resources: only a certain set of individuals may access certain resources. 130 \item To allow certain individuals to set the access rules on resources. The owner(s) of the resources need to manage the access rules. 131 \item To be able to re-use granting rules between resources. Projects must authorize access to a variety of proprietary resources. 132 \item To be able manage granting rules at a single location. Projects should not have to update each resource on a change to a re-used grant. 133 \item To be able to reference remote granting rules. Proprietary resources should not be confined to a single institution. 134 \end{itemize} 135 136 \section{Groups} 137 138 Why are groups a good model for authorization? When a system needs to perform an \emph{authorization check} on a resource, it is trying to determine if the authenticated user is allowed access. There are a number of options on how this can be accomplished. 139 140 A simple approach would be to add the identity of the user to the resource. However, this is too restrictive as there may be multiple users who are allowed access. So, we could instead add a list of user identities to the resource being protected. It becomes a problem when there are two resources that need protecting by the same set of individuals. This becomes difficult to maintain because a change in access rules (\emph{granting and revoking access}) would mean a change to multiple resources. 141 142 So, it becomes clear that this list of users needs to be decoupled from the resource so that it can be referenced and shared by multiple resources. To do so, the list must become a single entity than can be referenced by a name. And so, we must now have a named group of users. 143 144 A central repository of groups of users would introduce other problems: a single point of failure, and the inability to partition groups of users. Thus, the \emph{location} of the group must accompany the group reference so that it is possible to have multiple collections of groups of users and multiple assiciated GMS services. 145 146 Resources must then reference a group by a URI with a location and a name that is unique within that location. This is called the Group Identifier. 147 148 Systems must use the information in the group identifier to query location to determine if the user is a member of the group. Because the location may be outside of the immediate vicinity of the resource, this query must be performed in a standard and accessible manner and so is defined as a RESTful interface to group membership. 149 150 \subsection{Group Identifiers} 151 152 A Universal Group Identifier is an IVOID (\citep{std:VOID2}) used to uniquely identify groups. For GMS, there are three important components to the group ID: 153 154 \begin{enumerate} 155 \item \emph{The authority}: This identifies the location or instance of the group membership service. 156 \item \emph{The path}: Always starting with '/gms', indicating that it is a group URI, with '/instance-name' which is the name of the particular GMS instance within the authority. 157 \item \emph{The query}: Identifies the group within the authority and instance. The name of the group. 158 \end{enumerate} 159 160 Below is an example group identifier: 161 162 \begin{verbatim} 163 ivo://authority.example.com/gms/instance1?groupName 164 \end{verbatim} 165 166 To resolve the host GMS service URL, one would issue a query to RegTAP (\citep{std:RegTAP}) to find the accessURL in the interface for the authority: 167 168 \begin{verbatim} 169 SELECT access_url, security_method_id 170 FROM rr.interface 171 NATURAL JOIN rr.capability 172 NATURAL JOIN rr.resource 173 WHERE 174 ivoid = 'ivo://authority.example.com/gms/instance1' AND 175 standard_id = 'ivo://ivoa.net/std/gms#search-1.0' 176 \end{verbatim} 177 178 This would result in an access URL capable of supporting a GMS search on the group 'groupName'. For example: 179 180 \begin{verbatim} 181 http://server.example.com/myGMSImpl/search 182 \end{verbatim} 183 184 \section{GMS Search API} 185 186 The Group Membership Service (GMS) declares a RESTful API \citep{fielding00} that allows for the determination of whether a user is a member of a group. This is the GMS search capability and is identified by the following standardID: 187 188 \begin{verbatim} 189 ivo://ivoa.net/std/gms#search-1.0 190 \end{verbatim} 191 192 Within this capability, there are two functions: 193 \begin{itemize} 194 \item \emph{boolean isMember(Group, User)}: Return true if User is a member of Group. 195 \item \emph{list getMemberships(User)}: Return the list of Groups of which User is a member. 196 \end{itemize} 197 198 Group Membership System RESTful API 199 200 Mandatory Support: 201 \begin{verbatim} 202 GET /gms/groups 203 GET /gms/groups/{group} 204 \end{verbatim} 205 206 Optional Parameter Support: 207 \begin{verbatim} 208 user= 209 principal= 210 \end{verbatim} 211 212 Note that, in the mandatory API, there is no information about the user or the resource being protected in the GMS API. This is intentional. 213 Since it is the system representing the protected resource that is making the GMS call, it already knows the context of that call. If the ID resource were to be added to the GMS API, we would be unnecessarily coupling the resource with the data within the GMS service and creating an inflexible architecture. 214 The user is not a part of the API because the user is determined by identifying the authenticated caller of the service. It must be the user (or the delegated user) making the API call as explained in \ref{section:gmsandcdp}. 215 216 \section{GMS and Credential Delegation} 217 \label{section:gmsandcdp} 218 219 The GMS service follows the recommendations of the IVOA credential delegation protocol \citep{std:CDP} and requires that the calls to the service to be made by the user who initiated the request. Aside from the architectural benefits of employing this pattern, there are a number of information privacy concerns that are addressed. User and user group membership information is private and thus should only allowed to be viewed by the users themselves. So, the calls to GMS must be by the user, or by an authorized representative of the user. 220 221 Because it is the systems enforcing authorization on proprietary resources that need to make the calls to GMS, they must acquire the user's delegated credentials in order to make those calls. 222 223 TBD... 224 225 \section{Users} 226 227 The concept of users and user identity is core to group authorization. When a system makes a call to a GMS service to determine if the user trying to access the resource is a member of a group, the GMS service needs to identify that user with the users in various groups. 228 229 The collection of data centres and astronomy institutes likely have many ways of identifying users. They could be using external identity providers, they could have a local database of users, or may have a combination of these and other approaches. This specification does not require such a design. Instead, it requires simply that users can be uniquely identified within the scope of a GMS service's domain. If a user identity reaches beyond the scope of a GMS service's domain (such as an X.500 distinguished name \citep{std:RFC1779}), then it, too, may be referenced by the service. 230 231 The list of officially supported authentication protocols can be found in the IVOA Single-Sign-On Profile: Authentication Mechanisms \citep{std:SSOAUTH}. However, these protocols are 232 233 \subsection{User Identity} 234 235 TBD... 236 237 \section {Implementation} 238 239 Possible ways to implement GMS 240 241 \begin{itemize} 242 \item Via Grouper (groups in MySQL, users in LDAP) 243 \item LDAP only with memberOf plugin (supports groups-of-groups) 244 \item VOSpace implementation: ContainerNodes = groups, DataNodes = users 245 \end{itemize} 246 247 \subsection{User Identity} 248 \label{subsection:useridentity} 249 250 TBD - describe how to support multiple identities, how to design a system where no locally stored users are needed. 251 252 \subsection{Groups of Groups} 253 254 It may be functionally attractive to support groups within groups. If this is implemented, then the service must ensure that this representation is reflected by the service API. For example, if an isMember(g) call is made, and the group 'g' is a group within another group in which the user is a member, then the service must return true. Essentially, the service must denormalize (at runtime) the containment of groups within groups. 255 256 If one of the contained groups actually exists at another GMS instance, perhaps outside of the organization, then the service must transitively query that service to determine group membership. This of course requires that the user's delegated credentials be available in the GMS service itself and within any other GMS services it may call. Please refer to the note on the IVOA inter-service calling pattern for more detail \citep{note:IVOSvcPatterns} (not yet written!) 257 258 259 \subsection {Examples} 260 261 TBD 262 263 \section {Future considerations} 264 265 This document presents a standard way of making the authorization decision, but not for the granting and revoking of access. However, a number of examples are presented on how granting and revoking can work. These examples may define a path for standardization if the need arrises. 266 267 \appendix 268 269 \section{Convenient extensions to GMS}: 270 271 Group Management API could be provided: 272 \begin{itemize} 273 \item create/modify/delete groups 274 \item Add/remove members 275 \end{itemize} 276 277 \section{Changes from Previous Versions} 278 279 No previous versions yet. 280 % these would be subsections "Changes from v. WD-..." 281 % Use itemize environments. 282 283 284 \bibliography{ivoatex/ivoabib,ivoatex/docrepo} 285 286 287 \end{document}