sp_nuclei_test

nuclei templates for testing SAML service providers.

Background

The goal of these templates is to test SAML authentication between a SP (the target) and a conformance IdP (see below).

There are two ways to start the authentication:

1. IdP-initiated, starts by redirecting to an endpoint of the conformance IdP
2. SP-initiated (the most common), which usually starts at the SP by clicking a "login" button, accessing a protected page etc.

The IdP-initiated login is easier to automate, because the endpoint is known, but this produces unsolicited authentication responses, which some SPs might reject.

SP-initiated login can have many forms, but some of them are more or less standardized:

Service Provider Request Initiation Protocol

Service Provider Request Initiation Protocol can be used to start login with a specific IdP (it is as easy as with IdP-initiated login)

there are about 50 universally looking paths to this endpoint in eduGAIN, most of them are Shibboleth SPs (SimpleSAMLphp does not have this, neither does SATOSA; Keycloak embeds a realm in the URLs so they cannot be guessed)

Discovery response endpoint

Identity Provider Discovery Service response endpoint can be used to pretend that a user has selected a specific IdP (unsolicited message to this endpoint), that should also trigger an SP-initiated login.

there are about 90 universally looking paths to this endpoint in eduGAIN - Shibboleth SPs, SimpleSAMLphp, SATOSA and more

SP-specific login page/button

If neither of these previously mentioned endpoints are available, we can try to find a login page and click a login button, for example:

• a generic template which will assume that the button is on the home page ("/") and it has the words "log in" or "sign in" on it, and it is a link which will directly select the conformance IdP
  • this can be further extended to be able to bypass well-known discovery services by performing the selection of conformance IdP on the DS (only applicable if the conformance IdP is going to be in the DS)
• a SP-specific template for SP-specific behavior

Requirements

nuclei

You can run nuclei in multiple ways. The most common ones are directly on your machine (using go) or inside a docker container.

go

Install newest version of Go. The version included in your Linux distribution might not be current enough.

Then install nuclei.

You will run nuclei simply by calling nuclei (see below).

docker

Install docker and make sure that you can call docker in your terminal.

You will run nuclei by executing:

docker run --rm -v ./:/app/ projectdiscovery/nuclei # ...

conformance IdP

You need to setup a conformance IdP, with a module developed for SAML signature validation testing.

Then you need to connect SPs to the conformance IdP (exchange metadata), so that regular SAML authentication works.

Usage

Raw HTTP test (fast, no screenshots)

Make a copy of secret-file.example.yaml to secret-file.yaml and put in your authorization token for the conformance IdP.

Run against one target:

nuclei -u ACS_URL_HERE -V "SP_ENTITY_ID=ENTITY_ID_HERE" -secret-file secret-file.yaml \
    -duc -ms -t nuclei-templates/ -nmhe -lna -dka 30 -dt 30 -tags raw

or using docker:

docker run --rm -v ./:/app/ projectdiscovery/nuclei -u ACS_URL_HERE -V "SP_ENTITY_ID=ENTITY_ID_HERE" -secret-file secret-file.yaml \
    -duc -ms -t /app/nuclei-templates/ -nmhe -lna -dka 30 -dt 30 -tags raw

where

• ACS_URL_HERE is the assertion consumer service endpoint URL
• ENTITY_ID_HERE is the entity ID of the SP

It is expected that the SP will return HTTP code 200/302/303 on success and a different HTTP code on failure (e.g. when SAML response is not signed).

Headless browser test (slower, with screenshots)

Run against one target:

nuclei --headless -u ACS_URL_HERE -V "SP_ENTITY_ID=ENTITY_ID_HERE" -V "BEARER_TOKEN=BEARER_TOKEN_HERE" \
    -duc -ms -t nuclei-templates/ -nmhe -lna -dka 30 -dt 30 -tags headless

or using docker:

docker run --rm -v ./:/app/ projectdiscovery/nuclei --headless -u ACS_URL_HERE -V "SP_ENTITY_ID=ENTITY_ID_HERE" \
    -V "BEARER_TOKEN=BEARER_TOKEN_HERE" -V "SCREENSHOTS_DIR=/app/" \
    -duc -ms -t /app/nuclei-templates/ -nmhe -lna -dka 30 -dt 30 -tags headless

where

• ACS_URL_HERE is the assertion consumer service endpoint URL
• ENTITY_ID_HERE is the entity ID of the SP
• BEARER_TOKEN_HERE is your authorization token for the conformance IdP

SP-initiated (workflow)

Peforming SP-initiated login is more difficult than the IdP-initiated login used in previous templates.

You can use the included nuclei workflow to scan a server for available endpoints and perform SP-initiated login if possible:

nuclei -w workflow/saml-sp-workflow.yaml -u https://sp.example.com/ -code -sf secret-file.yaml

where

• https://sp.example.com/ is the address of a (potential) SP server (only the domain is relevant)

Current limitations

• templates are only usable with the conformace IdP
  • testing cannot be run in parallel for the same entity ID
• only HTTP-POST binding is currently supported
• IdP-initiated templates have to be invoked individually for each target (for each entity ID)
• only SPs which accept unsolicited logins (IdP-initiated) or with a Request Initiation endpoint can be tested
• headless browser test behaves differently than raw HTTP test (nuclei limitation)