MID Server user connectivity issues

The instance writes issues involving MID Server user logins and network connectivity to the MID Server Issue [ecc_agent_issue] table and creates events you can use in custom scripts or to send email notifications.

Records in the MID Server Issue [ecc_agent_issue] table can provide insight into why your MID Server user cannot log in or why a MID Server cannot connect to the instance. The system displays records for connectivity problems in this table that include informative error messages suggesting possible causes. By default, a scheduled job called MIDUserConnectivity runs every four hours and launches the MIDUserConnectivity script include to evaluate MID Server connection activity. Records in the MID Server Issue [ecc_agent_issue] table reflect the status of MID Server login attempts and connectivity at the time the scheduled job runs.

From the perspective of the instance, the MID Server is Down when:
  • User authentication fails
  • User authorization fails.
  • Network issues prevent MID Server from establishing a TCP/IP connection.
Note: To associate a user with a MID Server, navigate to the servicenow/<mid server name>/agent/config.xml file and enter the user credentials in the mid.instance.username and mid.instance.password parameters. Make sure to restart the MID Server to activate your changes.

How issues are logged

User authentication failures and authorization issues are logged automatically to the MID Server agent log file. The message for both is the same: User cannot be authenticated or is missing the proper roles. If the issue is related to authorization, the agent.log file shows the list of missing roles.

When debugging is enabled, MID Server issues are logged to the system log (syslog) and are available for display in either a summary or a detailed format. You can also change the sampling interval from the default 4 hours to something shorter for tracking your remediation efforts. For instructions on enabling and configuring debugging for MID Server user issues, see Test remediation efforts for MID Server user connectivity issues.

Data provided

When the instance encounters user connectivity issues, it opens a record in the MID Server Issue [ecc_agent_issue] table.
Figure 1. Example user authentication error message
Example user authentication error message
The MID Server Issue table contains these fields:
Table 1. MID Server issue fields
Field Description
Last detected Date and time the issue was last detected.
Short description Contents of the generated message that specifies a possible issue with the named user or the MID Server.
MID Server Empty in the Jakarta release.
Issue source The process that identified the issue. For all issues with MID Server user connectivity, the source is MIDUserConnectivity.
State The current state of the issue. Possible states are:
  • New: Starting state when the instance creates the issue.
  • Acknowledged: State set when the administrator first examines the issue.
  • Resolved: Ending state, set by the instance, indicating that the issue has been resolved. If the scheduled job does not encounter the issue when it runs again, the instance automatically sets this value.
Domain Domain associated with the MID Server user account.
Count Number of times an issue has been detected. Each time the scheduled job runs and encounters the same issue, it increments this field.

User authentication failure

The credentials that the instance uses to authenticate a MID Server user are configured in the MID Server Configuration Parameters [ecc_agent_config] table. If the MID Server user attempts to log into the instance with invalid credentials, the instance rejects the connection, and writes the login.failed event to the Events [sysevents] table for the user. Administrators can use this event in a custom script or in email notifications for authentication failure.

Note: If user authentication fails, user authorization is not attempted.

User accounts associated with a MID Server

Either of the following messages in the MID Server Issue [ecc_agent_issue] table indicate authentication failure for user accounts that are associated with a MID Server:
  • Login authentication failure for User <user name> associated with 1 down MID Server. Check password on MID server.
  • Login authentication failure for User <user name> associated with <n> down MID Servers. Check password on MID servers.
The necessary conditions for these messages to appear are:
  • The Status field in the MID Servers [ecc_agent] table that is associated with the MID Server indicates that the MID Server is Down.
  • The user identified in the MID Server Configuration Parameters [ecc_agent_config] table is the user that one or more MID Servers is configured to use for authentication and authorization when connecting to the instance. The record in the [ecc_agent_config] table must have these values:
    • Parameter name [param_name] field set to mid.instance.username.
    • Value [value] field set to the user’s name, corresponding to the User ID [user_name] field in Users [sys_user] table.
  • The Events [sysevent] table contains posts showing that the last login attempt associated with the user failed during the scheduled time period. The record created in the [sysevent] table contains these field values:
    • Event Name [name] field is set to login.failed.
    • Parm1 [parm1] field is set to the user’s name.
Note: The MID Server [mid_server] field in the MID Server Issues [ecc_agent_issue] table is empty (=NULL).

User accounts with the mid-server role not associated with a MID Server

The following message appears when a user with the mid_server role who is not associated with a MID Server fails to authenticate: Login authentication failure for User <user name> with mid_server role not associated with a MID Server.

