Module RoleService

Macros to manipulate and create roles, their availability in contexts, and their membership lists.

Since: 2.1

Macro Summary
external

LSAF
%lsaf_addinheritedrole(lsaf_path=, lsaf_role=, lsaf_role_context=);
Assigns a role to the specified context as an inherited role.
external

LSAF
%lsaf_addrolemember(lsaf_path=, lsaf_role=, lsaf_role_context=, lsaf_member=, lsaf_type=USER, lsaf_group_context=);
Adds a user account or user group as a member of a role in the specified context.
external

LSAF
%lsaf_addroleprivilege(lsaf_path=, lsaf_role=, lsaf_privilege=);
Adds a privilege to a role in the specified context.
external

LSAF
%lsaf_createrole(lsaf_path=, lsaf_role=, lsaf_description=);
Creates a role in the specified context.
external

LSAF
%lsaf_deleterole(lsaf_path=, lsaf_role=);
Deletes a role from the specified context.
external

LSAF
%lsaf_getrolemembers(lsaf_path=, lsaf_role=, lsaf_role_context=, sas_dsname=work.lsafGetRoleMembers);
Gets the metadata for all of the members that are assigned to a role within the specified ...
external

LSAF
%lsaf_getroleprivileges(lsaf_path=, lsaf_role=, sas_dsname=work.lsafGetRolePrivileges);
Gets the metadata for all of the privileges that are assigned to a role. The metadata is ...
external

LSAF
%lsaf_getroles(lsaf_path=, sas_dsname=work.lsafGetRoles);
Gets the metadata for all of the roles that are defined and inherited in a context. The ...
external

LSAF
%lsaf_hasscopedprivilege(lsaf_path=, lsaf_privilege=, lsaf_member=, lsaf_type=USER, lsaf_group_context=);
Indicates whether a user or group has a specific role privilege in the specified context.
external

LSAF
%lsaf_isrolemember(lsaf_path=, lsaf_role=, lsaf_role_context=, lsaf_member=, lsaf_type=USER, lsaf_group_context=);
Indicates whether a user account or user group is a member of a role in the specified context.
external

LSAF
%lsaf_isroleprivilege(lsaf_path=, lsaf_role=, lsaf_privilege=);
Indicates whether a privilege is assigned to a role in the specified context. Applies only ...
external

LSAF
%lsaf_removeinheritedrole(lsaf_path=, lsaf_role=, lsaf_role_context=);
Removes a role from the specified context.
external

LSAF
%lsaf_removerolemember(lsaf_path=, lsaf_role=, lsaf_role_context=, lsaf_member=, lsaf_type=USER, lsaf_group_context=);
Removes a user account or a user group as a member of a role in the specified context.
external

LSAF
%lsaf_removeroleprivilege(lsaf_path=, lsaf_role=, lsaf_privilege=);
Removes a privilege from a role in the specified context.
external

LSAF
%lsaf_roleexists(lsaf_path=, lsaf_role=, lsaf_role_context=);
Indicates whether a role exists as defined or inherited in a specified context.

Macro Detail

%lsaf_addinheritedrole(lsaf_path=, lsaf_role=, lsaf_role_context=);

[ Exposure: external ]
Assigns a role to the specified context as an inherited role.

Syntax:
%LSAF_ADDINHERITEDROLE(LSAF_PATH=lsaf-path, LSAF_ROLE=lsaf-role-name,
LSAF_ROLE_CONTEXT=lsaf-role-context);

          
History:
   2013-08-30
updates for standardization and coding conventions
   2016-08-26
rebrand as LSAF
   2019-01-29
update to 2.1
   2019-02-14
renamed from lsaf_assignrole
Expected Macro Variables:
_lsafMsg_ - The return message.
_lsafRC_ - The return code.
Parameters:
lsaf_path - - Required - The path of the context.
lsaf_role - - Required - The name of the role.
lsaf_role_context - - Required - The context in which the role is defined, specified as
        a path (such as /SAS).
File: lsaf_addinheritedrole.sas
First available in version: 1.2

