gunet/simple-cas repository overview

A simple SSO CAS container based on the Apereo CAS⁠ server

Part of the GUNet simpleidentity suite (includes a CAS SSO server and several SSO protocol testers)

Expects a gunet/simple-ldap⁠ container for the user database.

Configuration is in /etc/cas, including /etc/cas/cas.properties (with dynamic environment variables), /etc/cas/services for JSON based services definitions

Listen port: 8443

Features:

• LDAP user repository (for authentication and attribute retrieval)
• SAML IdP
• oAuth/OIDC provider
• failure throttling
• REST protocol
• GAuth
• Discovery Profile
• Actuator monitor endpoints
• User Account

Configured service definitions:

• A CAS protocol service definition for a general purpose serviceId of ^http(|s)://.*. Returned attributes will include cn, sn, displayName, uid, mobile
• A SAML protocol service definition for a general purpose serviceId of ^http(|s)://.*. The metadataLocation points to a dynamically expanded (on startup by the docker entrypoint) value including the SAML_SP environment variable for the gunet/simple-saml-sp based on simpleSAMLPHP (${SAML_SP}/simplesaml/module.php/saml/sp/metadata.php/default-sp)

Main endpoints:

• /cas/login: Login using the CAS protocol
• /cas/idp/metadata: SAML2 metadata
• /cas/idp: SAML endpoints⁠
• /cas/oidc/.well-known/openid-configuration: OIDC metadata
• /cas/oidc: OIDC endpoints⁠
• REST protocol reference⁠
  • Simple REST user authentication: curl -k https://localhost:8443/cas/v1/users -d "username=test&password=test"
• /cas/actuator/discoveryProfile: Discovery Profile
• /cas/account: User account (after login)

Returned attributes (CAS protocol):

• cn
• sn
• displayName
• mobile
• uid
• eduPersonEntitlement

Certificate:

• The certificate keystore is in /etc/cas/thekeystore while the actual certificate is also in /etc/cas/server.crt
• The certificate is issued for localhost and includes a subjectAltName of host.docker.internal. This can be used to access the /cas/serviceValidate endpoint through another container by including the relevant host (example for Docker compose stack):

    extra_hosts:
      - "host.docker.internal:host-gateway"

Actuators:

• /cas/actuator: List of available actuators
• /cas/actuator/status: General status
• /car/actuator/casFeatures: List of enabled features
• /cas/actuator/ssoSessions: SSO sessions stats/list
• /cas/actuator/registeredServices: List of registered services
• /cas/actuator/metrics/${metricName}: Various metrics. Accessing the root will return available metrics to query. For instance:
  • /cas/actuator/metrics/disk.total
  • /cas/actuator/metrics/disk.free
• /cas/actuator/statistics: Statistics
• /cas/actuator/resolveAttributes/${uid}: Return resolved user attributes
• /cas/actuator/multifactorTrustedDevices/{username}: Registered MultiFactor devices
• /cas/actuator/authenticationHandlers: Authentication handlers

A prometheus actuator is available at /car/actuator/prometheus

• GAuth
  • The user must perform a web authentication in order to register a new device by scanning the QR code and pressing CONFIG on the web interface. This can be done by passing a parameter authn_method=mfa-gauth in the login page (https://localhost:8443/cas/login?authn_method=mfa-gauth)
  • One can use the REST protocol to perform an authentication using an MFA token along with the username/password pair like: curl -sLk https://localhost:8443/cas/v1/users -d "username=auser&password=auser&gauthotp=229565". The CAS server response will include an attribute authnContextClass=mfa-gauth

Main configuration environment attributes:

• CAS_SERVER_NAME which is used to setup the cas.server.name cas property. Default value: https://localhost:8443
• The general cas.server.prefix will be equal to ${CAS_SERVER_NAME}/cas. All other relevant endpoints will be below this prefix
• LDAP_URL which sets the LDAP URL to use. We expect the gunet/simple-ldap container with its data structure and admin username/password. Default value: ldap://ldap:1389
• SAML_SP_METADATA for the gunet/simple-saml-sp tester container metadata location already setup in the SAML service definition. Default value: http://host.docker.internal:8080/simplesaml/module.php/saml/sp/metadata.php/default-sp

How to include in docker-compose.yaml (the gunet/simple-ldap needs to be included in the stack with a service name of ldap):

  sso:
    image: gunet/simple-cas
    depends_on:
      - ldap
    restart: unless-stopped
    ports:
      - ${CAS_PORT:-8443}:8443
    environment:
      - TZ=Europe/Athens
      - LDAP_URL=ldap://ldap:1389
      - CAS_SERVER_NAME=${CAS_SERVER_NAME:-https://localhost:8443}
      - SAML_SP_METADATA=${SAML_SP_METADATA:-http://host.docker.internal:8080}
    extra_hosts:
      - "host.docker.internal:host-gateway"