README.md

# SAML IdP Probe

Probe a SAML IdP deployment

## Installation

Download the dependent [Bash Library](https://github.internet2.edu/InCommon/bash-library) source, change directory to the source directory, and install the source into ``/tmp`` as follows:

```Shell
$ export BIN_DIR=/tmp/bin
$ export LIB_DIR=/tmp/lib
$ ./install.sh $BIN_DIR $LIB_DIR
```

or install into your home directory:

```Shell
$ export BIN_DIR=$HOME/bin
$ export LIB_DIR=$HOME/lib
$ ./install.sh $BIN_DIR $LIB_DIR
```

A target directory will be created if one doesn't already exist. The following files will be installed:

```Shell
$ ls -1 $BIN_DIR
cget.sh

$ ls -1 $LIB_DIR 
compatible_date.sh
config_tools.sh
core_lib.sh
entity_endpoints_txt.xsl
entity_identifiers_txt.xsl
entity_idp_names_txt.xsl
extract_entity.xsl
http_tools.sh
md_tools.sh
saml_tools.sh
```

Next download the SAML IdP Probe project source, change directory to the source directory, and install the source on top of the previous installation:

```Shell
$ ./install.sh $BIN_DIR $LIB_DIR
```

Altogether the following files will be installed:

```Shell
$ ls -1 $BIN_DIR
cget.sh
check_idp_error_urls.sh
list_local_idp_error_urls.sh
list_local_saml_idp_endpoints.sh
probe_saml_idp.sh
probe_saml_idps.sh

$ ls -1 $LIB_DIR 
command_paths.sh
compatible_date.sh
compatible_mktemp.sh
config_tools.sh
entity_endpoints_txt.xsl
entity_identifiers_txt.xsl
entity_idp_names_txt.xsl
extract_IdP_entityIDs.xsl
extract_InCommon_IdP_entityIDs.xsl
extract_entity.xsl
http_tools.sh
md_tools.sh
saml_tools.sh
```

## Overview

### ``probe_saml_idp.sh``

Given a single IdP entityID, the ``probe_saml_idp.sh`` script probes all browser-facing SSO endpoints in IdP metadata.

```Shell
$ id=https://idp.incommonfederation.org/idp/shibboleth
$ $BIN_DIR/probe_saml_idp.sh $id
0 redirects:2;response:200;dns:0.000;tcp:0.038;ssl:0.086;total:1.016 https://idp.incommonfederation.org/idp/profile/SAML2/Redirect/SSO urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect https://idp.incommonfederation.org/idp/shibboleth https://incommon.org
0 redirects:2;response:200;dns:0.000;tcp:0.038;ssl:0.088;total:0.737 https://idp.incommonfederation.org/idp/profile/SAML2/POST/SSO urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST https://idp.incommonfederation.org/idp/shibboleth https://incommon.org
WARNING: get_sso_endpoint: entity has no SSO endpoint that supports the HTTP-POST-SimpleSign binding: https://idp.incommonfederation.org/idp/shibboleth
0 redirects:2;response:200;dns:0.000;tcp:0.038;ssl:0.088;total:0.735 https://idp.incommonfederation.org/idp/profile/Shibboleth/SSO urn:mace:shibboleth:1.0:profiles:AuthnRequest https://idp.incommonfederation.org/idp/shibboleth https://incommon.org
```

By default, the script probes **all** browser-facing endpoints, including SAML1 endpoints. Use the ``-b`` option to probe a single endpoint with a particular binding.

See the inline help file for details:

```Shell
$ $BIN_DIR/probe_saml_idp.sh -h
```

### ``probe_saml_idps.sh``

Given a list of IdP entityIDs, the ``probe_saml_idps.sh`` script probes one or more browser-facing SSO endpoints in each IdP entity descriptor.

```Shell
$ $BIN_DIR/probe_saml_idps.sh -t 6 <<ENTITY_IDs
urn:mace:incommon:internet2.edu
https://login.ligo.org/idp/shibboleth
https://idp.ncsa.illinois.edu/idp/shibboleth
ENTITY_IDs
0 redirects:3;response:200;dns:0.070;tcp:0.107;ssl:0.303;total:0.833 https://origin.internet2.edu/idp/profile/SAML2/Redirect/SSO urn:mace:incommon:internet2.edu
0 redirects:1;response:200;dns:0.000;tcp:0.000;ssl:0.000;total:0.797 https://login.ligo.org/idp/profile/SAML2/Redirect/SSO https://login.ligo.org/idp/shibboleth
0 redirects:1;response:200;dns:0.000;tcp:0.038;ssl:0.093;total:1.075 https://idp.ncsa.illinois.edu/idp/profile/SAML2/Redirect/SSO https://idp.ncsa.illinois.edu/idp/shibboleth
```

By default, the script probes one endpoint per IdP, namely, the SAML2 HTTP-Redirect endpoint. By specifying an option on the command line, up to four (4) endpoints per IdP may be probed.

See the inline help file for details:

```Shell
$ $BIN_DIR/probe_saml_idps.sh -h
```

### ``check_idp_error_urls.sh``

Given a list of entityIDs and a metadata source, bash script ``check_idp_error_urls.sh`` probes each entity and determines which of the entityIDs correspond to SAML IdP deployments. For each such deployment, the script determines whether it has an ``errorURL`` in metadata and whether or not that URL is resolvable. For example:

```Shell
# Fetch the main production metadata aggregate at md.incommon.org:
$ MD_LOCATION=http://md.incommon.org/InCommon/InCommon-metadata.xml
$ MD_PATH=$MD_DIR/InCommon-metadata.xml
$ /usr/bin/curl --silent $MD_LOCATION > $MD_PATH

# Probe every errorURL in IdP metadata registered by InCommon
$ /bin/cat $MD_PATH \
  | /usr/bin/xsltproc $LIB_DIR/extract_InCommon_IdP_entityIDs.xsl - \
  | $BIN_DIR/check_idp_error_urls.sh -f $MD_PATH
```

See the inline help file for details:

```Shell
$ $BIN_DIR/check_idp_error_urls.sh -h
```

## Compatibility

The bash scripts are compatible with both GNU/Linux and Mac OS. The XSLT scripts are written in XSLT 1.0.

## Dependencies

* [Bash Library](https://github.internet2.edu/InCommon/bash-library)