colabsvc/auth_sloth repository overview

⁠Auth Sloth

⁠Quick Start

⁠Prerequisites

• Docker and docker-compose installed
• Duke service account credentials

Setup Command:

  mkdir -p proxy
  docker run --rm -it \
    -v "$(pwd)/proxy:/srv/config" \
    --user "$(id -u):$(id -g)" \
    colabsvc/auth_sloth \
    bash -lc 'cd /srv && bash setup/setup.sh'

This interactive setup will:

• ✅ Prompt you for Duke service account credentials
• ✅ Guide you through SP registration (Entity ID, ownership, SAML attributes)
• ✅ Generate SSL certificates and keys
• ✅ Register your application with Duke's Shibboleth API
• ✅ Auto-generate ALL configuration files (including Duke's IDP certificate)

⁠Step 2: Configure Your Backend Services

Edit config/proxied_apps.json to point to your backend application:

[
  {
    "host": "http://your-app",
    "port": 8000,
    "path": "/"
  }
]

Optional: Review and customize:

• config/protected_paths.json - Define which paths require authentication
• config/attribute_map.json - Customize SAML attribute mappings

⁠Step 3: Start Auth-Sloth

docker-compose up

Your application is now running at http://localhost:4000 with SAML authentication!

⁠Usage

⁠Getting attributes in your proxied application.

After the IDP saml response has been read by the SP, auth sloth will set headers in the request to your proxied apps based on the key/value pairings in the attribute_map.json file. For Example: if you have a pairing of "cn": "urn:oid:2.5.4.3" you can expect a header of "cn" to be sent over in requests to your proxied application.

⁠Volumes

Auth sloth expects config files to be placed into /srv/config on the container. This can be accomplised through either a volume or your own Dockerfile based off this image.

⁠docker-compose.yml

services:
  proxy:
    image: colabsvc/auth_sloth
    ports: 
      - 4000:4000
    volumes:
      - ./proxy:/srv/config
    environment:
      - PROXY_SECRET=your_secret_here

⁠Environment Variables

• PROXY_SECRET (required) - secret value to compute string hash session

• SINGLE_VALUE_ATTRS - By default, attributes will come in an array as this is how they come from the IDP. Setting this value with return the index 0 value as most attrs will be single value. Use with caution as some attributes can be multi value, such as if you are returning multiple groups. We are looking to update this in future versions.

⁠Config Files

• attribute_map.json - this file is used to create human-readable names from urn paths received in the saml response

{
  "cn":	"urn:oid:2.5.4.3",
  "displayName": "urn:oid:2.16.840.1.113730.3.1.241",
  "duDukeID": "urn:mace:duke.edu:idms:unique-id",
  "duMiddleName1": "urn:mace:duke.edu:idms:middle-name1",
  "eduPersonPrincipalName": "urn:oid:1.3.6.1.4.1.5923.1.1.1.6",
  "eduPersonAffiliation": "urn:oid:1.3.6.1.4.1.5923.1.1.1.1",
  "eduPersonNickname": "urn:oid:1.3.6.1.4.1.5923.1.1.1.2",
  "isMemberOf": "urn:oid:1.3.6.1.4.1.5923.1.5.1.1",
  "eduPersonPrimaryAffiliation": "urn:oid:1.3.6.1.4.1.5923.1.1.1.5",
  "givenName": "urn:oid:2.5.4.42",
  "mail": "urn:oid:0.9.2342.19200300.100.1.3",
  "ou": "urn:oid:2.5.4.11",
  "sn": "urn:oid:2.5.4.4",
  "telephoneNumber": "urn:oid:2.5.4.20",
  "title": "urn:oid:2.5.4.12",
  "uid": "urn:oid:0.9.2342.19200300.100.1.1",
  "dkuID": "urn:mace:duke.edu:idms:dku-id",
  "duDADDEntityId": "urn:mace:duke.edu:idms:dadd:entityid"
}

• idp.crt - certificate of the Identity Provider(IDP)
• protected_paths.json - outlines what paths require SAML authentication. You can optionally provide a grouper group value to require the user to also have certain group membership.

[
  {
    "path": "/only_auth"
  },
  {
    "path": "/TBD", 
    "group": "urn:mace:duke.edu:groups:group-manager:roles:your-group-name-here"
  }
]

• proxied_apps.json - outlines what other services you would like to proxy.

[
  {
      "host": "http://api", 
      "port": 3000, 
      "path": "/api"
  },
  {
    "host": "http://app", 
    "port": 8080, 
    "path": "/"
  }
  
]

• sp_values.json - configures values needed for the Service Provider(SP) to communicate with the Identity Provider(IDP)

{
    "ENTITYID": "http://my-entity-id",
    "SSO_LOGIN_URL": "https://shib.oit.duke.edu/idp/profile/SAML2/Unsolicited/SSO?providerId=http://my-entity-id",
    "SSO_LOGOUT_URL": "https://shib.oit.duke.edu/cgi-bin/logout.pl",
    "NOT_BEFORE": "2",
    "ACS": "http://localhost:3000/saml/consume"
}

• sp.crt - certificate for the Service Provider(SP)
• sp.key - private key for the Service Provider(SP)