.\" Copyright (c) 2003-2012 .\" Distributed Systems Software. All rights reserved. .\" See the file LICENSE for redistribution information. .\" $Id: copyright-nr 2564 2012-03-02 00:17:08Z brachman $ '\" t .\" Title: dacs.groups .\" Author: [see the "AUTHOR" section] .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 08/23/2020 .\" Manual: DACS Formats Manual .\" Source: DACS 1.4.40 .\" Language: English .\" .TH "DACS\&.GROUPS" "5" "08/23/2020" "DACS 1.4.40" "DACS Formats Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" dacs.groups \- \fBDACS\fR groups .SH "DESCRIPTION" .PP These files are part of the \fBDACS\fR suite\&. .PP Groups are a convenient shorthand for a jurisdiction\*(Aqs administrator to use when specifying access control rules\&. Rather than explicitly listing the set of users who have certain access rights to a service, an administrator can reference a group name that represents the membership of the set\&. The set\*(Aqs membership is built dynamically and consists of any combination of users and other group names\&. The membership of a particular group may vary over time and is resolved when a service request is subjected to access control\&. A jurisdiction may define any number of groups and specify their membership; these definitions may then be referenced by other jurisdictions, in their access control rules and their group definitions\&. It is the task of the \fBDACS\fR group membership service to manage group membership and determine the set of users who belong to each group defined within \fBDACS\fR\&. .PP A group\*(Aqs membership is determined solely by the administrator of the jurisdiction that defines it, unless membership is delegated to other jurisdictions\&. .PP For its own purposes, a jurisdiction often maintains group membership information, such as the organizational unit within the jurisdiction to which each of its users belong\&. \fBDACS\fR can consult such a group membership database to associate roles (or "internal\-group membership") with the jurisdiction\*(Aqs users\&. This separately maintained information may easily be imported into \fBDACS\fR, eliminating the administrative burden that would arise from having to maintain the same information within two different systems\&. .PP When \fBDACS\fR needs to resolve group membership to determine whether the user making a service request is a member of a particular group, it may need to consult any combination of local group definitions, the roles associated with the user, and remote group definitions (groups defined by other jurisdictions)\&. .PP \fBDACS\fR does not dictate any particular method of storing group information; group information is accessed through the \fBDACS\fR virtual filestore\&. .PP Every referenced group must be defined somewhere within \fBDACS\fR, whether locally or by another jurisdiction, before the referencing group is considered valid by \fBDACS\fR\&. .SS "Role\-Based Group Membership" .PP Jurisdictions, such as companies or organizations, typically have a hierarchical internal structure, perhaps based on subdivisions such as departments, groups, projects, and so on\&. Typically, an individual is associated with one or more of these subdivisions\&. Alternatively, jurisdictions might use an organizational structure that is based on the role of each individual\&. .PP Regardless of the type of structure, jurisdictions may have information services that describe and manage where an individual belongs within that structure\&. A directory system, such as X\&.500 or Microsoft\*(Aqs Active Directory, which is typically accessible using the \m[blue]\fBLightweight Directory Access Protocol (LDAP)\fR\m[]\&\s-2\u[1]\d\s+2, is a common example of such an information service\&. Another example is found in Unix\-type systems, which assign their users to \m[blue]\fBgroups\fR\m[]\&\s-2\u[2]\d\s+2 for access control purposes\&. By exporting this information, or by creating and managing its own group definitions, a jurisdiction can use \fBDACS\fR to provide role\-based security\&. .PP \fBDACS\fR uses the concept of a role\-based group to allow a jurisdiction to implicitly create groups and associate users with them\&. At authentication time, a jurisdiction can indicate which roles a user belongs to within the jurisdiction\&. This information becomes part of the user\*(Aqs credentials and is consulted when determining whether the user is a member of a given group\&. The entire membership of a role\-based group, potentially very large and possibly sensitive, need never be revealed or distributed to other jurisdictions\&. .PP Group information may sometimes be extracted from a directory system by processing the distinguished names of users\&. Consider a distinguished name like the following, which might be retrieved from a directory system: .sp .if n \{\ .RS 4 .\} .nf {cou=CA, prov=BC, o=BigBank, ou=RandD, ou=Software, ou=Networks, cn=Auggie Doggie} .fi .if n \{\ .RE .\} .sp For this individual, a role descriptor asserting membership in three groups within the jurisdiction might be produced: 1) RandD, 2) Software within RandD, and 3) Networks within Software under RandD\&. Within \fBDACS\fR access control rules, these groups might be referred to as "%BigBank:RandD", "%BigBank:RandD\-Software", and "%BigBank:RandD\-Software\-Networks", respectively\&. These group names may also be included in the membership of other groups\&. Also, a group having one of these names can be defined and administered using \fBDACS\fR\*(Aqs standard group membership methods; its membership is the union of the role\-based group members and the explicitly named group members\&. .PP A concise syntax is available for expressing hierarchically\-related elements of a role descriptor\&. The role descriptor "RandD/Software/Networks" is an equivalent way of expressing the three\-element descriptor given above\&. .PP It is relatively easy for a jurisdiction to use its existing services to export the required role description to \fBDACS\fR\&. The Roles clause (see \m[blue]\fB\fBdacs\&.conf(5)\fR\fR\m[]\&\s-2\u[3]\d\s+2) configures how this is done\&. .SS "Group Syntax and Semantics" .PP The following BNF syntax describes the names and symbols used in group definitions\&. Upper and lower case are distinct in the defined strings and all strings are constructed from a subset of the printable ASCII characters (e\&.g\&., the group name DSS:abc is different from the group name DSS:AbC)\&. .sp .if n \{\ .RS 4 .\} .nf ::= [A\-Za\-z][A\-Za\-z0\-9\e\-_]* ::= [A\-Za\-z][A\-Za\-z0\-9\e\-_]* .fi .if n \{\ .RE .\} .sp Thus, jurisdiction names and group names are composed of upper and lower case letters, digits, dashes, and underscores and must begin with a letter\&. .PP The name of a group is formed from two components: .sp .if n \{\ .RS 4 .\} .nf ::= \*(Aq:\*(Aq .fi .if n \{\ .RE .\} .sp The is the unique, officially\-assigned abbreviated name for the \fBDACS\fR jurisdiction\&. The is a unique name for the group within the jurisdiction that defines the \&. .PP The following XML DTD is used as the external representation of group definitions and membership\&. It is used by \fBDACS\fR both to distribute this information from one jurisdiction to another\&. .sp .if n \{\ .RS 4 .\} .nf .fi .if n \{\ .RE .\} .PP A group_definition gives the official name of the jurisdiction that defined the group (jurisdiction), a name for the group that is unique with that jurisdiction (name), the date and time the group\*(Aqs definition was last changed (mod_date) and whether the group\*(Aqs membership is to be kept private (type)\&. The date and time are expressed in UTC and using a 24 hour clock, in the format Wdy, DD\-Mon\-YYYY HH:MM:SS GMT, based on \m[blue]\fBRFC 822\fR\m[]\&\s-2\u[4]\d\s+2, with the variations that the only legal time zone is GMT and the separators between the elements of the date must be dashes\&. If public, the type attribute indicates that the group membership may be distributed to other jurisdictions and included in the definition of another group that is distributed\&. .PP Each group_member specifies a member of the group\&. The type is role if the named member is a role, username if it is a \fBDACS\fR username, and dacs if it is the name of another \fBDACS\fR group\&. The special type meta is reserved for the internal use of \fBDACS\fR and associated with this type only is the presence of information about the jurisdiction: dacs_url, name, altname, authenticates, and prompts, each of which must be present for this type, and auxiliary, which is optional\&. Refer to \m[blue]\fBDACS Metadata\fR\m[]\&\s-2\u[5]\d\s+2 for additional information\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br .PP In conjunction with \m[blue]\fBdacs_list_jurisdictions(8)\fR\m[]\&\s-2\u[6]\d\s+2, if the dacs_url attribute value does not begin with "http" or "https", then name interpolation is performed on the value as if by the \m[blue]\fBpathname()\fR\m[]\&\s-2\u[7]\d\s+2 function with \fIhostname\fR formed by prepending the name attribute value to the \m[blue]\fBFEDERATION_DOMAIN\fR\m[]\&\s-2\u[8]\d\s+2 and \fIport\fR obtained from the port associated with the \fBdacs_list_jurisdictions\fR request\&. .PP For example, assuming FEDERATION_DOMAIN is test\-03\&.example\&.com and given the entry: .sp .if n \{\ .RS 4 .\} .nf .fi .if n \{\ .RE .\} .sp and the request: .sp .if n \{\ .RS 4 .\} .nf http://test\-03\&.example\&.com/fedadmin/dacs/dacs_list_jurisdictions .fi .if n \{\ .RE .\} .sp then the effective value of dacs_url for the entry would be: .sp .if n \{\ .RS 4 .\} .nf http://test\-03\&.example\&.com/metalogic/dacs .fi .if n \{\ .RE .\} .PP And assuming FEDERATION_DOMAIN is dss\&.ca and given the entry: .sp .if n \{\ .RS 4 .\} .nf .fi .if n \{\ .RE .\} .sp and the request: .sp .if n \{\ .RS 4 .\} .nf https://dacs\&.dss\&.ca:8443/cgi\-bin/dacs/dacs_list_jurisdictions .fi .if n \{\ .RE .\} .sp then the effective value of dacs_url would be: .sp .if n \{\ .RS 4 .\} .nf https://dacs\&.dss\&.ca:8443/cgi\-bin/dacs .fi .if n \{\ .RE .\} .sp .5v .RE .PP If the type is role, any user who has credentials that name the given role is a member of the group\&. .PP The appearance of a group name in the membership list of a group definition effectively inserts the entire membership of that referenced group in the definition\&. This type of inclusion is recursive, allowing for a configurable maximum depth\&. A cycle of inclusions is detected and not considered an error\&. Duplicate members are culled from the final membership list\&. All invalid group definitions are considered by \fBDACS\fR to have no members (that is, they are treated as having an empty membership list)\&. The included group may belong to the same jurisdiction as the one being defined or it may refer to a group defined by some other jurisdiction\&. In the latter case, the administrator who defines the group delegates part of the responsibility for the group definition to another administrator who might do the same\&. .PP A group may be defined to be empty (i\&.e\&., not having any members)\&. .SS "DACS Metadata" .PP At each jurisdiction in a federation, \fBDACS\fR requires metadata that describes the jurisdictions\&. This information might be used by middleware or client\-side software, for instance, for creating a menu to present to the user, which would need to obtain a list of jurisdictions\&. The metadata is also used for various internal purposes\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBImportant\fR .ps -1 .br .PP The \fBDACS\fR metadata is stored in a group definition named "jurisdictions" relative to the groups item type\&. By default, at a jurisdiction with \m[blue]\fBJURISDICTION_NAME\fR\m[]\&\s-2\u[9]\d\s+2 BOBO in a federation with \m[blue]\fBFEDERATION_DOMAIN\fR\m[]\&\s-2\u[8]\d\s+2 example\&.com, this will be a file named jurisdictions\&.grp in the directory /usr/local/dacs/federations/example\&.com/BOBO/DACS\&. .PP \fBDACS\fR does not care about the values of the name and alt_name attributes, provided that they are well\-formed\&. The alt_name might provide descriptive information in another language\&. These attributes might be used by middleware to construct a menu for users to select their home jurisdiction when logging in, for instance\&. For consistency, a federation should consider adopting a convention across all jurisdictions for how these two attributes are used\&. .PP The dacs_url attribute is important because it tells \fBDACS\fR how to construct a URL for any \fBDACS\fR web service at the jurisdiction\&. .sp .5v .RE .PP Group information about jurisdictions is indicated by the meta attribute value for the type attribute\&. .PP This example group definition describes a four jurisdiction \fBDACS\fR federation: .sp .if n \{\ .RS 4 .\} .nf .fi .if n \{\ .RE .\} .sp .SH "EXAMPLES" .PP The group ON:gis is defined by the jurisdiction ON to consist of three ordinary users: .sp .if n \{\ .RS 4 .\} .nf .fi .if n \{\ .RE .\} .PP This example defines a group that includes other groups as members: .sp .if n \{\ .RS 4 .\} .nf .fi .if n \{\ .RE .\} .sp The group METALOGIC:admin is defined by jurisdiction METALOGIC to consist of the membership of three other groups (NF:admin, ON:admin, and BC:admin) and a user\&. .PP This group, BC:nobody, has no members: .sp .if n \{\ .RS 4 .\} .nf .fi .if n \{\ .RE .\} .PP Here is an example of a private group: .sp .if n \{\ .RS 4 .\} .nf .fi .if n \{\ .RE .\} .sp As the first group in the example above has been declared to be private, access control rules may be constructed to make its membership invisible to other jurisdictions, to forbid its definition from being forwarded to other jurisdictions, and so on\&. .PP Here is a group with dynamic, role\-based membership: .sp .if n \{\ .RS 4 .\} .nf .fi .if n \{\ .RE .\} .sp This definition references a role (ou_admin), a username, and a group\&. .SH "AUTHOR" .PP Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[10]\d\s+2) .SH "COPYING" .PP Copyright \(co 2003\-2018 Distributed Systems Software\&. See the \m[blue]\fBLICENSE\fR\m[]\&\s-2\u[11]\d\s+2 file that accompanies the distribution for licensing information\&. .SH "NOTES" .IP " 1." 4 Lightweight Directory Access Protocol (LDAP) .RS 4 \%https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol .RE .IP " 2." 4 groups .RS 4 \%https://www.freebsd.org/cgi/man.cgi?query=group&apropos=0&sektion=5&manpath=FreeBSD+10.3-RELEASE&format=html .RE .IP " 3." 4 \fBdacs.conf(5)\fR .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html .RE .IP " 4." 4 RFC 822 .RS 4 \%http://www.rfc-editor.org/rfc/rfc822.txt .RE .IP " 5." 4 DACS Metadata .RS 4 \%http://dacs.dss.ca/man/#dacs_metadata .RE .IP " 6." 4 dacs_list_jurisdictions(8) .RS 4 \%http://dacs.dss.ca/man/dacs_list_jurisdictions.8.html .RE .IP " 7." 4 pathname() .RS 4 \%http://dacs.dss.ca/man/dacs.exprs.5.html#pathname .RE .IP " 8." 4 FEDERATION_DOMAIN .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#FEDERATION_DOMAIN .RE .IP " 9." 4 JURISDICTION_NAME .RS 4 \%http://dacs.dss.ca/man/dacs.conf.5.html#JURISDICTION_NAME .RE .IP "10." 4 www.dss.ca .RS 4 \%http://www.dss.ca .RE .IP "11." 4 LICENSE .RS 4 \%http://dacs.dss.ca/man/../misc/LICENSE .RE