Module AclService

Macros to manipulate owner and permission information of a repository item.

Since: 2.1

Macro Summary
external

LSAF
%lsaf_getacls(lsaf_path=, sas_dsname=work.lsafGetACLs, lsaf_recursive=0);
Gets the access control list for items in the repository. The access control list is stored ...
external

LSAF
%lsaf_getowner(lsaf_path=, lsaf_aclType=);
Gets the current owner of an item within the SAS Life Science Analytics Framework ...
external

LSAF
%lsaf_isowner(lsaf_path=, lsaf_acltype=, lsaf_userid=);
Indicates whether the specified user is the owner of an item in the SAS Life Science ...
external

LSAF
%lsaf_updateacls(sas_dsname=);
Sets the permissions on SAS Life Science Analytics Framework items using a SAS data set as ...
external

LSAF
%lsaf_updateowner(lsaf_path=, lsaf_aclType=, lsaf_userid=);
Updates the current owner of an item in the SAS Life Science Analytics Framework repository.

Macro Detail

%lsaf_getacls(lsaf_path=, sas_dsname=work.lsafGetACLs, lsaf_recursive=0);

[ Exposure: external ]
Gets the access control list for items in the repository. The access control list is stored
in a SAS data set.

For container items, both the default and current access control lists are returned with
the exception of analyses. For non-container items and analyses, only the current access
control lists is returned.

Syntax:
%LSAF_GETACLS(LSAF_PATH=lsaf-path, <SAS_DSNAME=SAS-data-set,
LSAF_RECURSIVE=recursion-level>);

          
History:
   2013-08-30
updates for standardization and coding conventions
   2016-08-26
rebrand as LSAF
   2019-02-05
update to 2.1
   2019-11-01
update to handle a blank SAS output file.
Expected Macro Variables:
_lsafMsg_ - The return message.
_lsafRC_ - The return code.
Parameters:
lsaf_path - - Required - The path of the content item in the SAS Life Science
        Analytics Framework repository. This can be either a file or a container.
sas_dsname - - Optional - The name of the output SAS data set that contains the metadata
        for the access control lists that are specified as libref.dataset. The default
        value is WORK.LSAFGETACL. The data set contains a row for each access control
        entry, sorted by path and aclType, and columns with the following names:
        - name: The name of the item.
        - path: The path to the item.
        - itemType: The type of the item (such as folder or data set).
        - isContainer: Indicates whether the item is a container. Valid values:
        (0=no, 1=yes).
        - owner: The user ID of the user who owns the item.
        - aclType: DEFAULT or CURRENT. Analyses and files have only current ACL. All
        other containers have both default and current ACL.
        - aclPrincipalName: If the aclPrincipalType is ACLOWNER, this is the Owner. If
        the aclPrincipalType is ACLMEMBERS, this is Members. If the
        aclPrincipalType is USER, this is the user ID of the user. If the
        aclPrincipalType is GROUP, this is the name of the group.
        - aclPrincipalType: Specifies whether the principal is a ACLOWNER, ACLMEMBERS,
        USER or GROUP.
        - grpSrcCtxt: For group principals, specifies the context path where the group
        is defined.
        - adminPermission: Permission to administer the item.
        - readPermission: Permission to read the item.
        - writePropPerm: Permission to update the item properties.
        - writeContentPerm: Permission to update the item content.
        - deletePermission: Permission to delete the item.
        Permission values:
        1: Allowed.
        -1: Denied.
        0: Not specified (Inherited).
lsaf_recursive - - Conditional - The level of recursion when the path is a container.
        Valid values:
        0 (Default): Returns ACLs for the input container only.
        1: Returns ACLs for the container and all items within the container, but not
        sub containers.
        2: Returns ACLs for the container, all items within the container, and one
        level of sub containers.
        99: Returns ACLs for the container and all of the sub containers and items
        (traverses the entire tree).
        For files, the value is ignored.
File: lsaf_getacls.sas
First available in version: 1.2

%lsaf_getowner(lsaf_path=, lsaf_aclType=);

[ Exposure: external ]
Gets the current owner of an item within the SAS Life Science Analytics Framework
repository.

The value of the macro variable _lsafOwner_ is the owner user ID. The value of _lsafOwner_
is the <creator> for the default permissions on a container that has no specific user who is
designated as the owner.

Syntax for files:
%LSAF_GETOWNER(LSAF_PATH =lsaf-path);

Syntax For containers:
%LSAF_GETOWNER(LSAF_PATH =lsaf-path, LSAF_ACLTYPE =lsaf-acl-type);

          
History:
   2013-08-30
updates for standardization and coding conventions
   2016-08-26
rebrand as LSAF
   2019-02-05
update to 2.1
Expected Macro Variables:
_lsafMsg_ - The return message.
_lsafOwner_ - The current owner of the item.
_lsafRC_ - The return code.
Parameters:
lsaf_path - - Required - The path of the item in the SAS Life Science Analytics
        Framework repository.