%lsaf_addrolemember(lsaf_path=, lsaf_role=, lsaf_role_context=, lsaf_member=, lsaf_type=USER, lsaf_group_context=);

[ Exposure: external ]
Adds a user account or user group as a member of a role in the specified context.

Syntax:
%LSAF_ADDROLEMEMBER(LSAF_PATH=lsaf-path, LSAF_ROLE=lsaf-role-name,
LSAF_ROLE_CONTEXT=lsaf-role-context, LSAF_MEMBER=lsaf-member-identifier
<, LSAF_TYPE=lsaf-member-type, LSAF_GROUP_CONTEXT=lsaf-group-context>);

Example Code
Context paths used in examples:
- Organization: /SAS
- Project: /SAS/Project1
- Analysis: /SAS/Project1/Analysis1

1. Add a user account to a role that is defined in a project:
%lsaf_addrolemember(lsaf_path=%str(/SAS/Project1), lsaf_role=%str(PrjRole1),
lsaf_role_context=%str(/SAS/Project1),lsaf_member=%str(User1), lsaf_type=%str(USER));

2. Add a user group that is defined in an organization to a role that is defined in a project:
%lsaf_addrolemember(lsaf_path=%str(/SAS/Project1), lsaf_role=%str(PrjRole1),
lsaf_role_context=%str(/SAS/Project1),lsaf_member=%str(OrgGrp1), lsaf_type=%str(GROUP),
lsaf_group_context=%str(/SAS));

3. Add a user account to a role that is assigned in a project:
%lsaf_addrolemember(lsaf_path=%str(/SAS/Project1), lsaf_role=%str(OrgRole1),
lsaf_role_context=%str(/SAS),lsaf_member=%str(User1), lsaf_type=%str(USER));

4. Add a user group that is defined in an organization to a role that is assigned in a project:
%lsaf_addrolemember(lsaf_path=%str(/SAS/Project1), lsaf_role=%str(OrgRole1),
lsaf_role_context=%str(/SAS),lsaf_member=%str(OrgGrp1), lsaf_type=%str(GROUP),
lsaf_group_context=%str(/SAS));

          
History:
   2013-08-30
updates for standardization and coding conventions
   2016-08-26
rebrand as LSAF
   2019-01-29
update to 2.1
Expected Macro Variables:
_lsafMsg_ - The return message.
_lsafRC_ - The return code.
Parameters:
lsaf_path - - Required - The path of the context item in which the role is assigned.
lsaf_role - - Required - The name of the role.
lsaf_role_context - - Optional - The context in which the role is defined, specified as a
        path (such as /SAS). If not provided, the member is added to the role that is
        defined at the path.
lsaf_member - - Required - The identifier of the user account or the name of the user
        group to add.
lsaf_type - - Conditional - The type of member to add. Valid values (case-insensitive):
        USER (Default) and GROUP.
lsaf_group_context - - conditional - The context in which the group is defined, specified
        as a path (such as /SAS). This parameter is required, if LSAF_TYPE=GROUP.
        Otherwise, it is ignored.
File: lsaf_addrolemember.sas
First available in version: 1.2

%lsaf_addroleprivilege(lsaf_path=, lsaf_role=, lsaf_privilege=);

[ Exposure: external ]
Adds a privilege to a role in the specified context.

Syntax:
%LSAF_ADDROLEPRIVILEGE(LSAF_PATH=lsaf-path, LSAF_ROLE=lsaf-role-name,
LSAF_PRIVILEGE=lsaf-privilege-id);

Example Code:
Use %lsaf_getscopedprivileges to fetch the list of privileges that are available at the .
context level. The macro returns a SAS data set that contains the list of the privileges.
The default name of the data set is work.lsafgetscopedprivileges). Use one of the privilegeId
values to add that privilege to a role.

1. Retrieve the available privileges in a project:
%lsaf_getscopedprivileges(lsaf_path=%str(/SAS/Project1));

