The fields, groups and sections displayed by APSAdmin, whether a field is read or read/write, the prompts, whether a password is validated and whether a particular user is even accessible to a given administrator, are all defined in the APSAdmin section of the APS Configuration File.
Access to specific users (or directories) by specific administrators can be controlled, in a general way, using the Allowed keyword in the APSAdmin section of the APS Configuration File.
The Allowed keyword identifies whether the current administrator (defined in the Setting Override) can access a particular user (defined by the Value of the setting) at all.
By default, all access to APSAdmin is denied. There must a an applicable instance of the Allowed keyword that specifically grants rights for an administrator to a particular user.
In the APSAdmin section, an additional function is available when specifying the target. This function, Self(), is TRUE if the administrator is the same as the target user. This function can be used, for example, to allow all users specific access to their own records or to allow a Help Desk person access to the entire directory except for himself (by using NOT Self() for the setting).
Once the administrator (or on-line user) has "rights" to the target user, APS will continue to check to see which fields can be read and/or written.
Different types of User Directories impose different naming requirements on the fields in the user record. Some sites impose further naming conventions, particularly for RDBMS-based directories.
For example, the "Full Name" of a user in an LDAP directory, using the IETF standard, is stored in an attribute called cn. For an ODBC database, this might be a column called userFullName.
APS allows sites to remap user field names in the Mappings section of the APS Configuration File. The format for such an entry is:
<logical name>={<restricted expression>}<underlying name>
The <logical name> can be any name without spaces. References to this name in the APSAdmin section of the APS Configuration File will actually reference the <underlying name> (assuming that the <restricted expression> applied).
The <restricted expression> is the same as a standard override expression, except that it cannot reference user-specific details, such as attributes and group membership. It can, however, reference functions like IsLDAP(), IsODBC(), and IsInDirectory().
To present a solution to our most recent example:
FullName={IsLDAP()} cn
FullName={IsODBC()} userFullName
Because of these two lines in the Mappings section, FullName can be referenced in the APSAdmin section regardless of whether the user exists in an LDAP directory or an ODBC directory.
If a line exists for a given <logical name>, if the <underlying name> is blank, the field, for most intents and purposes, does not exist and APSAdmin will ignore any references to it. This can be useful when an attribute exists in one directory, but not in another.
Entries are not required in the Mappings section. If an entry does not exist at all (as opposed to existing with a null <underlying name>), APS will use the <logical name> that it is looking for as the actual name.
Mappings are used throughout APS. For certain operational fields required by APS, if a field is mapped to a null value, APS will use the logical name anyway (probably resulting in an error). However, APSAdmin will still honor null mappings regardless.
This discussion relates not only to column/attribute names, but to group names as well.
Under LDAP, in fact, a site must map group names in order to use them in the APSAdmin section because LDAP group DNs contain equal signs (=).
A user field is "available" to APSAdmin if it appears in the APSAdmin section of the APS Configuration File and explicitly allows access to that attribute, by the current administrator, for the target user. By default, administrators do not have access to any fields (even if Allowed).
Furthermore, read access and write access are separately controlled. An administrator might have read rights, but not write rights, vice versa, both, or neither for a particular field.
The format of a field access specification is:
<right>.<field>={<admin override>} <target override>
The <right> can be READ, WRITE or RW (for read and write).
The <field> refers to the name of the attribute or column and is subject to the mappings described in the previous section.
The <admin override> defines whether this particular setting applies to the current online user (the administrator). If omitted, the setting applies to all users.
The <target override> defines whether this right/field is applicable for the user currently requested (the target user). This value can be supplied as TRUE to indicate that it applies to all target users.
During APSAdmin read operations, only the first reference to a particular <field> applies. The APSAdminRead function returns XML describing the requested (target) user. In this XML, each attribute is identified as Read, Write or Read/Write. When multiple settings apply for the same <field>, only the first <right> is returned to APSAdmin.
However, during APSAdmin write operations, APS checks to see if any write (write or read/write) access is allowed for this administrator and target. If so, the write is allowed.
A user's group membership is "available" to APSAdmin if it appears in the APSAdmin section of the APS Configuration File and explicitly allows access to that group membership, by the current administrator, for the target user. By default, administrators do not have access to any such information (even if Allowed).
Furthermore, read access and write access are separately controlled. An administrator might have read rights, but not write rights, vice versa, both, or neither for a particular group membership.
The format of a field access specification is:
<right>.GROUP.[set the product group or family]={<admin override>} <target override>
The <right> can be READ, WRITE or RW (for read and write).
The [set the product group or family] refers to the name of the group and is subject to the mappings described in the previous section. For LDAP groups, this field must be remapped, since the equal sign ("=") in the DN will confuse the parser.
The <admin override> defines whether this particular setting applies to the current online user (the administrator). If omitted, the setting applies to all users.
The <target override> defines whether this right/field is applicable for the user currently requested (the target user). This value can be supplied as TRUE to indicate that it applies to all target users.
During APSAdmin read operations, only the first reference to a particular [set the product group or family] applies. The APSAdminRead function returns XML describing the requested (target) user. In this XML, each attribute is identified as Read, Write or Read/Write. When multiple settings apply for the same [set the product group or family], only the first <right> is returned to APSAdmin.
However, during APSAdmin write operations, APS checks to see if any write (write or read/write) access is allowed for this administrator and target. If so, the write is allowed.
APSAdmin returns field and group information in the order in which they appear in the APSAdmin section of the APS Configuration File (note that only settings that apply to the current administrator are considered and duplicate references to the same field or group are ignored).
Entries can be grouped together into sections using the Section keyword in the APS Configuration File. All settings after a Section definition will appear in that section until a new Section keyword appears.
APSAdmin will display a section header for grouped values.
Sections can only have an administrator override and a name (not a target override).
Once the first section is started, there is no way to "unsection" attributes.
If, after evaluating all of the settings in the section, a section does not contain any field or group references, the section is suppressed and not displayed.
By default, APSAdmin uses the name of the field, group, or section as its prompt (the text label alongside the data). This is rarely desirable.
The prompt for each field, group, or section can be changed in the APS Configuration File on a line by line basis. This means that the prompt can be different based on the administrator, target and/or context (discussed later).
To set the prompt for an item, at the end of the setting (it must be after the <target override> or section name), place a prompt specification:
Section=UserInfo [PROMPT User Information]
RW.FullName={@HelpDesk} TRUE [PROMPT Name]
The prompt will be passed through the XML along with the actual name. The APSAdmin interface will display the prompt.
APSAdmin does not normally translate prompts, since screens are so dynamic. If you wish a prompt to be translated, specify the prompt as the translation key, prefixed with a pound sign (#). For example:
Section=UserInfo [PROMPT #User Information]
RW.FullName={@HelpDesk} TRUE [PROMPT #Name]
The prompt itself (with the # sign) will be used as the translation key. The default value will be the key without the # sign. In other words, the following entry in APSAdmin.lang would be used in the above example:
key #Name val Full Name
However, if the #Name key were not found, Name would be used as the translation.
If a section has neither a prompt nor a name (e.g. Section=), the APSAdmin interface will display a section header as a horizontal rule (HTML's <HR> tag).
As mentioned previously, each setting that specifies a field or group with its access rights can be overridden by on-line user (Administrator). The same item can be specified more than once, with different expressions for <admin override> and <target override>. The first entry that applies for a combination of administrator and target will be used.
A site can creatively vary content by making adjustments to these override fields. For example, the field smapsExpirePasswordDays is one of the APS attributes that allows the setting of a password expiration period for a specific user. It should not be used directory-wide, but is frequently used for administrator accounts (that do not get used very often) to prevent their passwords from expiring. The following lines from the APSAdmin section of the APS Configuration File demonstrate one use for varying content by user:
READ.smapsExpirePasswordDays=
{@HelpDesk AND NOT @HelpDeskManager}
Not IsNull("smapsExpirePasswordDays")
[PROMPT Expiration]
RW.smapsExpirePasswordDays={@HelpDeskManager}
true [PROMPT Expiration]
In this example, Help Desk personnel (but not Help Desk Managers) will see the value of this attribute if the viewed user has such an override. If the target user does not have an override, no value is displayed. Even if the value is displayed, the Help Desk person cannot change it.
However, the Help Desk Manager will always be able to see and set the field for all users.
If the field is shown, it will always be shown in the same place on the panel, no matter what kind of Help Desk administrator.
APSAdmin can also, within limits, vary content by context. Recall that all override expressions support context macros. These are values that only exist at certain times ("contexts") during processing and can be tested within an override.
The APSAdmin interface always sends a context macro of APSAdmin=YES. In the APS Configuration File, you can make sure that a particular field only displays when requested by the APSAdmin interface by using something like:
RW.FullName={%APSAdmin="YES"} TRUE
A utility other than APSAdmin using the API would not be expected to pass an APSAdmin macro and this setting would not apply to it.
The APSAdmin interface allows a site to pass arbitrary context macros using either a SiteMinder Response ("Header Variable") or an environment variable (but not both). The former option is far more useful than the latter.
A site could, for example, use multiple virtual directories to access the APSAdmin executable. Under the SiteMinder Policy Server User Interface, each would require its own realm, rule and response. Since each can also have its own policy, each context can be protected differently.
For each context, specify an additional response attribute called APSADMINCONTEXT containing the desired macros. Each macro is in the format <key>=<value> and multiple macros can be specified, separated by semicolons.
Environment variables must exist within the user process within which the CGI program (APSAdmin) executes. The name of the environment variable is HTTP_APSADMINCONTEXT and its value is the same as the APSADMINCONTEXT response. Setting a environment variable for use under a Web Server, Windows usually requires a machine reboot and Solaris requires that the Web Server be restarted.
An example of the use of contexts:
//server/Reset/APSAdmin.exe
RW.userPassword={%PasswordReset="YES"} TRUE
Note: Warning: Recall that APSAdmin will use the first setting that applies to the current administrator/target combination. When using contexts, it is possible to fall through the definitions for that context and hit another setting, specific to no particular context. Be sure to fully test all combinations of contexts to make sure that unexpected fields (or rights) do not appear.
The function Self() can be used within <target overrides>. This function is available at no other place within the APS Configuration File. The value of the function is TRUE if, and only if, the current administrator is the same as the target user. A really good example of its use is:
RW.userPassword={@HelpDesk} NOT Self()
This allows all help desk administrators to reset passwords for all users other than themselves.
Allowed=Self()Another example: RW.mail=Self()
Assuming no other settings in the APSAdmin section, these lines will allow all users to change their own email address, but no other fields.
APSAdmin supports administrative password resets. This operation allows an administrator to change the password of a user to a known value. It does not require that the administrator know the existing password. This is different from the Change Password Interface that 1) only allows users to change their own password and 2) requires the entry of the current password.
The APSAdmin interface recognizes a specific field name called userPassword and will present an appropriate entry interface.
When changes are posted for a field called userPassword, APS may or may not be required to validate the new entry against required password content. Whether or not this validation is to occur is defined in the APS Configuration File, in the APSAdmin section, using the Validate Password setting.
Every instance of the Validate Password setting will be checked by APS. If any setting applies that has FALSE value, the password content will not be validated. If no Validate Password setting applies or none is contained in the file, passwords will be validated.
Validation is against password content only. It does not include password history or attribute (profile) checking.
The Force Immediate Change setting in the APS Configuration File controls whether APSAdmin (the API) should automatically set the immediate change flag (smapsImmediateChange) when a password is reset.
If any applicable setting is TRUE, the immediate change flag will be set.
One exception: if, on the same update, the immediate change flag is explicitly updated, APSAdmin will not update it automatically.
When building the XML to describe a user account, APS examines a number of things to determine if that element is currently disabling the account, whether the element can be used to disable the account, or if the element will cause the account to be disabled at the next login.
As part of the XML user tag (<user>), APS will return the reasons that the account is disabled, if any, in an XML attribute called "disabled". This is a text string identifying all of the reasons that the account is disabled.
The APSAdmin interface will display these reasons at the top of the panel, along with a graphic indicating that the displayed record is disabled. Possibly, the administrator can reset all of these reasons. However, recall that access to each element in the user record must be explicitly granted. It is possible that not all reasons are accessible to the current administrator.
For groups, APS will check to see if the underlying group is a disabling group. If so, an XML attribute is associated with the field identifying the "Disabled Reason". The APSAdmin interface uses this information to determine if the disabled graphic might be required for that group's membership.
The APSAdmin interface "knows" how to handle the disabling fields smapsDisableUntil, smapsDisableAfter, and smapsMustLoginBy. There is no special XML information generated. If any of these fields disable the account, the interface will display the disabled icon.
During XML generation, APS also may produce an additional XML attribute for the smapsBaseDate and smapsFailureCount fields called redisable. If this attribute is passed, it means that the current value of these fields will cause the account to be disabled at their next login, even if all other disabling values are clear.
For example, if the password has expired, the record might be placed into an LDAP disabling group. The group might be passed to the interface with the proper reason code. The reason code will be passed as part of the XML user tag. If the smapsBaseDate is included in the output, it will have the redisable setting, since, even if the membership in the disable group is reset, the password will just expire again. To get around this, the administrator will need to reset the Base Date. The APSAdmin interface displays a special icon in this case that looks like the standard disabled icon, with a little arrow showing that the user account will become disabled.
Each cause that can disable the user account is separately presented, both in the XML and by the APSAdmin interface. Elements must have explicit rights granted for an administrator to view and/or change. This can be used by a site to create layered administration. For example, there might be three reasons that an account is disabled:
All administrators will see all of the reasons why the account is disabled at the top of the panel (even if they do not have rights to the individual elements). The rationale is that a Help Desk administrator will be able to tell a user, presumably on the phone, why they cannot log in.
A low level Help Desk administrator might have the right to reset users who are locked out because of failure count:
RW.GROUP.FailureCount={@HelpDesk} true
But not have any rights to the other reason codes.
The next level up, @HelpDeskManager, might be able to do Password Expired as well:
RW.GROUP.PwdExpired={@HelpDeskManager} true
But Credit Limit Exceeded can only be reset by the accounting system. The site may wish to grant read rights to that group, so that it is explicitly shown on the form, but no administrator may change it.
The APSAdmin interface recognizes all of the APS-specific fields by logical name. It will translate, edit, and display these fields in appropriate way for their meaning. For example, the date fields (which APS always stores in Greenwich Time) will be displayed/entered in the time zone local to the browser. APSAdmin will handle the conversions to and from GMT.
To reiterate: these fields are recognized by logical name. If these field names are remapped to something else (like smapsBaseDate is passed as BaseDate), the APSAdmin interface will not recognize the field and will not perform its special processing.
APSAdmin recognizes disabling groups, as discussed in the previous section. This not only includes the "known" APS disabling groups, but site-specific, custom ones as well.
Other fields and groups, without specific APS processing, can be used as well, with any desired access right (read, write, read/write). However, the interface will display the value using unmodifable defaults and accept unedited input. No special processing will be performed and there is no way, using the APSAdmin executable, to specify special processing.
The primary purpose of allowing these fields is so that a Help Desk administrator can use things like Name and Phone Number to accurately identify the user on the phone. This type of information often needs to be displayed.
Sometimes, simple fields might also be editable, like Email Address. Just keep in mind that the input field is of limited length and there will be no syntax checking of any kind on the field.
APSAdmin should not be used as a replacement for a full user administration system; it is not intended to be so. If this kind of functionality is required, there are a number of tools available. For LDAP directories, Delegated Management Services (DMS2) is uniquely qualified for this purpose.
|
Copyright © 2014 CA.
All rights reserved.
|
|