Getting Started with ShibbDebugger

https://www.shibbdebugger.org

This guide explains how to select a command, submit the appropriate input, and interpret the results.

Requirements

You need:

• A modern web browser
• An internet connection
• Access to the relevant metadata or configuration file for file-based commands
• A metadata URL for remote retrieval
• Appropriate authorization to inspect the supplied configuration

No local installation of Shibboleth is required to use the web interface.

Step 1: Choose a Diagnostic Command

Open ShibbDebugger and locate the Choose a diagnostic command selector.

Commands are organized into three categories:

SP Tests

• Lint Configuration File
• Lint Attribute Map File
• Check XML Discovery

IdP Tests

• Grab Metadata from URL
• Parse Metadata File
• Check SAML Bindings
• Check NameID Formats
• Check Certificate Expiration
• Check XML Signature

Client Tests

• Check For Client Clock Skew

The command labels reflect the application's interface grouping.

Some metadata commands can also be useful for inspecting SP metadata when it has the XML structure expected by the command.

Step 2: Supply the Required Input

ShibbDebugger automatically enables the relevant input field.

File-Based Commands

Select the XML file using Upload XML File.

The browser disables the URL field while a file-based command is selected.

URL-Based Commands

Enter the metadata URL into Metadata URL.

Example:

https://idp.example.org/

The file upload field is disabled for URL-based commands.

No-Input Commands

Clock synchronization requires no uploaded file or URL.

Step 3: Execute the Command

Click Execute Command.

The interface integrates ZapCaptcha verification before normal form submission.

After submission, ShibbDebugger validates the selected command's required input and executes its corresponding server-side diagnostic.

Step 4: Review the Result

The application returns a diagnostic report through its results page.

Depending on the command, the report can contain:

• Successful checks
• Missing elements
• Warnings
• Extracted configuration values
• Certificate details
• Error messages
• Network lookup results

Example Output

Result of: ConfigLintCommand

General SP XML structure checks : ✓ valid

ApplicationDefaults : ✓ block found
Sessions : ✓ block found
SSO : ✓ block found

This is a shortened illustrative example.

Understanding Status Indicators

The commands use several output indicators.

These indicators reflect command-specific rules.

They do not establish overall SAML compliance or deployment security.

File Upload Limits

ShibbDebugger restricts request content length to 5 MiB.

Files larger than the configured limit may be rejected.

For large metadata aggregates, use a smaller individual entity file when appropriate.

Supported XML Inputs

Different commands expect different XML structures.

SAML Metadata

Common root:

<EntityDescriptor
  xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
  entityID="https://idp.example.org/idp/shibboleth">
</EntityDescriptor>

Shibboleth SP Configuration

Typically:

shibboleth2.xml

Attribute Map

Typically:

attribute-map.xml

The exact filename alone does not determine validity. Each command inspects the XML content.

Input Errors

If a command is unknown or its required input is absent, ShibbDebugger returns an error.

Examples:

ERROR: Unknown command.

ERROR: Invalid input or missing file/URL.

Processing Considerations

File-based diagnostic operations are performed on the application server after upload.

URL-based retrieval causes the server to contact the specified endpoint.

External time services are contacted during clock synchronization.

Best Practices

1. Use the command appropriate for the XML document.
2. Confirm that the file is not truncated.
3. Preserve original configuration files.
4. Review warnings in the context of your deployment.
5. Avoid uploading unnecessary confidential information.
6. Verify changes in a staging environment before production.

Next Steps

Continue to SAML Metadata Retrieval and Parsing for details on working with identity provider metadata.