2. Add a privilege to a role:
%lsaf_addroleprivilege(lsaf_path=%str(/SAS/Project1), lsaf_role=%str(PrjRole1),
lsaf_privilege=%str(PRIVILEGE_SIGN_FILE));

          
History:
   2013-08-30
updates for standardization and coding conventions
   2016-08-26
rebrand as LSAF
   2019-01-29
update to 2.1
Expected Macro Variables:
_lsafMsg_ - The return message.
_lsafRC_ - The return code.
Parameters:
lsaf_path - - Required - The path of the context in which the role is defined.
lsaf_role - - Required - The name of the role.
lsaf_privilege - - Required - The identifier of the privilege.
File: lsaf_addroleprivilege.sas
First available in version: 1.2

%lsaf_createrole(lsaf_path=, lsaf_role=, lsaf_description=);

[ Exposure: external ]
Creates a role in the specified context.

Syntax:
%LSAF_CREATEROLE(LSAF_PATH=lsaf-path, LSAF_ROLE=lsaf-role-name
<, LSAF_DESCRIPTION=lsaf-description>);

          
History:
   2013-08-30
updates for standardization and coding conventions
   2016-08-26
rebrand as LSAF
   2019-01-25
updates for LSAF 5.1 functionality.
   2019-01-29
update to 2.1
Expected Macro Variables:
_lsafMsg_ - The return message.
_lsafRC_ - The return code.
Parameters:
lsaf_path - - Required - The path of the context in which to create the role.
lsaf_role - - Required - The name of the role.
lsaf_description - - Optional - The description of the role.
File: lsaf_createrole.sas
First available in version: 1.2

%lsaf_deleterole(lsaf_path=, lsaf_role=);

[ Exposure: external ]
Deletes a role from the specified context.

Syntax:
%LSAF_DELETEROLE(LSAF_PATH=lsaf-path, LSAF_ROLE=lsaf-role-name);

          
History:
   2013-08-30
updates for standardization and coding conventions
   2016-08-26
rebrand as LSAF
   2019-01-25
updates for LSAF 5.1 functionality.
   2019-01-29
update to 2.1
Expected Macro Variables:
_lsafMsg_ - The return message.
_lsafRC_ - The return code.
Parameters:
lsaf_path - - Required - The path of the context in which the role is defined.
lsaf_role - - Required - The name of the role.
File: lsaf_deleterole.sas
First available in version: 1.2

%lsaf_getrolemembers(lsaf_path=, lsaf_role=, lsaf_role_context=, sas_dsname=work.lsafGetRoleMembers);

[ Exposure: external ]
Gets the metadata for all of the members that are assigned to a role within the specified
context. The metadata is stored in a SAS data set.

Syntax:
%LSAF_GETROLEMEMBERS(LSAF_PATH=lsaf-path, LSAF_ROLE=lsaf-role-name,
LSAF_ROLE_CONTEXT=lsaf-role-context, <, SAS_DSNAME=SAS-data-set>);

          
History:
   2013-08-30
updates for standardization and coding conventions
   2016-08-26
rebrand as LSAF
   2019-01-29
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 context where the role is assigned.
lsaf_role - - Required - The name of the role.
lsaf_role_context - - Optional - The context in which the role is defined, specified as a
        path (such as /SAS). If not provided, the members returned are from the role taht is
        defined at the path.
sas_dsname - - Optional - The name of the output SAS data set to contain the metadata
        for the members, specified as libref.dataset. The default value is
        WORK.LSAFGETROLEMEMBERS. The data set contains a row for each member in the role and
        columns with the following names. The data set is sorted by member type and
        principalId.
        - contextPath: The path of the context.
        - type: The member type. Valid values: user and group.
        - principalId: The name of the member. Valid values: group name and user ID.
        - descriptor: The description of the member. Valid values: group name and user
        display name.
        - grpSrcCtxt: The context in which the group member is defined, if the member is
        a group.
File: lsaf_getrolemembers.sas
First available in version: 1.2

%lsaf_getroleprivileges(lsaf_path=, lsaf_role=, sas_dsname=work.lsafGetRolePrivileges);

