Authentication failures on the SAS Metadata Server are often presented to the end user as a circular re-prompting for credentials, or a message such as the following:

It is often necessary to see logging with more details about the authentication process on the SAS Metadata Server to determine why authentication is failing. In particular, trace-level logging is helpful in troubleshooting unexpected or erroneous behavior in the following scenarios:

• Metadata server direct use of the Lightweight Directory Access Protocol (LDAP)
• Metadata server direct authentication to LDAP over the Secure Sockets Layer (SSL)
• Metadata server direct authentication to LDAP over SSL with Federal Information Processing Standards (FIPS) 140-2 mode
• Use of mixed authentication providers (for example, host and LDAP providers)

If you encounter an authentication failure, complete the following five steps to troubleshoot the problem:

Step 1: Determine Which Loggers Are Relevant

If your metadata server authentication mechanism is Metadata server direct use of LDAP, or a combination of providers such as host and LDAP, then you should set the Audit.Authentication logger to Trace. This logger writes server authentication requests that contain the inbound user ID, the authentication provider that was used, and the authenticated user ID.

If your metadata server authentication mechanism is Metadata server direct authentication to LDAP over SSL, or it incorporates FIPS 140-2, then you should set the Audit.Authentication, App.tk.eam, and App.tk.LDAP loggers to Trace. The two App.tk loggers include messages regarding the FIPS mode and the SSL handshake process.

If your metadata server is a UNIX or Linux operating system and you know that host authentication is failing, then follow the instructions in SAS Note 39891: "Using PROC PERMTEST to diagnose UNIX host authentication issues in SAS^® 9.2 and later releases."

Step 2: Set Logger Levels

Here are two common ways to change logger levels on the SAS Metadata Server:

• SAS^® Management Console
• The IOMOPERATE Procedure

Both methods take effect immediately and do not require that you restart the SAS Metadata Server. If you are running a clustered metadata server environment, the loggers must be changed on all nodes in the cluster. The App.tk.LDAP logger cannot be set within SAS Management Console. Therefore, if you need to set the level for App.tk.LDAP, use the IOMOPERATE procedure.

Caution: The SAS Metadata Server log files grow quickly in size with trace logging enabled, particularly with the App.tk loggers enabled. Running out of disk space can cause the metadata server to stop performing, and can cause corruption to the metadata repository. When you adjust logger levels, you must be certain that you monitor disk space. Return the loggers to their prior levels once you have captured the events that you need to trace.

Set Logger Levels Using SAS Management Console

1. Log in to SAS Management Console as an administrator (for example, sasadm@saspw).
2. Expand Server Manager ► SASMeta ► SASMeta - Logical Metadata Server ► SASMeta - Metadata Server.
3. Right-click SASMeta - Metadata Server and select Connect.
4. Provide your administrator credentials again, if prompted.
5. Click the Loggers tab.
6. In the list of loggers, open the properties for the logger that you need to set, such as Audit.Authentication.
7. Change the Assigned drop-down list to Trace.
8. Click OK.
9. Repeat the procedure to set the level for other loggers.

Note:The App.tk.LDAP logger is not accessible from within SAS Management Console. Use the IOMOPERATE procedure to set that logger.

For more information, see the "Use the Loggers Tab in the Server Manager, and (If Necessary) Change Logging Levels for Individual Loggers" section on page 113 in SAS^® 9.4 Intelligence Platform: System Administration Guide.

Set Logger Levels Using the IOMOPERATE Procedure

1. Edit the following code by providing valid values for the HOST=, PORT=, USER=, and PASS= options in order to connect to the SAS Metadata Server:
   
   proc iomoperate; connect host='host-name' port=port-number user='user-ID' pass='password'; list attributes category="Loggers"; set attribute category="Loggers" name="Audit.Authentication" value="Trace"; quit;
   If you determined that you need the two App.tk loggers, your step must include two additional SET statements:
   
   proc iomoperate; connect host='host-name' port=port-number user='user-ID' pass='password'; list attributes category="Loggers"; set attribute category="Loggers" name="Audit.Authentication" value="Trace"; set attribute category="Loggers" name="App.tk.LDAP" value="Trace"; set attribute category="Loggers" name="App.tk.eam" value="Trace"; quit;
