IBM Tivoli Monitoring > Version 6.3 Fix Pack 2 > Administrator's Guide > Agent-based services > Agent Service Interface

IBM Tivoli Monitoring, Version 6.3 Fix Pack 2

Access Authorization Group Profile

The Access Authorization Group Profile (AAGP) contains the access authorization group definitions and user ID assignments that are established by the security administrator.

The security administrator can define any access authorization group name with the exception of the Restricted group, which is mandatory. Each access authorization group has at least one agent component category, such as Service Interface (SIAPI element), and services published by that agent component. Each agent component calls upon the AAGP facility to get the user ID, component category, and the requested service name for access authorization. After authorization, the agent component executes the requested service; otherwise the agent returns a status of unauthorized.

The AAGP is not an authentication service and it assumes that the user ID provided has been authenticated. The same assumption is made for the Service Interface because all users must first sign onto the system with a valid ID and password. However, the agent can perform work on behalf of other agents or the Tivoli Enterprise Monitoring Server, such as automation actions, and the user ID on hand could be unknown to the local system. In such a scenario, the agent considers that the virtual user is a trusted Tivoli Monitoring member and therefore authentic and calls upon AAGP for authorization. Alternatively, the AAGP can be enhanced to leverage a centralized authentication and authorization service where such facility becomes available.


Access Authorization Group types

The following default AAGP groups are predefined and they are automatically loaded upon agent startup.

Restricted group

The default group. The Service Interface category in this group consists of services that provide system information, operation configuration, workload monitoring, and historical data reporting capabilities. All users are in this mandatory group, including those that are not specifically defined.

Operation group

This group includes Restricted group category services and the Service Interface services that provide operation control, configuration management, and application customized access capabilities.

Administrative group

This group has access to all Service Interface capabilities, with the addition of File Object and dynamically updating the AAGP.


Access Authorization Group permissions for Service Interface commands

Service Interface API Restricted Operation Administrative
AgentInfo x x x
AttrList x x x
ReadAttr x x x
ListSubnode x x x
TableSit x x x
SitStat x x x
SitSummary x x x
HistRead x x x
Report x x x
PvtControl   x x
CnfgCommand   x x
ConfigurationArtifact   x x
PrivateConfiguration   x x
Overrides   x x
AAGP     x
ListAAGP   x x
FileObj     x

The Restricted group definition is required. If it is not included in the AAGP, the agent default specification shown in Table 1 is in effect.

Specify the keyword *NONE for a component category prohibits all non-explicit users from accessing that component service. For example, <SIAPI>*NONE</SIAPI> specified in Restricted group disallows general access to the Agent Service Interface.

FileObj allows you to push or pull files on an agent using an HTTP request. For Centralized Configuration, FileObj is the API that is used to allow a monitoring agent to act as a central configuration server. The Agent Service Interface is available in the basic services of the monitoring agent and can be used to serve files or you can send HTTP requests to any agent to push or pull files. The AAGP function provides additional security. By default, only root on Linux or UNIX and Administrator on Windows are members of the AD group that has permission to use the FileObj API. See the example in Monitor agent as the central configuration server.

If the AAGP contains no <AAGROUP> specification, the agent default specification shown in Table 1 is in effect. Valid groups are RE, OP, and AD. There is no need to define R (restricted) group users because all users are automatically assigned to the Restricted group unless otherwise defined by the AAGP.


Access Authorization Group Profile XML specification

The security administrator defines the agent User Group Authorization Profile in simple XML specification format:

<AAGP>

This element identifies the XML file as an agent Access Authorization Group Profile document. All AAGP specifications must be enclosed by begin <AAGP> and end </AAGP> root-level element tags. The contents of the AAGP file are merged with the existing AAGP being used by the agent and you can add users to the default Access Authorization Groups. If you prefer to completely replace the existing AAGP, use the REFRESH attribute with the AAGP element.

REFRESH="Y"

Deletes the current active AAGP and replaces it with the AAGP definition from this AAGP specification.

LOCAL="LOCK | UNLOCK"

Optional, with no default value. LOCK and UNLOCK are only accepted when an AAGP update originated from the ASI.

  • LOCAL="LOCK" locks the local AAGP configuration, which cannot be updated by either the ASI or by a Centralized Configuration Facility AAGP file download.

  • LOCAL="UNLOCK" unlocks the local AAGP configuration and AAGP can now be updated by ASI or a Centralized Configuration Facility file download. UNLOCK is valid only when LOCK is in effect, otherwise it is ignored. In other words, <AAGP LOCAL="UNLOCK"> must be preceded by a prior <AAGP LOCAL="LOCK"> operation.

  • <AAGP LOCAL="LOCK"></AAGP> and <AAGP LOCAL="UNLOCK"></AAGP> can be independent stand-alone AAGP ASI transactions.

<AAGROUP>

Defines an Access Authorization Group. Begin <AAGROUP> and end </AAGroup> element tags enclose a set of group definitions.

<GROUPNAME>

Defines the Access Authorization Group name. Specify the name between begin <GROUPNAME> and end </GROUPNAME> element tags. The group name can be up to 32 characters and the first two characters must be unique among all user group names.