[ Exposure: external ]
Gets the metadata for all of the privileges that are assigned to a role. The metadata is
stored in a SAS data set.

Syntax:
%LSAF_GETROLEPRIVILEGES(LSAF_PATH=lsaf-path, LSAF_ROLE=lsaf-role-name
<, SAS_DSNAME=SAS-data-set>);

          
History:
   2013-08-30
updates for standardization and coding conventions
   2016-08-26
rebrand as LSAF
   2019-01-29
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 context in which the role is defined.
lsaf_role - - Required - The name of the role.
sas_dsname - - Optional - The name of the output SAS data set to the metadata for the
        the privileges, specified as libref.dataset. The default value is
        WORK.LSAFGETROLEPRIVILEGES. The data set contains a row for each privilege in the
        role and columns with the following names. The data is sorted by the
        privilegeId.
        - contextPath: The path of the context in which the role is defined.
        - roleName: The name of the role.
        - privilegeId: The identifier of the privilege.
        - privilegeName: The name of the privilege.
File: lsaf_getroleprivileges.sas
First available in version: 1.2

%lsaf_getroles(lsaf_path=, sas_dsname=work.lsafGetRoles);

[ Exposure: external ]
Gets the metadata for all of the roles that are defined and inherited in a context. The
metadata is stored in a SAS data set.

Syntax:
%LSAF_GETROLES(LSAF_PATH=lsaf-path <,SAS_DSNAME=SAS-data-set>);

          
History:
   2013-08-30
updates for standardization and coding conventions
   2016-08-26
rebrand as LSAF
   2019-01-25
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 context in which the roles are located.
sas_dsname - - Optional - The name of the output SAS data set to contain the metadata
        for the roles, specified as libref.dataset. The default value is
        WORK.LSAFGETROLES. The data set contains a row for each role in the context
        and columns with the following names. The data set is sorted by the role name.
        - path: The path of the context.
        - name: The name of the role.
        - description: The role description.
        - roleSrcCtxt: The context in which the of role is defined.
        - isInherited: Indicates whether the role is inherited. Valid values: 0 and 1.
File: lsaf_getroles.sas
First available in version: 1.2

%lsaf_hasscopedprivilege(lsaf_path=, lsaf_privilege=, lsaf_member=, lsaf_type=USER, lsaf_group_context=);

[ Exposure: external ]
Indicates whether a user or group has a specific role privilege in the specified context.

The SAS macro variable _lsafHasScopedPrivilege_ is set to a value of 1, when the specified
user or group has the privilege, 0 if it does not. In the event of an incorrect call to the
macro that results in an error, the return value of _lsafHasScopedPrivilege_ is set to -1.

Syntax:
%LSAF_HASSCOPEDPRIVILEGE(LSAF_PATH=lsaf-path, LSAF_PRIVILEGE=lsaf-privilege-id,
LSAF_MEMBER=lsaf-member-identifier <, LSAF_TYPE=lsaf-type,
LSAF_GROUP_CONTEXT=lsaf-group-context>);

          
History:
   2016-08-19
original code
@updated 2019-01-29 updated and rebranded to 2.1
@updated 2019-02-14 renamed from lsaf_hascontextprivilege
Expected Macro Variables:
_lsafHasScopedPrivilege_ - Indicates whether the user or group has the privilege in the
        specified context.
_lsafMsg_ - The return message.
_lsafRC_ - The return code.
Parameters:
lsaf_path - - Required - The path of the context.
lsaf_privilege - - Required - The identifier of the privilege.
lsaf_member - - Required - The user ID or group name of the member.
lsaf_type - - Conditional - The type of member. Valid values (case-insensitive):
        - USER (Default).
        - GROUP.
lsaf_group_context - - Conditional - The context in which the member group is defined,
        specified as a path (such as /SAS). The parameter is required, if LSAF_TYPE=GROUP.
        Otherwise, it is ignored.
File: lsaf_hasscopedprivilege.sas
First available in version: 1.5

%lsaf_isrolemember(lsaf_path=, lsaf_role=, lsaf_role_context=, lsaf_member=, lsaf_type=USER, lsaf_group_context=);

