18.3 Identity Server Logging

18.3.1 Configuring Logging for Identity Server

If you change or enable logging, you must update the Identity Server configuration and restart the Embedded Service Providers to apply the changes. When you disable logging, you must also restart the Embedded Service Providers.

This section discusses the following topics:

Enabling Component Logging

File logging records the actions that have occurred. For example, you can configure Identity Server logging to list every request made to the server. With log file analysis tools, you can get a good idea of where visitors are coming from, how often they return, and how they navigate through a site. The content logged to file logging can be controlled by specifying logger levels and by enabling statistics logging.

  1. In the Administration Console, click Devices > Identity Servers > Edit > Logging.

  2. File Logging: The following options are available for component logging:

    • Enabled: Enables file logging for this server and its associated Embedded Service Providers.

    • Echo To Console: Copies the Identity Server XML log file to /var/opt/novell/nam/logs/idp/tomcat/catalina.out (Linux), or to /Program Files (x86)/Novell/Tomcat/logs/stdout.log (Windows Server 2012). You can download the file from Auditing > General Logging.

      For the Embedded Service Providers, the log file location depends upon the device:

      • For an Access Gateway Appliance or a Linux Access Gateway Service, this sends the messages to the catalina.out file of the device.

      • For a Windows Access Gateway Service, this sends messages to the stdout.log file of the device.

    • Log File Path: Specifies the path that the system uses to save the Identity Server XML log file. The default path is /var/opt/novell/nam/logs/idp/nidplogs.

      If you change this path, you must ensure that the user associated with configuring the identity or service provider has administrative rights to the Tomcat application directory in the new path.

      If you have a mixed platform environment (for example, the Identity Server is installed on Windows and the Access Gateway is on Linux), do not specify a path. In a mixed platform environment, you must use the default path.

    • Maximum Log Files: Specifies the maximum number of Identity Server XML log files to leave on the machine. After this value is reached, the system deletes log files, beginning with the oldest file. You can specify Unlimited, or values of 1 through 200. 10 is the default value.

    • File Wrap: Specifies the frequency (hour, day week, month) for the system to use when closing an XML log file and creating a new one. The system saves each file based on the time you specify and attaches the date and/or time to the filename.

    • GZip Wrapped Log Files: Uses the GZip compression utility to compress logged files. The log files that are associated with the GZip option and the Maximum Log Files value are stored in the directory you specify in the Log File Path field.

  3. Component File Logger Levels: Specify the logging sensitivity for the following protocols:

    Application: Logs system-wide events, except events that belong to a specific subsystem.

    Liberty: Logs events specific to the Liberty IDFF protocol and profiles.

    SAML 1: Logs events specific to the SAML1 protocol and profiles.

    SAML 2: Logs events specific to the SAML2 protocol and profiles.

    WS Trust: Logs events specific to the WS-Trust protocol.

    WS Federation: Logs events specific to the WS Federation protocol.

    OAuth and OpenID Connect: Logs events specific to the OAuth and OpenID Connect protocols.

    Web Service Provider: (Liberty) Logs events specific to fulfilling Web service requests from other Web service consumers.

    Web Service Consumer: (Liberty) Logs all events specific to requesting Web services from a Web service provider.

    Use the drop-down menu to categorize logging sensitivity. Higher logging levels also include the lower levels in the log.

    • Off: Turns off component file logging for the selected item.

    • Severe: Logs serious failures that can cause system processing to not proceed.

    • Warning: Logs potential failures, but the impact on execution is minimal. Warnings indicate that you should be aware that this event is happening and might want to make a configuration change to avoid it.

    • Info: Logs informational events. No execution or data impact occurred.

    • Verbose: Logs static configuration information. The system logs any configuration errors under one of the primary three levels: Severe, Warning, and Info.

    • Debug: Includes all of the preceding levels.

  4. Statistics Logging: (Optional) Enable this option if you want the system to periodically send the system statistics, in string format, to the current file logger. Statistical data (such as counts, levels, and so on) are included in the file log.

    1. In the Statistics Logging section, select Enabled.

    2. In the Log Interval field, specify the time interval in seconds that statistics are logged.

  5. Novell Audit Logging: For information about configuring Novell Audit Logging, see Enabling Identity Server Audit Events.

  6. Click OK.

  7. Update the Identity Server.

  8. Restart the Embedded Service Providers on the devices, in order to apply the changes.

    When you disable component logging, you need to update the Identity Servers and restart the Embedded Service Providers.