The necessary conditions for this message to appear are:
  • The User Roles [sys_user_has_role] table contains a record linking the sys_id associated with the user record stored in the [sys_user] table, with the sys_id associated with the mid_server role record stored in the [sys_user_role] table.
  • The user is not identified in the MID Server Configuration Parameters [ecc_agent_config] table as the user whom one or more MID Servers are configured to use for authentication and authorization when connecting to the instance.
  • The Events [sysevent] table contains posts showing that the last login attempt associated with the user failed during the scheduled time period.
    • The [sysevent] table contains a record with the Event Name [name] field set to login.failed.
    • The Parm1 [parm1] field is set to the user’s name, corresponding to the User ID [user_name] field in Users [sys_user] table.
Note: The MID Server [mid_server] field in the MID Server Issues [ecc_agent_issue] table is empty (=NULL).

User authorization failure

The user authorization check occurs after the MID Server has successfully authenticated on the instance. In this step, the system ensures that the user account associated with a MID Server is granted the minimum roles required. A SOAP web service called MIDServerCheck performs the role checking on the instance. If the MID Server user has the proper roles, the connection is allowed and a login event is written to the Events [sysevents] table. If the user does not have the proper roles, the instance writes a login.authorization.failed event to the Events [sysevents] table. This event provides a comma separated list of the user's missing roles. Administrators can use this event in custom scripts or in email notifications for authorization failure.

Authorization can fail if a user is missing the mid_server role or any of the important SOAP roles, as in these cases:
  • If the user has the soap_script role, the MIDServerCheck SOAP web service runs to check for the appropriate MID Server roles. If the user lacks the mid_server role or any of the other SOAP roles, authorization fails, and the login.authorization.failed event is created.
  • If the user is missing the soap_script role, that user is not authorized to launch the MIDServerCheck SOAP web service, which checks for all required MID Server roles. Authorization fails, but the login.authorization.failed event is not created. When this occurs, the instance displays this message: Connectivity of MID Server user <user name> cannot be detected by the instance.

Users associated with one or more down MID Servers

Either of the following messages in the MID Server Issue [ecc_agent_issue] table indicate authorization failure for user accounts that are associated with a MID Server that is Down:
  • Login authorization failure for User <user name> associated with 1 down MID Server. Re-assign mid_server role to grant all required roles.
  • Login authorization failure for User <user name> associated with <n> down MID Servers. Re-assign mid_server role to grant all required roles.
The MIDUserConnectivity script include identifies active users associated with one or more down MID Servers whose last login attempt within the reporting period failed user authorization. This message is generated when user authorization failures are detected and reported by the MIDServerCheck scripted web service. However, user authorization failures are not reported for users who are not assigned the soap_script role. Should this occur, problems with the user are reported by the network connectivity message.
This message appears in the MID Server Issue [ecc_agent_issue] table when:
  • The user may or may not have the mid_server role.
  • The user is identified in the MID Server Configuration Parameters [ecc_agent_config] table as the user whom one or more MID Servers are configured to use for authentication and authorization when connecting to the instance.
  • The Events [sysevent] table contains posts showing that the last login attempt associated with the user failed during the scheduled time period. The [sysevent] table contains a record with these settings:
    • Event Name [name] field set to login.authorization.failed.
    • Parm1 [parm1] field set to the user’s name, corresponding to the User ID [user_name] field in Users [sys_user] table.
Note: The MID Server [mid_server] field in the MID Server Issues [ecc_agent_issue] table is empty (=NULL).

Users with the proper role not associated with a MID Server

The following message appears when a user with the mid_server role who is not associated with a MID Server fails authorization: Login authorization failure for User <user name> with mid_server role not associated with a MID Server.

This message is generated when user authorization failures are detected in which the user account, with the mid_server role, is not identified as a configured MID Server user in the [ecc_agent_config] table. It is possible that the user account was associated with a MID Server at the time of the failure.

This message appears in the MID Server Issue [ecc_agent_issue] table when:
  • The user has the mid_server role. The User Roles [sys_user_has_role] table has a record linking the sys_id associated with the user record stored in the [sys_user] table, with the sys_id associated with the mid_server role record stored in the [sys_user_role] table.
  • The user is not identified in the MID Server Configuration Parameters [ecc_agent_config] table as the user whom one or more MID Servers are configured to use for authentication and authorization when connecting to the instance.
  • The Events [sysevent] table contains posts showing that the last login attempt associated with the user failed during the scheduled time period. The [sysevent] table contains a record with these settings:
    • Event Name [name] field set to login.authorization.failed.
    • Parm1 [parm1] field set to the user’s name, corresponding to the User ID [user_name] field in Users [sys_user] table.