[ Exposure: external ]
Indicates whether a user account or user group is a member of a role in the specified context.

The SAS macro variable _lsafIsRoleMember_ is set to a value of 1, if the user account or user
group is a member of the role, 0, if it is not. In the event of an incorrect call to the macro
that results in an error, the return value of _lsafIsRoleMember_ is set to -1.

Syntax:
%LSAF_ISROLEMEMBER(LSAF_PATH=lsaf-path, LSAF_ROLE=lsaf-role-name,
LSAF_ROLE_CONTEXT=lsaf-role-context, LSAF_MEMBER=lsaf-member-identifier <, LSAF_TYPE=lsaf-type,
LSAF_GROUP_CONTEXT=lsaf-group-context>);

          
History:
   2013-08-30
updates for standardization and coding conventions
   2016-08-26
rebrand as LSAF
   2019-01-30
update to 2.1
Expected Macro Variables:
_lsafIsRoleMember_ - Indicates whether the user account or user group is a member of the
        role in the specified context.
_lsafMsg_ - The return message.
_lsafRC_ - The return code.
Parameters:
lsaf_path - - Required - The path of the context.
lsaf_role - - Required - The name of the role.
lsaf_role_context - - Optional - The context in which the role is defined, specified as a
        path (such as /SAS). If not provided, the membership is tested in the role that is
        defined at the path.
lsaf_member - - Required - The user identifier or user group name of the member.
lsaf_type - - Conditional - The type of the member. Valid values (case-insensitive):
        USER (Default) and GROUP.
lsaf_group_context - - Conditional - The context in which the member group is defined,
        specified as a path (such as /SAS). If LSAF_TYPE=GROUP, the parameter is required.
        Otherwise, it is ignored.
File: lsaf_isrolemember.sas
First available in version: 1.2

%lsaf_isroleprivilege(lsaf_path=, lsaf_role=, lsaf_privilege=);

[ Exposure: external ]
Indicates whether a privilege is assigned to a role in the specified context. Applies only
for a defined role, not an inherited role, in the specified context.

The SAS macro variable _lsafIsRolePrivilege_ is set to a value of 1 when the role has the
privilege, 0 if it is not. In the event of an incorrect call to the macro that results in an
error, the return value of _lsafIsRolePrivilege_ is set to -1.

Syntax:
%LSAF_ISROLEPRIVILEGE(LSAF_PATH=lsaf-path, LSAF_ROLE=lsaf-role-name,
LSAF_PRIVILEGE=lsaf-privilege-id);

          
History:
   2013-08-30
updates for standardization and coding conventions
   2016-08-26
rebrand as LSAF
   2019-01-30
update to 2.1
Expected Macro Variables:
_lsafIsRolePrivilege_ - Indicates whether the privilege is assigned to the role in the
        specified context.
_lsafMsg_ - The return message.
_lsafRC_ - The return code.
Parameters:
lsaf_path - - Required - The path of the context in which the role is assigned.
lsaf_role - - Required - The name of the role.
lsaf_privilege - - Required - The identifier of the privilege.
File: lsaf_isroleprivilege.sas
First available in version: 1.2

%lsaf_removeinheritedrole(lsaf_path=, lsaf_role=, lsaf_role_context=);

[ Exposure: external ]
Removes a role from the specified context.

Syntax:
%LSAF_REMOVEINHERITEDROLE(LSAF_PATH=lsaf-path, LSAF_ROLE=lsaf-role-name,
LSAF_ROLE_CONTEXT=lsaf-role-context);

          
History:
   2013-08-30
updates for standardization and coding conventions
   2016-08-26
rebrand as LSAF
   2019-01-30
update to 2.1
   3019-02-14
rename from lsaf_unassignrole
Expected Macro Variables:
_lsafMsg_ - The return message.
_lsafRC_ - The return code.
Parameters:
lsaf_path - - Required - The path of the context from which to remove the role.
lsaf_role - - Required - The name of the role.
lsaf_role_context - - Required - The context in which the role is defined, sepcified as
        a path (such as /SAS).