Managing Log File Size

On Linux, the logrotate daemon manages the log files located in the following directories:

/opt/novell/nam/logs
/opt/volera/roma/logs/

On Windows, you need to manually monitor the size of the log files. On Linux, the logrotate daemon manages the log files located in the following directories:

/opt/novell/nam/idp/logs
/opt/volera/roma/logs/

The logrotate daemon has been configured to scan the files in these directories once a day. It rolls them over when they have reached their maximum size and deletes the oldest version when the maximum number of copies have been created.

If you want to modify this behavior, see the following files in the /etc/logrotate.d directory:

novell-tomcat7
novell-devman

For information about the parameters in these files, see the documentation for the logrotate daemon.

18.3.2 Configuring Session-Based Logging

The session-based logging feature allows the administrator to enable file logging for an individual user. In production environments, this has the following value:

  • Debug logging can be turned on for an individual user rather than all users. The potential size of logged data usually prohibits an administrator from turning on debug logging for all users.

  • All logged messages for this user are directed to a single file. Administrators do not need to sort through the various log files to follow the activity of the user.

  • Isolating the problem and finding the cause is limited to the user who is experiencing the problem.

  • Enabling session-based logging does not require a configuration change to the Identity Server, and thus does not require updating the Identity Server.

The following user scenario explains how this feature could be used in a production environment

  1. A user notices a problem and calls the help desk.

  2. The help desk operator questions the users and concludes that the problem is caused by either a NetIQ Identity Server or an Embedded Service Provider.

  3. The operator has been granted the rights to create logging tickets, and uses the User Portal to create a logging ticket for the user.

  4. The operator sends the logging ticket password and the URL to access the logging ticket class to the user.

  5. The user clicks the URL and enters the logging ticket password.

    This marks the current session as “active for logging” and adds a small icon to the top right of the page, which makes the session logging feature visible to the user.

  6. Using the same browser window, the user duplicates the problem behavior.

  7. The operator can then access the data that was logged just for this user and analyze the cause of the behavior.

To enable session-based logging, the following tasks need to be completed:

Creating the Administrator Class, Method, and Contract

The IDP Administrator class, method, and contract control who has the rights to create a logging ticket. You need to know the DNs of the operators who are going to be responding to the users who are experiencing problems.

  1. In the Administration Console, click Devices > Identity Servers > Edit > Local.

  2. To create the class:

    1. Click Classes.

    2. Click New, then specify the following values:

      Display name: IDP Administrator

      Java class: Other

      Java class path: com.novell.nidp.authentication.local.IDPAdministratorClass

    3. Click Next, then click Finish.

  3. To create the method:

    1. Click Methods.

    2. Click New, then specify the following values:

      Display name: IDP Administrator Method

      Class: IDP Administrator

      Identifies user: Deselect this option.

      User Stores: Select the user stores that contain your operators, then move them to the list of User Stores.

    3. In the Properties section, click New, then specify the following to create an IDP Administrator:

      Property Name: Administrator1

      The Property Name must begin with Administrator; append a value to this so that each property has a unique value.

      Property Value: cn=jdoe,o=users

      The Property Value must be the DN of an operator in the user stores you selected in Step 3.b. Use LDAP typed comma notation for the DN.

    4. Repeat Step 3.c for each IDP Administrator you require.

      You can return to this method to add or remove IDP Administrators, when responsibilities change.

    5. Click Finish.

  4. To create the contract:

    1. Click Contracts.

    2. Click New, then specify the following values:

      Display name: IDP Administrator Contract

      URI: urn:novell:nidp:admin:contract

      Methods: Move the IDP Administrator Method to the Methods list.

      Leave all other fields with their default values.

    3. Click Next, then specify the following values for the authentication card:

      ID: IDPAdmin

      Text: IDP Administrator

      Image: Select an image from the list, such as the IDP Administrator image that was created for this type of contract.

      Show Card: Deselect this option.

    4. Click Finish.

  5. Continue with Creating the Logging Session Class, Method, and Contract.

