gosaml2 Documentation

To extend the fuzzing coverage of gosaml2, follow these steps:

1. Implement the new fuzzer in the internal/fuzz/ directory.
2. Update the build.sh script to include the new fuzzer in the compilation step and ensure its seed corpus is created.
3. If the fuzzer requires specific arguments or configurations, create a corresponding .options file (e.g., my_new_fuzzer.options).

You can run the built-in fuzzing targets for gosaml2 using Go's native fuzzing capabilities. These targets are located in the ./internal/fuzz/ directory. Use the -fuzz flag to specify the target function and -fuzztime to limit the duration of the fuzzing session.

go test -fuzz=FuzzDecodeResponse ./internal/fuzz/ -fuzztime=30s
go test -fuzz=FuzzLogoutResponse ./internal/fuzz/ -fuzztime=30s
go test -fuzz=FuzzBuildRequest ./internal/fuzz/ -fuzztime=30s

Install gosaml2 into your $GOPATH using the go get command.

go get github.com/russellhaering/gosaml2

You can test the OSS-Fuzz integration for gosaml2 on your local machine using Docker and the OSS-Fuzz infrastructure scripts. This requires cloning the oss-fuzz repository and using its infra/helper.py script to manage the build and execution lifecycle.

# Clone OSS-Fuzz
git clone https://github.com/google/oss-fuzz
cd oss-fuzz

# Build the image
python infra/helper.py build_image gosaml2

# Build the fuzzers
python infra/helper.py build_fuzzers gosaml2

# Run the fuzzers
python infra/helper.py run_fuzzer gosaml2 fuzz_decode_response

When processing SAML responses, the library provides structured data to inspect the assertion:

• AssertionInfo: Contains the NameID, Values (attributes), SessionIndex, AuthnInstant, and the raw Assertions. It also includes ResponseSignatureValidated to confirm if the response was signed.
• WarningInfo: Provides details on potential security or protocol issues found during validation, such as:
  • OneTimeUse: Whether the assertion was intended for single use.
  • ProxyRestriction: Details on whether proxy restrictions were violated.
  • NotInAudience: Whether the assertion was intended for a different audience.
  • InvalidTime: Whether the assertion's time bounds were invalid.

The RequestedAuthnContext struct allows the Service Provider to request specific authentication mechanisms from the Identity Provider.

• Comparison: The comparison policy (e.g., using constants like AuthnPolicyMatchExact).
• Contexts: A slice of strings representing AuthnContextClassRefs. For example, to force password authentication, use []string{AuthnContextPasswordProtectedTransport}.

Note: Leaving this unset allows the IdP to choose the authentication method, which is recommended for maximum compatibility.

sp.RequestedAuthnContext = &saml2.RequestedAuthnContext{
    Comparison: "urn:oasis:names:tc:SAML:2.0:authnmethods-replay:exact",
    Contexts:   []string{"urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"},
}

The library supports two primary SAML bindings:

1. HTTP Redirect Binding: The SAML message is compressed (DEFLATE), Base64 encoded, and appended as a query parameter (SAMLRequest) to the IdP's SSO URL. If sp.SignAuthnRequests is enabled, the library also signs the query string parameters (including SigAlg and Signature) according to the SAML specification.

   • Use BuildAuthURLRedirect or BuildLogoutURLRedirect to generate these URLs.
   • Use AuthRedirect for a direct HTTP redirect.

2. HTTP POST Binding: The SAML message is Base64 encoded and sent within an HTML <form> via an HTTP POST request.

   • Use BuildAuthBodyPost to generate the complete HTML form (including the auto-submitting JavaScript) required for this binding.

The following fuzzing targets are implemented in the internal/fuzz directory to target specific SAML operations and XML processing:

• FuzzDecodeResponse: Fuzzes SAML response decoding and validation.
• FuzzLogoutResponse: Fuzzes SAML logout response decoding.
• FuzzBuildRequest: Fuzzes SAML authentication request building.
• FuzzXMLValidation: Fuzzes XML validation to catch parsing vulnerabilities.

gosaml2 is designed as a generic SAML implementation. The following Identity Providers (IdPs) have been tested and verified to work with the library:

• Okta
• Auth0
• Shibboleth
• Ipsilon
• OneLogin
• Azure Active Directory (Azure AD)

If you have an existing etree.Element representing a SAML request (AuthnRequest or LogoutRequest) and need to sign it, use the SignAuthnRequest or SignLogoutRequest methods.

These methods follow the SAML schema requirement where the <Signature> element is inserted immediately after the <Issuer> element and before all other children.

// Example: Manually signing an element
signedEl, err := sp.SignAuthnRequest(myElement)
if err != nil {
	// handle error
}