File: lsaf_removeinheritedrole.sas
First available in version: 1.2

%lsaf_removerolemember(lsaf_path=, lsaf_role=, lsaf_role_context=, lsaf_member=, lsaf_type=USER, lsaf_group_context=);

[ Exposure: external ]
Removes a user account or a user group as a member of a role in the specified context.

Syntax:
%LSAF_REMOVEROLEMEMBER(LSAF_PATH=lsaf-path, LSAF_ROLE=lsaf-role-name,
LSAF_ROLE_CONTEXT=lsaf-role-context, LSAF_MEMBER=lsaf-member-identifier <, LSAF_TYPE=lsaf-type,
LSAF_GROUP_CONTEXT=lsaf-group-context>);

          
History:
   2013-08-30
updates for standardization and coding conventions
   2016-08-29
rebrand as LSAF
   2019-01-30
update to 2.1
Expected Macro Variables:
_lsafMsg_ - The return message.
_lsafRC_ - The return code.
Parameters:
lsaf_path - - Required - The path of the context that contains the role.
lsaf_role - - Required - The name of the role.
lsaf_role_context - - Optional - The context in which the role is defined, specified as a
        path (such as /SAS). If not provided, the member is removed from the role that is
        defined at the path.
lsaf_member - - Required - The identifier of the user account or the name of the user group.
lsaf_type - - Conditional - Type of the member. Valid values (case-insensitive):
        USER (Default) and GROUP.
lsaf_group_context - - Conditional - The context in which the group to remove is defined,
        specified as a path (such as /SAS). If LSAF_TYPE=GROUP, this parameter is required.
        Otherwise, it is ignored.
File: lsaf_removerolemember.sas
First available in version: 1.2

%lsaf_removeroleprivilege(lsaf_path=, lsaf_role=, lsaf_privilege=);

[ Exposure: external ]
Removes a privilege from a role in the specified context.

Syntax:
%LSAF_REMOVEROLEPRIVILEGE(LSAF_PATH=lsaf-path, LSAF_ROLE=lsaf-role-name,
LSAF_PRIVILEGE=lsaf-privilege-id);

          
History:
   2013-08-30
updates for standardization and coding conventions
   2016-08-26
rebrand as LSAF
   2019-01-30
update to 2.1
Expected Macro Variables:
_lsafMsg_ - The return message.
_lsafRC_ - The return code.
Parameters:
lsaf_path - - Required - The path of the context in which the role is defined.
lsaf_role - - Required - The name of the role.
lsaf_privilege - - Required - The identifier of the privilege.
File: lsaf_removeroleprivilege.sas
First available in version: 1.2

%lsaf_roleexists(lsaf_path=, lsaf_role=, lsaf_role_context=);

[ Exposure: external ]
Indicates whether a role exists as defined or inherited in a specified context.

The SAS macro variable _lsafRoleExists_ is set to a value of 1, if the role exists, 0 if it
does not. In the event of an incorrect call to the macro that results in an error, the return
value of _lsafRoleExists_ is set to -1.

Syntax:
%LSAF_ROLEEXISTS (LSAF_PATH=lsaf-path, LSAF_ROLE=lsaf-role-name,
LSAF_ROLE_CONTEXT=lsaf-role-context);

          
History:
   2013-08-30
updates for standardization and coding conventions
   2016-08-26
rebrand as LSAF
   2019-01-29
update to 2.1
Expected Macro Variables:
_lsafMsg_ - The return message.
_lsafRC_ - The return code.
_lsafRoleExists_ - Indicates the existence of the role.
Parameters:
lsaf_path - - Required - The path of the context.
lsaf_role - - Required - The name of the role.
lsaf_role_context - - Optional - The context in which the role is defined, specified as a
        path (such as /SAS). If not provided or if the value is equal to the path parameter,
        the macro looks for the role to be defined at the path context. Otherwise, the
        macro searches for the role inherited at the path context.
File: lsaf_roleexists.sas
First available in version: 1.2