Creating the Logging Session Class, Method, and Contract

  1. In the Administration Console, click Devices > Identity Servers > Edit > Local.

  2. To create the class:

    1. Click Classes.

    2. Click New, then specify the following values:

      Display name: Logging Session

      Java class: Other

      Java class path: com.novell.nidp.authentication.local.LogTicketClass

    3. Click Next, then click Finish.

  3. To create the method:

    1. Click Methods.

    2. Click New, then specify the following values:

      Display name: Logging Session Method

      Class: Logging Session

      Identifies user: Deselect this option.

      User Stores: Select the user stores that contain the users that potentially can experience problems, then move them to the list of User Stores.

    3. Click Finish.

  4. To create the contract:

    1. Click Contracts.

    2. Click New, then specify the following values:

      Display name: Logging Session Contract

      URI: urn:novell:nidp:loggingsession:contract

      Methods: Move the Logging Session Method to the Methods list.

      Leave all other fields with their default values.

    3. Click Next, then specify the following values for the authentication card:

      ID: LogSession

      Text: Logging Session

      Image: Select an image from the list, for example the Session Logging image that was created for this type of contract.

      Show Card: Deselect this option.

    4. Click Finish.

  5. Click OK, then update the Identity Server.

  6. Continue with Enabling Basic Logging.

Enabling Basic Logging

For session-based logging to function, logging on the Identity Server must be enabled. However, you do not need to select what is logged. The Logging Ticket enables the appropriate components and levels when an incident occurs.

  1. In the Administration Console, click Devices > Identity Servers > Edit.

  2. Click Logging, then specify the following:

    File Logging: Enable this option.

    Echo To Console: Enable this option.

    No other options need to be enabled. The Component File Logger Levels can be left in their default state of off.

  3. Click OK, then update the Identity Server.

    This completes the configuration. You now need to wait for a user to report a problem. For information about using this feature to respond to a problem, see Responding to an Incident.

Responding to an Incident

The following sections explain how to use the feature when a user reports a problem:

Creating a Logging Ticket

