saml.md

SAML

To authenticate with SAML rather than the basic auth:

1. Create the Identity Server image. Options:

   • Build from scratch
   • Download the existing image (GSA only)

     1. Download the image

     2. Unarchive and load the image.

        gunzip wso2-image.tar.gz
        docker load -i wso2-image.tar

2. Start the Identity Server.

   make identity

3. Set up SAML Provider.

   1. Visit WSO2 console.
   2. Click through the certificate warning in your browser.
   3. Log in with username and password of admin.
   4. Add a Service Provider with the Name localhost.
   5. Go into the Inbound Authentication Configuration->SAML2 Web SSO Configuration section, then click Configure.
   6. Fill out the form.
      • Issuer: localhost
      • Assertion Consumer URLs: http://localhost:3000/auth/saml/callback, then click Add
      • Uncheck everything but Enable Response Signing
      • Check Enable Single Logout, no need to set SLO request or response URLs

4. Copy the certificate.

   1. Go to Identity Providers->Resident.

   2. Expand Inbound Authentication Configuration, then SAML2 Web SSO Configuration.

   3. Click Download SAML Metadata.

   4. Open up the resulting SAML Metadata XML file that gets downloaded, and copy the contents of the <X509Certificate> element.

   5. Save that in api/wso2.crt.

      -----BEGIN CERTIFICATE-----
      <contents>
      -----END CERTIFICATE-----
      

5. Enable SAML on the "client" side.

   1. Make sure your .env has the SAML_* defaults from .env.example.
   2. In your .env, set BASIC_ENABLED= and SAML_ENABLED=1.

6. In another terminal, start the server (or restart, if already running).

   make run

7. Visit http://localhost:8080.

8. Log in with PIV/CAC, with username and password of admin.

Caveats

Note this is using an off-the shelf WSO2 server, which won't match production in that:

• It's not hardened
• Using an embedded database rather than an external one
  • NOTE: If you delete the SAML server container the SAML Provider data will be lost along with the embedded database
• The WSO2 verison may not match
• etc.