Using Role and Permission List Aliases
This topic discusses how to:
Identify hard-coded roles and permission lists.
Enable role and permission list alias options.
Define role aliases.
Define permission list aliases.
Run role and permission list alias queries.
IsUserInRole and IsUserInPermissionList PeopleCode functions are used by PeopleSott developers to control discrete functionality or access that is not controlled by normal role and permission list settings. These PeopleCode functions use hard-coded references to PeopleSoft roles and permissions lists and therefore make it hard for customers to adopt their own roles and permission lists when they want to use their own naming conventions. If they adopt a new name for a PeopleSoft-delivered role or permission list and there are any IsUserInRole and IsUserInPermissionList PeopleCode references to roles and permissions, the customer may want to find and modify all those PeopleCode references.
As a workaround, security administrators can create aliases for hard-coded roles and permission lists. At runtime, IsUserInRole or IsUserInPermissionList PeopleCode runs against the aliases and returns a value of TRUE.
Key points about role and permission list aliases:
Role and permission list aliases are not given the security access of the role or permission list on which they are defined. Only the name reference uses the alias.
System variable %Role will not contain any roles that are only associated via an alias. Likewise, system variable %PermissionLists will not contain any permission lists that are only associated via an alias.
Aliases defined for roles and permission lists are not included with the original object when copying Application Designer projects using Project Copy.
Example: Role Alias
Role alias example:
Role A is assigned to User A.
There is functionality controlled by IsUserInRole(“Role B").
This will return FALSE for User A.
If Role B is set as an alias for Role A, IsUserInRole(“Role B”) will return TRUE for User A, even though Role B is not actually assigned to User A.
The IsUserInRole built-in function takes an arbitrary-length list of strings representing the names of roles and determine whether the current user belongs to any role in an array of roles. The syntax is as follows:
IsUserInRole(rolename1 [, rolename2]. . .)In this example before the alias assignment, only Role A is included in the array, as follows:
IsUserInRole (Role A)When Role B is defined as an alias of Role A, Role B is included in the array of roles:
IsUserInRole (Role A, Role B)Example: Permission List Alias
Permission list alias example:
Permission List A is assigned to User A (via a role).
There is functionality controlled by IsUserInPermissionList (“Permission List B”)
This will return FALSE for User A.
If Permission List B is set as an alias for Permission List A, IsUserInPermissionList("Permission List B") will return TRUE for User A, even though Permission List B is not actually assigned to User A (via a role).
The IsUserInPermissionList built-in function takes an arbitrary-length list of strings representing the names of permission lists and determines and determine whether the current user belongs to any of the permission lists. The syntax is as follows:
IsUserInPermissionList(PermissionList1 [, PermissionList2]. . .)In this example before the alias assignment, only Permission List A is included in the array list, as follows:
IsUserInPermissionList(PermissionList A)When Permission List B is defined as an alias of Permission List A, Permission List B is included in the array:
IsUserInPermissionList(PermissionList A, PermissionList B)To identify hard-coded roles and permission lists, use either of these options to scan for instances of IsUserInRole or IsUserInPermissionList:
PeopleCode trace.
Use the Show Each option on the Trace PeopleCode page. To access the page select in PIA select
Note that the trace can considerably slow system performance and it should not be performed in a production environment.
Change Impact Analyzer.
Change Impact Analyzer allows you to search for references in the application that match a string that you specify. Once you connect to a database you can use the Find In page to find references in PeopleCode, SQL, and HTML objects. You select your scope (Search Criteria) and add one or more strings for which you want to find references in the Find What text box. For each string you specify you click on Add to List button. Once you have completed building you list of strings, you select the Run Find In button to execute the search.
To access the Find In page, in Change Impact Analyzer select
This table describes the pages used to define and manage role and permission list aliases.
|
Page |
Object ID |
Description |
Navigation |
|---|---|---|---|
|
Alias Options |
PTSECALIASOPTIONS |
Use this page to enable role and permission list alias functionality. You must enable the Role Alias option for the Role Aliases page to appear in the Roles component. Likewise, you must enable the Permission List Alias option for the Permission List Alias page to appear in the Permission List component. Important! You must reboot the application server for changes you make on the page to take effect. |
PeopleTools, Security, Security Objects, Alias Options.
|
|
Role Aliases |
PTROLENAMEALIAS |
Use this page to define aliases for a role. |
|
|
Permission Aliases |
PTCLASSIDALIAS |
Use this page to define aliases for a permission list. |
|
|
Role Security Queries |
MAINT_SEC_ROLE_QRY |
Use this page to run a query that returns a list of all role aliases defined in the database. |
|
|
Permission List Report Queries |
MAINT_SEC_PLIST_QR |
Use this page to run a query that returns a list of all permission list aliases defined in the database. |
|
For the pages used to define role and permission list aliases to appear, the Roles - Role Aliases and Permission Lists - Permission List Aliases pages respectively, you must enable the alias options on the Alias Options page (PTSECALIASOPTIONS).
To access the Alias Options page, select
Image: Alias Options page
This example illustrates the fields and controls on the Alias Options page. You can find definitions for the fields and controls later on this page.
Important! You must reboot the application server for changes you make on the page to take effect.
|
Field or Control |
Definition |
|---|---|
| Role Alias |
Select this option to enable the alias functionality for roles. When you enable this option the Roles - Role Aliases page appears in the Roles component. |
| Permission List Alias |
Select this option to enable the alias functionality for permission lists. When you enable this option the Permissions List - Permission Aliases page appears in the Permissions List component. |
Use the Roles - Role Aliases page to define role aliases. To access the page select
For the page to be accessible, you must enable the Role Alias option on the Alias Options page as described earlier in this topic.
To assign a role alias it must be an existing role in the database.
Image: Roles – Role Aliases page
This example illustrates the fields and controls on the Roles – Role Aliases page. You can find definitions for the fields and controls later on this page.
To assign a role alias to a role, in the Role Aliases grid, enter or search for a role to add.
Click the Add Row button to add additional aliases.
The system does not assign role aliases any permissions or access of the base role on which you define it. (In the previous example, Integration Administrator is the base role.) Role aliases are only used in conjunction with the IsUserInRole built-in function. When IsUserInRole PeopleCode runs, the system will include the base role and any role aliases you define in the Role Aliases grid in the string array and return a value of TRUE.
Use the Permission Lists - Permission List Aliases page to define permission list aliases. To access the page select
For the page to be accessible, you must enable the Permission List Alias option on the Alias Options page as described earlier in this topic.
To assign a permission list alias it must be an existing permission list in the database.
Image: Permission Lists – Permission List Aliases page
This example illustrates the fields and controls on the Permission Lists – Permission List Aliases page. You can find definitions for the fields and controls later on this page.
To assign a permission list alias to a permission list, in the Permission List Aliases grid, enter or search for a permission list to add.
Click the Add Row button to add additional aliases.
The system does not assign permission list aliases any permissions or access of the base permission list on which you define it. (In the previous example, PeopleSoft User is the base permission list.) Permission list aliases are only used in conjunction with the IsUserInPermissionList built-in function. When IsUserInPermissionList PeopleCode runs, the system includes the base permission list and any aliases you define in the Permission List Aliases grid in the string array and return a value of TRUE.
PeopleSoft provides queries that generate reports of the role and permission list aliases defined in the database:
Running the Role Alias Query
Use the Role Security Queries page (MAINT_SEC_ROLE_QRY) to run a query on role aliases defined in the database. To access the page select
Image: Common Queries – Role Security Queries page
This example illustrates the Common Queries - Role Security Queries page the Role Security Queries delivered with PeopleTools.
To view the role aliases defined in the database, click the All Role Aliaseslink. The system runs the delivered PT_SEC_ROLE_ALIASES query, generates a report of all defined role aliases in the database, and displays the results in a new browser window.
Running the Permission List Alias Query
Use the Permission List Report Queries page (MAINT_SEC_PLIST_QR) to run a query on permission list aliases defined in the database. To access the page select
Image: Permission List Report Queries page
This example illustrates the Common Queries - Permission List Report Queries page and the permission list reports and queries delivered with PeopleTools.
To view the permission list aliases defined in the database, click the All Permission List Aliases link. The system runs the delivered PT_SEC_PLIST_ALIASES query, generates a report of all defined permission list aliases in the database, and displays the results in a new browser window.