2. Submit the procedure step from within a Base SAS^® session. It is generally best to use a SAS session that is launched from the SAS Metadata Server, but it is not mandatory as long as the SAS session can connect to the SAS Metadata Server.

Note: The LIST statement within the IOMOPERATE procedure generates a listing of logger levels before to changing their value. This is a useful reference for step 5, below, to return loggers to their previous level.

For more details about loggers, see "Chapter 1: The SAS Logging Facility" in SAS^® 9.4 Logging: Configuration and Programming Reference.

Step 3: Reproduce Problem and Evaluate Trace Logs

Reproduce the authentication failure or monitor authentication activity, noting the user ID and time of the authentication problems. Evaluate the SAS Metadata Server log.

The start of each authentication request is marked by the string, Create Authenticated Token, and ends with New client connection ..., similar to the following two examples:

Note: The above examples show results from the Audit.Authentication logger. Results from App.tk.eam and App.tk.LDAP include far more data.

Step 4: Send Information to SAS Technical Support

If you need help with reading the trace logs, or otherwise determining what to do with the trace data, send the following information to SAS Technical Support:

• The metadata server log from the test period after enabling trace logging and reproducing the authentication problem
• The metadata server configuration files:
  • SASMeta/MetadataServer/sasv9.cfg
  • SASMeta/MetadataServer/sasv9_usermods.cfg
  • SASMeta/MetadataServer/MetadataServer.sh (MetadataServer.bat for Windows systems)

Step 5: Return Loggers to Their Previous Settings

It is important to return loggers to their previous levels. With trace-logging enabled, particularly for the App.tk loggers, log files grow rapidly in size. Running out of disk space for the log files can cause the metadata server to stop performing, and can cause corruption to the metadata repository. If you ran the IOMOPERATE procedure, as indicated above, to set the logger levels to Trace, you can refer to the List output that was written to the SAS Log to determine the initial level for the loggers.

Return Logger Levels Using SAS Management Console

1. Log in to SAS Management Console as an administrator (for example, sasadm@saspw).
2. Expand Server Manager ► SASMeta ► SASMeta - Logical Metadata Server ► SASMeta - Metadata Server.
3. Right-click SASMeta - Metadata Server and select Connect.
4. Provide your administrator credentials again, if prompted.
5. Click the Loggers tab.
6. In the list of loggers, open the properties for the logger that you need to set.
7. Change the Assigned drop-down list to the new value, or click the Inherited radio button.
8. Click OK.
9. Repeat this procedure to set the level for other loggers.

Return Logger Levels Using the IOMOPERATE Procedure

1. Edit the following code by providing valid values for the HOST=, PORT=, USER=, and PASS= options in order to connect to the SAS Metadata Server. In the SET statement, use a value of "NULL" to set the logger to its Inherited level. Or, set the value to a new level, such as "Info" or "Debug".
   
   proc iomoperate; connect host='host-name' port=port-number user='user-ID' pass='password'; set attribute category="Loggers" name="Audit.Authentication" value="NULL"; list attributes category="Loggers"; quit;
   proc iomoperate; connect host='host-name' port=port-number user='user-ID' pass='password'; set attribute category="Loggers" name="Audit.Authentication" value="NULL"; set attribute category="Loggers" name="App.tk.LDAP" value="NULL"; set attribute category="Loggers" name="App.tk.eam" value="NULL"; list attributes category="Loggers"; quit;
2. Submit the procedure step from within a Base SAS^® session. It is generally best to use a SAS session that is launched from the SAS Metadata Server, but it is not mandatory as long as the SAS session can connect to the SAS Metadata Server.

Note: Restarting the SAS Metadata Server reverts logging to the original levels. These levels are determined by the Log Configuration file.

Operating System and Release Information