25 Enabling Debugging for SAML 1.1 and 2.0

Oracle Weblogic Server provides a variety of ways to enable debugging for a web application that uses SAML for SSO. Debugging is configured by setting attributes on the ServerDebug MBean.

This chapter includes the following topics:

About SAML Debug Scopes and Attributes

Learn about the registered debug scopes and attributes provided in WebLogic Server for SAML 1.1 and 2.0.

Table 25-1 SAML 1.1 Debug Scopes and Attributes

Scope Attribute Description
weblogic.security.saml.atn
DebugSecuritySAMLAtn

Prints information about SAML 1.1 authentication provider processing.

weblogic.security.saml.credmap
DebugSecuritySAMLCredMap

Prints information about SAML 1.1 credential mapping provider processing.

weblogic.security.saml.lib
DebugSecuritySAMLLib

Prints information about SAML 1.1 library processing.

weblogic.security.saml.service
DebugSecuritySAMLService

Prints information about SAML 1.1 SSO profile services.

Table 25-2 SAML 2.0 Debug Scopes and Attributes

Scope Attribute Description
weblogic.security.saml2.atn
DebugSecuritySAML2Atn

Prints information about SAML 2.0 authentication provider processing.

weblogic.security.saml2.credmap
DebugSecuritySAML2CredMap

Prints information about SAML 2.0 credential mapping provider processing.

weblogic.security.saml2.lib
DebugSecuritySAML2Lib

Prints information about SAML 2.0 library processing.

weblogic.security.saml2.service
DebugSecuritySAML2Service

Prints information about SAML 2.0 SSO profile services.

Enabling Debugging Using the Command Line

You can enable debug scopes or attributes by passing them as options in the command that starts WebLogic Server. This method for enabling SAML debugging is static and can only be used at server startup.

The command line options you can use for enabling SAML debugging by attribute are listed in Table 25-3.

Table 25-3 Command Line Options for SAML Debugging

SAML Version Available Command Line Options for Debugging

SAML 1.1

-Dweblogic.debug.DebugSecuritySAMLAtn=true
-Dweblogic.debug.DebugSecuritySAMLCredMap=true
-Dweblogic.debug.DebugSecuritySAMLLib=true
-Dweblogic.debug.DebugSecuritySAMLService=true

SAML 2.0

-Dweblogic.debug.DebugSecuritySAML2Atn=true
-Dweblogic.debug.DebugSecuritySAML2CredMap=true
-Dweblogic.debug.DebugSecuritySAML2Lib=true
-Dweblogic.debug.DebugSecuritySAML2Service=true

Enabling Debugging Using the WebLogic Server Administration Console

You can enable SAML debugging using the WebLogic Server Administration Console. Using the WebLogic Server Administration Console to enable or disable SAML debugging is dynamic and can be used while the server is running.

To configure SAML debugging using the WebLogic Server Administration Console, complete the following steps:

  1. If you have not already done so, in the Change Center of the WebLogic Server Administration Console, click Lock & Edit (see Use the Change Center in the Oracle WebLogic Server Administration Console Online Help).
  2. In the left pane of the console, expand Environment and select Servers.
  3. On the Summary of Servers page, click the server on which you want to enable or disable debugging to open the settings page for that server.
  4. Click Debug.
  5. Expand weblogic.
  6. Expand security.
  7. Enable SAML debugging as follows:
    • To enable the SAML 1.1 debug scope, which encompasses all the SAML 1.1 attributes, select saml, then click Enable.

    • To enable one or more individual SAML 1.1 debug attributes, expand saml, expand the scope of the desired attribute, select the desired individual SAML 1.1 attribute, then click Enable. For example, expand saml, expand atn, and select the DebugSecuritySAMLAtn attribute to debug SAML 1.0 authentication processing.

    • To enable the SAML 2.0 debug scope, which encompasses all the SAML 2.0 attributes, select saml2, then click Enable.

    • To enable one or more individual SAML 2.0 debug attributes, expand saml2, expand the scope of the desired attribute, select the desired individual SAML 2.0 attribute, then click Enable. For example, expand saml2, expand credmap, and select the DebugSecuritySAML2Credmap attribute to debug SAML 2.0 credential mapping provider processing.

    For a description of each registered SAML debug attribute, see About SAML Debug Scopes and Attributes.

  8. To activate these changes, in the Change Center of the WebLogic Server Administration Console, click Activate Changes (see Use the Change Center in the Oracle WebLogic Server Administration Console Online Help).

Changes to SAML debug scopes and attributes take effect immediately — no restart is necessary. See Define debug settings in the Oracle WebLogic Server Administration Console Online Help.

Enabling Debugging Using the WebLogic Scripting Tool

You can use the WebLogic Scripting Tool (WLST) to configure SAML debugging attributes. Using WLST is a dynamic method and can be used to enable debugging while the server is running.

For example, the following command runs a program for setting debugging attributes called debug.py:

java weblogic.WLST debug.py

The debug.py program contains the following code, which enables debugging for the attribute DebugSecuritySAMLAtn.

user='user1'
password='password'
url='t3://localhost:7001'
connect(user, password, url)
edit()
cd('Servers/myserver/ServerDebug/myserver')
startEdit()
set('DebugSecuritySAMLAtn','true')
save()
activate()

Note:

For clarity, this WLST example script shows the username and password in clear text. However, you should avoid entering clear-text passwords in WLST commands in general, and you should especially avoid saving on disk WLST scripts that include clear-text passwords. In these instances you should use a mechanism for passing encrypted passwords instead. See Security for WLST in Understanding the WebLogic Scripting Tool.

Note that you can also use WLST from Java. The following example shows the source file of a Java program that sets the DebugSecuritySAMLAtn debugging attribute:

import weblogic.management.scripting.utils.WLSTInterpreter;
import java.io.*;
import weblogic.jndi.Environment;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;

public class test {
        public static void main(String args[]) {
       try {
              WLSTInterpreter interpreter = null;
              String user="user1";
              String pass="pw12ab";
              String url ="t3://localhost:7001";
              Environment env = new Environment();
              env.setProviderUrl(url);
              env.setSecurityPrincipal(user);
              env.setSecurityCredentials(pass);
              Context ctx = env.getInitialContext();

              interpreter = new WLSTInterpreter();
              interpreter.exec
                     ("connect('"+user+"','"+pass+"','"+url+"')");
              interpreter.exec("edit()");
              interpreter.exec("startEdit()");
              interpreter.exec
                     ("cd('Servers/myserver/ServerDebug/myserver')");
              interpreter.exec("set('DebugSecuritySAMLAtn','true')");       
              interpreter.exec("save()");
              interpreter.exec("activate()");

       } catch (Exception e) {
       System.out.println("Exception "+e);
       }
       }
}

Sending Debug Messages to Standard Out

Messages corresponding to enabled debug attributes are sent to the server log file. Optionally, you can also send debug messages to standard out by passing the StdoutSeverity=Debug attribute on the LogMBean in the command to start WebLogic Server.

For example, -Dweblogic.log.StdoutSeverity=Debug. See Message Output and Logging in Command Reference for Oracle WebLogic Server.