Note: The MID Server [mid_server] field in the MID Server Issues [ecc_agent_issue] table is empty (=NULL).

Network issues

A network issue can prevent the MID Server from connecting to the instance's TCP/IP server to begin a session. In this case, the instance marks the MID Server as Down, because the instance failed to receive the MID Server heartbeat within the prescribed 5 minute interval.

Users associated with down MID Servers who have not attempted to log in

Either of the following messages in the MID Server Issue [ecc_agent_issue] table name users associated with MID Servers who have not attempted to log in during the reporting period:
  • User <user name> is associated with 1 down MID Server. No login attempts within reporting period.
  • User <user name> is associated with <n> down MID Servers. No login attempts within reporting period.

The MIDUserConnectivity script include reports active users associated with down MID Servers where network connectivity cannot be detected by the instance.

This message appears in the MID Server Issue [ecc_agent_issue] table when:
  • The user may or may not have the mid_server role.
  • The user is identified in the MID Server Configuration Parameters [ecc_agent_config] table as the user which one or more MID Servers are configured to use for authentication and authorization when connecting to the instance.
  • There are no login attempts, either failed or successful, recorded in the Events [sysevent] table for the user during the scheduled reporting period.
Note: The MID Server [mid_server] field in the MID Server Issues [ecc_agent_issue] table is empty (=NULL).

Users not associated with MID Servers who have not attempted to log in

The following message appears when a user with the mid_server role who is not associated with a MID Server has not attempted to login during the configured reporting interval: User <user name> with mid_server role is not associated with a MID Server. No login attempts within reporting period.

The MIDUserConnectivity script include reports active users with the mid_server role not associated with a MID Server, where connectivity cannot be detected by the instance.

This message appears in the MID Server Issue [ecc_agent_issue] table when:
  • The user has the mid_server role. The User Roles [sys_user_has_role] table has a record linking the sys_id associated with the user record stored in the [sys_user] table, with the sys_id associated with the mid_server role record stored in the [sys_user_role] table.
  • The user is not identified in the MID Server Configuration Parameters [ecc_agent_config] table as the user whom one or more MID Servers are configured to use for authentication and authorization when connecting to the instance.
  • There are no login attempts, either failed or successful, recorded in the Events [sysevent] table for the user during the scheduled reporting period.
Note: The MID Server [mid_server] field in the MID Server Issues [ecc_agent_issue] table is empty (=NULL).

Configuration issues

Any of the following messages, discussed above, can indicate a configuration issue:
  • Login authentication failure for User <user name> with mid_server role not associated with a MID Server.
  • Login authorization failure for User <user name> with mid_server role not associated with a MID Server.
  • User <user name> with mid_server role is not associated with a MID Server. No login attempts within reporting period.
These are some common configuration errors:
  • An administrator neglected to associate the user record with the MID Server record as shown in the MID Server Configuration Parameters [ecc_agent_config] table. This table is read-only and cannot be updated directly. To associate a user with a MID Server, configure the user name and password in the MID Server's config.xml file and restart the MID Server.
  • During the process of reconfiguring a MID Server to use a different account for TCP/IP connection, the administrator has not yet removed the mid_server role from the account or deleted the account.
  • A multipurpose user account was created and granted a large number of roles, including the mid_server role, although this account was never intended to be used as a MID Server account.

User who successfully authenticates and authorizes but might not need mid_server role

The following message appears when a user with the mid_server role who is not associated with a MID Server successfully logs in: User <user name> with mid_server role successfully connected but not associated with a MID Server. The mid_server role should be reserved for MID Server use only.

The MIDUserConnectivity script include reports active users with the mid_server role who are not identified as a configured MID Server user, and whose last login attempt was successful during the scheduled time period. This message suggests that the user’s credentials are being used by a system administrator or a process that is not running on a MID Server. The assumption here is that the mid_server role should only be used for applications deployed to a MID Server. The presence of this message reminds the system administrator to remove extraneous mid_server roles from user accounts that do not require them.

This message appears in the MID Server Issue [ecc_agent_issue] table when:
  • The user has the mid_server role.
  • The user is not identified in the MID Server Configuration Parameters [ecc_agent_config] table as the user whom one or more MID Servers are configured to use for authentication and authorization when connecting to the instance.
  • The Events [sysevent] table contains posts showing that the last login attempt associated with the user succeeded during the scheduled time period. The [sysevent] table contains a record with these settings:
    • Event Name [name] field set to login.
    • Parm1 [parm1] field set to the user’s name, corresponding to the User ID [user_name] field in Users [sys_user] table.
Note: The MID Server [mid_server] field in the MID Server Issues [ecc_agent_issue] table is empty (=NULL).