lsaf_aclType - - Conditional - The type of permissions to return. Valid values (case-
        insensitive):
        - DEFAULT
        - CURRENT
        Files have only current permissions. Therefore, a value is not required when
        lsaf_path is a file. However, if a value other than CURRENT or blank is specified
        for a file, the operation fails.
        For container items, the value must be specified.
File: lsaf_getowner.sas
First available in version: 1.2

%lsaf_isowner(lsaf_path=, lsaf_acltype=, lsaf_userid=);

[ Exposure: external ]
Indicates whether the specified user is the owner of an item in the SAS Life Science
Analytics Framework repository.

The SAS macro variable _lsafIsOwner_ is set to a value of 1, if the specified user value is
the valid owner of the item, 0 if it is not. In the event of an incorrect call to the macro
that results in an error, the return value of _lsafIsOwner_ is set to -1.

Syntax:
%LSAF_ISOWNER(LSAF_PATH=lsaf-path, LSAF_ACLTYPE=lsaf-acl-type, LSAF_USERID=lsaf-userid);

          
History:
   2019-02-05
initial coding
Expected Macro Variables:
_lsafIsOwner_ - Indicates whether the user is the owner of the item.
_lsafMsg_ - The return message.
_lsafRC_ - The return code.
Parameters:
lsaf_path - - Required - The path of the item in the SAS Life Science Analytics
        Framework repository.
lsaf_acltype - - Conditional - The type of permissions. Valid values (case-insensitive):
        - DEFAULT
        - CURRENT
        Files have only current permissions. Therefore, a value is not required when
        lsaf_path is a file. However, if a value other than CURRENT or blank is specified
        for a file, the operation fails.
        For container items, the value must be specified.
        the user ID, including the brackets.
lsaf_userid - Parameter description not provided
File: lsaf_isowner.sas
First available in version: 2.5

%lsaf_updateacls(sas_dsname=);

[ Exposure: external ]
Sets the permissions on SAS Life Science Analytics Framework items using a SAS data set as
input.

The permission lists (known as Access Control Lists or ACLs) for multiple items can be modified
using a single data set. Access permissions are applied only to items in the repository
within an organization.

There are two types of access permission lists: current and default.

The current access permissions are applied to an individual item. The default access
permissions apply only to container items (such as folders and projects) and define the
permissions that are inherited by any new items that are added to the container.

In the context of this macro, the access permission type is referred to as aclType. All records
in the input data set that pertain to the same repository item and aclType are processed
together as a single ACL.

A set of permissions for a specific repository item for an individual principal within an
access permission type is referred to as an Access Control Entry (ACE). An ACE is
represented as a single row in the input data set.

An ACE is defined by the following characteristics:
path: The full path of the repository item (file or container).
ACL type: The access permission type (DEFAULT or CURRENT).
ACL principal type: The type of the principal. The principal type can be Owner, Members,
User, or Group.
ACL principal name: The name of the user or group.
set of permissions: The specific permissions to assign (such as Administration, Read,
Properties Write, Content Write, or Delete).

The output data set from the lsaf_getacls macro contains all of the necessary variables
and data needed as the input data set for the lsaf_updateACLs macro. Modify the data set with
any changes before calling lsaf_updateacls.

To add a principal with specific access permissions to a repository item, add a new row to the
data set for that principal.

To modify the access permissions for a principal who is associated with a repository item,
edit the appropriate row in the data set.

To remove a principal with specific access permissions from a repository item, delete the
appropriate row from the data set. Note that the Owner and Members access control entries
cannot be removed from the item. Removing them from the data set causes a failure.

To maintain the existing permissions for a principal who is associated with a repository item,
leave the record as it is in the data set. The record must remain, otherwise the access
permissions for this principal are removed.

Failure and Message Handling

The macro performs a series of validation procedures to determine that the input data set has
the necessary structure for processing. If any of these validation procedures fail, an
appropriate failure message is printed to the SAS log file and the macro stops additional
processing.

In addition to other modifications, the macro sorts the input data set and stores the modified
data in a temporary data set called WORK.__SASMACRO_ACLTEMP__. In the event that a failure
occurs during processing, this temporary data set is retained as a reference. If all updates
are performed successfully, this data set is deleted from the work library. A message is
printed to the SAS log file that indicates whether the data set was retained or not. Regardless
of the success or failure of previous runs, this data set is deleted at the beginning of each
new run of the macro. The data values and sort order of the original input data set are
maintained.

All records that pertain to the same repository item and aclType are processed as a single
access control list by the macro. Messages are printed to the SAS log file as each ACL is
processed. If the update of an ACL fails, the macro stops processing.

If a failure occurs while processing a specific access control entry (such as a principal), the
macro stops processing and a failure message is written to the SAS log file. Successful updates
to ACLs made prior to the observation that contains the failure are maintained in SAS Life
Science Analytics Framework. Changes made to access permissions for entries that are part of
the same ACL that contained the observation with the failure are lost. *;