These steps are performed by an IDP Administrator when a user reports a problem:

  1. Log in to the Identity Server by using the credentials of an administrator.

    If the base URL of the Identity Server is https://idp.amlab.net:8443/nidp, enter the following URL:

    https://idp.amlab.net:8443/nidp/app
  2. Change to the Logging Ticket page by specifying the following URL:

    https://idp.amlab.net:8443/nidp/app/login?id=IDPAdmin

    The id specified in the URL must match the ID you specified for the ID of the IDP Administrator Contract. See Step 4.c of Creating the Administrator Class, Method, and Contract.

    If you logged in with the credentials of an IDP Administrator, an Administrator tab appears.

  3. To create a ticket for the user, click the Administrator tab.

    1. Click New.

    2. Specify the following:

      Ticket: Specify a name for ticket.

      You must share this name with the user who reported the problem.

      Ticket Good For: Select a time limit for the ticket, from one minute through one year.

      When selecting a time limit, consider the following:

      • When a ticket expires, logging is automatically stopped. If you know that user is experiencing a problem that prevents the user from logging out, you might want to create a ticket with a short time limit.

      • If the user does not log out (just closes the browser window or the problem closes it), the session remains in the list of logged sessions. After 10 minutes of inactivity, the session is closed and the lock on the log file is cleared. As long as the log file is locked, no other application can read the file.

      Ticket Log Level: Select the level of information to log, from severe-only messages to debug.

      Log to Console: Select to log the messages to the user’s file and to the console.

      • If you have set up logging for session-based logging (see Enabling Basic Logging), then this allows you see the messages in the catalina.out or stdout.log file.

      • If you have enabled Component File Logger Levels, selecting this option can create duplicate entries in the catalina.out or stdout.log file.

    3. Click Create.

  4. Create a URL that uses the following format:

    https://<base_URL>/nidp/app/login?id=<LogSession>

    Replace <base_URL> with the base URL of your Identity Server, including the port. Ensure that the port agrees with the HTTP scheme (either http or https).

    Replace <LogSession> with the ID you specified for the authentication card when defining the Logging Session contract.

    IMPORTANT:The id is the ID of the authentication card of the Logging Session contract (see Step 4.c of Creating the Logging Session Class, Method, and Contract). It is not the name of the ticket you just created.

    If the base URL of the Identity Server is https://idp.amlab.net:8443/nidp and the ID for the authentication card is LogSession, create the following URL:

    https://idp.amlab.net:8443/nidp/app/login?id=LogSession
  5. Send the URL of the LogSession card and the name of the ticket to the user.

Enabling a Logging Session

These steps are performed by the user. The URL needs to be sent to the user, with the ID and ticket values that were specified in Creating a Logging Ticket.

  1. Open a browser and enter the log session URL sent by the help desk.

    If the URL does not display a page that prompts for the ticket name, check the value of the id string. The id must be set to the ID of the authentication card of the Logging Session contract.

    Instead of sending the user a URL, you can enable the Show Card option for the Logging Session card. When you do this, all users can see it. You need to decide if this is acceptable.

    When the Show Card option is enabled, the login page looks similar to the following:

  2. When prompted, enter the following:

    Ticket: Specify the ticket name that the help desk sent.

    User Identifier: Specify a value that the help desk associates with you as a user. The identifier must be less than 33 characters and contain only alphanumeric characters.

  3. Click Login.

    This login creates the logging session.

  4. Enter your name and password, then click Login.

    This login authenticates you to the Identity Server.

  5. In the same browser window, enter the URL of the resource that is causing the problem.

  6. Perform any other actions necessary to create the problem behavior.

  7. Log out and send your user identifier to the help desk.

Viewing the Log File

These steps are performed by someone who has had Access Manager training and understands the significance of the messages in the log files. This can be an IDP Administrator or a specialist.

  1. On the Identity Server, change to the Tomcat log directory.

    Linux: /var/opt/novell/nam/logs/idp/nidplogs

    Windows Server 2012: \Program Files (x86)\Novell\Tomcat\webapps\nidp\WEB-INF\logs

  2. Open the file that begins with the user identifier to which a session ID is appended.

    If the user does not log out (just closes the browser window or the problem closes it), the session remains in the list of logged sessions. After 10 minutes of inactivity, the session is closed and the lock on the logging file is cleared. As long as the file is locked, no other application can read the file.

    When a ticket expires, logging is stopped automatically. If you know that user is experiencing a problem that prevents the user from logging out, you might want to create a ticket with a short time limit.

  3. (Conditional) If the user was experiencing a problem with an Embedded Service Provider, change to the Tomcat log directory on the device:

    Linux: /opt/novell/nam/idp/webapps/nesp/WEB-INF/logs

    Windows Server 2012: \Program Files (x86)\Novell\Tomcat\webapps\nesp\WEB-INF\logs

  4. Open the file with the same user identifier and session ID.

  5. After solving the problem, delete the file from each Identity Server in the cluster and each Access Gateway in the cluster.