<INCLUDE>

Optional. Specifies the AAGROUP definitions to be included in this AAGROUP. Enclose the AAGROUP name within begin <INCLUDE> and end </INCLUDE> tags.

<SIAPI>

Specifies the agent Service Interface API name and is not case-sensitive. Only the component category is defined at this time. Enclose the name within begin <SIAPI> and end </SIAPI> tags.

<other>

The <other> element is not available in the current release; it is reserved for future use. It specifies the other agent component services to be managed.

<AAUSER>

Defines an authorized user ID and its associated Access Authorization Group by name. Enclose each user definition within begin <AAUSER> and end </AAUSER> tags.

<ID>

Specifies an authorized user sign-on ID and is not case-sensitive. Enclose the user ID within begin <ID> and end </ID> tags.

<ASSIGN>

Specifies the Access Authorization Group assignment and is not case-sensitive. Valid AAGP types are RE (Restricted), OP (Operation), and AD (Administrative). You can enter the full group name or the first character. Enclose the AAGP type within begin <ASSIGN> and end </ASSIGN> tags.


Example


Access Authorization Group methodology

All valid system users are automatically authorized for Restricted group access. Authorized, Administrative group, and other groups users are defined by the enterprise security administrator through the AAGP. The following procedure illustrates AAGP methodology.

  1. The enterprise security administrator creates a customized AAGP and stores it at a secure central configuration server. The predefined authorization group content can be customized and additional custom authorization groups added. For example, <AUTOCMD>KILL</AUTOCMD> could be included in the Operation group.

  2. The monitoring agent starts and activates the default AAGP. An administrative ID is defined as a member of the Administrative group by default: Administrator on Windows; root on Linux or UNIX.

  3. The monitoring agent leverages Centralized Configuration and retrieves its own customized AAGP from a central configuration server. The agent always chooses the HTTPS protocol for this operation. If there is no AAGP included in agent's configuration load list or if the AAGP cannot be downloaded from the central configuration server, the agent operates in this mode until the next restart.

  4. Agent components check the AAGP for authorization, which provides the user ID, component category, and service name. The AAGP grants or denies access based on the access authorization group and user ID assignment.

  5. The monitoring agent checks for AAGP updates periodically as specified in the configuration load list or when the Service Interface configuration command is issued.

  6. The monitoring agent does not save or store the User Authorization Profile locally.


Local AAGP Persistent Configuration

An administrator might need to make AAGP customization changes to meet ad-hoc challenges. For example, adding temporary contractor user IDs or rearranging category services per local environment access restrictions. The steps below describe the procedure for implementing local AAGP configuration changes that persist across agent restarts:

  1. Logon to the local system through the Agent Service Interface using an administrator user ID.

  2. Use the <ListAAGP> transaction to retrieve the agent's current AAGP specification.

  3. Edit the ListAAGP output for your new requirements. For example, adding another authorized user ID.

  4. Submit the updated AAGP definitions to the agent through the Agent Service Interface.

  5. The agent processes the input AAGP definitions, which then become the current active AAGP definition in effect. The agent also outputs a copy of the AAGP configuration XML to a local file, either $ITM_HOME$/localconfig/pc/pc_aagpcnfg.txt on distributed systems, or KpcAAGPX.UKANDATV in encrypted format on z/OS systems.

  6. At the next agent startup, the agent searches for the local persistent AAGP configuration file, decrypts and reads the file, and then processes all of its AAGP XML statements. These actions restore the previously customized AAGP definitions. If the agent cannot find the local persistent AAGP configuration file, the default AAGP definitions take effect.

  7. While the locally customized AAGP configuration is in effect, the agent suspends all AAGP updates from the Centralized Configuration Facility, ensuring that the local AAGP customization values remain unchanged. The administrator must submit an <AAGP Resume=”Y”> request through the Agent Service Interface to unlock the local AAGP persistent configuration. This allows the Centralized Configuration Facility to resume its support of AAGP update operations.


Local AAGP Authorization Control

If the administrator wants to enforce strict authorization controls at an agent endpoint and not allow any automation requests from executing, unless the user ID is defined to the local system, then you can use the following procedure to enable local AAGP authorization control:

  1. Logon to local system through the Agent Service Interface using an administrator user ID.

  2. Use the <ListAAGP> transaction to retrieve the agent's current AAGP specification.

  3. Edit the ListAAGP output and delete the default user definition. 

      <AAUSER>     
   <ID>default</ID>      
   <ASSIGN>OP</ASSIGN>   
</AAUSER>

  4. The default user definition instructs AAGP to create an internal secret user ID that is granted the authority to run automation. Without the default user ID definition, AAGP extracts the user ID from each command request sent to the agent. If the extracted user ID is undefined to AAGP, the command request is rejected with an authorization error. This capability gives the local administrator full control over which automation is allowed to run at an agent endpoint.

  5. Submit the updated AAGP definitions to the agent through the Agent Service Interface.


Parent topic:

Agent Service Interface

+

Search Tips   |   Advanced Search