Valid values for permissions are as follows. All values must be of type numeric.
1: ALLOW
-1: DENY
0: Inherited

Syntax:
%LSAF_UPDATEACLS(SAS_DSNAME=SAS-data-set);

Example Code:
Get permissions for a folder:

* start code example;
%lsaf_getacls(lsaf_path=%str(/SAS/Study1/Files/folder1), lsaf_recursive=0);

data UpdateACLS;
set lsafGetACLS end=eof;

output;

if eof then do;
* Adding user permission under DEFAULT;
aclType = "DEFAULT";
aclPrincipalType = "USER";
aclPrincipalName = "user1";
grpSrcCtxt = "";
adminPermission = 0;
readPermission = 1;
writePropPerm = 1;
writeContentPerm = 1;
deletePermission = 1;
output;

* Adding group permission under CURRENT;
aclType = "CURRENT";
aclPrincipalType = "GROUP";
aclPrincipalName = "group1";
grpSrcCtxt = "/SAS";
adminPermission = 0;
readPermission = 1;
writePropPerm = 1;
writeContentPerm = 1;
deletePermission = 1;
output;
end;

run;

%lsaf_updateacls(sas_dsname=UpdateACLS);
* end code example;

Note: User or group Access Control Entries (ACEs) with values of 0 for all permission variables
will result in a validation error that will cause the processing to stop.
Note: Users and groups being added as ACEs must be members in the context containing the item
being updated.

          
History:
   2013-08-30
updates for standardization and coding conventions
   2016-02-09
updates for path sorting, notes to log, stop after first failure.
   2016-08-26
rebrand as LSAF
   2019-02-05
update to 2.1
Expected Macro Variables:
_lsafMsg_ - The return message.
_lsafRC_ - The return code.
Parameters:
sas_dsname - - Required - the name of a SAS data set that contains the permission
        information for all of the items to modify, specified as libref.dataset. The
        data set must contain at least the variables listed below. Any additional
        variables are ignored.
        path: The case-sensitive path of the item, which includes the item name.
        aclType: Indicates the ACL to modify for the item and is case-insensitive. For
        file items, the variable must be present but the value must be CURRENT or
        blank. For container items, the value must be either DEFAULT or CURRENT.
        aclPrincipalType: Indicates the type of ACE to update.
        Values: ACLOWNER | ACLMEMBERS | USER | GROUP (case-insensitive)
        Default: None
        aclPrincipalName: The name of the principal ACE to update or add.
        For aclPrincipalType ACLOWNER, this must have the value OWNER.
        For aclPrincipalType ACLMEMBERS, this must have the value MEMBERS.
        For aclPrincipalType USER, this must be a valid userid (case-sensitive).
        For aclPrincipalType GROUP, this must be a valid group name (case-sensitive).
        grpSrcCtxt: The case-sensitive path of the context in which the group is defined, if
        aclPrincipalType is GROUP. For aclPrincipalType GROUP, this value is required,
        otherwise the variable must be present but the value is ignored.
        adminPermission: The permission to administer the item.
        readPermission: The permission to view the item.
        writePropPerm: The permission to update the properties of the item.
        writeContentPerm: The permission to write to the content of the item.
        deletePermission: The permission to the delete the item.
File: lsaf_updateacls.sas
First available in version: 1.2

%lsaf_updateowner(lsaf_path=, lsaf_aclType=, lsaf_userid=);

[ Exposure: external ]
Updates the current owner of an item in the SAS Life Science Analytics Framework repository.

Syntax for files:
%LSAF_UPDATEOWNER(LSAF_PATH=lsaf-path, LSAF_USERID=lsaf-userid);

Syntax for containers:
%LSAF_UPDATEOWNER(LSAF_PATH=lsaf-path, LSAF_USERID=lsaf-userid, LSAF_ACLTYPE=lsaf-acl-type);

          
History:
   2013-08-30
updates for standardization and coding conventions
   2016-08-26
rebrand as LSAF
   2019-02-05
update to 2.1
Expected Macro Variables:
_lsafMsg_ - The return message.
_lsafRC_ - The return code.
Parameters:
lsaf_path - - Required - The path of the item in the SAS Life Science Analytics
        Framework repository.
lsaf_aclType - - Conditional - The type of permission owner to set. The valid values
        are DEFAULT and CURRENT (case-insensitive). Files have only CURRENT permissions.
        Therefore, a value is not required when lsaf_path is a file. However, if a value
        other than CURRENT or blank is entered for a file, the operation fails.
        For container items, the value must be specified.
lsaf_userid - - Required - The user ID for the account to be the new owner. To set the
        owner for the DEFAULT permissions to be the creator of the item, specify the value
        <creator> as the value for lsaf-userid.
File: lsaf_updateowner.sas
First available in version: 1.2