IAM appliance - cas-docker

Image built atop BCV’s Tomcat image with Apache Tomcat 9.0.x version. You can find our Tomcat Docker image here. This image is referenced as a "baseimage" throughout this text.

Image versioning

This image is versioned by CAS version. The underlying Tomcat version is not mentioned since CAS is distributed as a whole application stack.

Naming scheme is pretty simple: bcv-cas:CAS_BCV_RELEASE-rIMAGE_VERSION.

  • Image name is bcv-cas.

  • CAS_BCV_RELEASE is a version of CAS released by BCV. The versioning of this is CAS_VERSION.BCV_RELEASE.

  • IMAGE_VERSION is an image release version written as a serial number, starting at 0. When images have the same CAS versions but different image versions it means there were some changes in the image itself (setup scripts, etc.) but application itself did not change.

Example

bcv-cas:6.2.8.0-r0    // first release of the first CAS BCV RELEASE with CAS version 6.2.8
bcv-cas:6.2.8.1-r2    // third release of the second CAS BCV RELEASE with CAS version 6.2.8
bcv-cas:6.3.0.0-r0    // first release of the first CAS BCV RELEASE with CAS version 6.3.0
bcv-cas:latest      // nightly build

Building

To build a new CAS image, put the application WAR archive into dropin/cas-$CAS_VERSION.war Then cd to the directory which contains the Dockerfile and issue docker build --no-cache -t <image tag here> ./. To make sure your WAR archive contains the correct version, you have to open it and navigate to /WEB-INF/lib/ and find cas-server-core-<your version>.jar

The build process:

  1. Pulls bcv-tomcat:some-version image.

  2. Installs necessary tooling - openssl, xmlstarlet, kerberos tools etc.

  3. Secures Tomcat installation, namely:

    1. Disables shutdown port.

    2. Disables directory listings.

    3. Removes all Tomcat management apps.

  4. Copies cas.war with given application version into the container. If you need other version of the app, you have to build a new image.

  5. Copies additional runscripts into the container. Those runscripts generate CAS configuration. For explanation of runscripts, see Tomcat baseimage documentation.

  6. Creates CAS configuration directory structure /etc/cas/…​.

Use

Image contains some defaults.

  • STDOUT/STDERR logging, logs available with docker logs CONTAINER.

  • Xms512M

  • Xmx1024M

After it is started up, you can navigate to http://yourserver:8080/cas. CAS itself is a bare application and needs to be connected with other applications to do anything useful.

Minimal mandatory parameters for deployments

Those parameters have no defaults and when left unset, CAS will not start at all.

  • CAS_SERVER_NAME - The hostname of the CAS server, e. g., https://company.com (without slash at the end), property cas.server.name in cas.properties. Default: not set.

  • CAS_SERVER_SCOPE - Scope of the access manager. Used, for example, for SAML metadata scope. In the form of a domain name, e.g. example.com. Default: not set

  • CAS_SERVER_PREFIX - The actual link at which CAS is available, e. g., https://company.com/cas (property cas.server.prefix in cas.properties). Default: $CAS_SERVER_NAME/cas.

Container startup and hooks

Container start leverages existing hooks infrastructure as provided by the Tomcat baseimage - run.sh, runOnce.sh, runEvery.sh, startTomcat.sh and their respective .d/ directories. For more information about runscripts structure, see Tomcat baseimage doc.

CAS image adds its own scripts there:

  • runEvery.d/001_000-generateTruststore.sh - This script was superseded by similar baseimage functionality.

  • runEvery.d/001_001-createCASAppconfig.sh - Creates the cas.properties file which defines CAS behavior.

  • runEvery.d/001_002-appendCASAppconfig.sh - Appends externally-provided property file fragments.

  • runEvery.d/001_003-copySPNEGOFiles.sh - Copies the SPNEGO files (config and keytab).

  • runEvery.d/001_004-fixupMountedDirsPrivs.sh - Fixes privileges on some directories that might have been mounted from outside.

Container shutdown

See Tomcat baseimage doc. CAS is very swift when shutting down, the default STOP_TIMEOUT should be more than enough.

Environment variables

You can pass a number of environment variables into the container. All Tomcat baseimage environment variables are supported - see the baseimage doc. Apart from that, CAS configuration is set based on these environment variables.

If you need more to set more properties that defined here, they must be added to relevant scripts. A quick workaround is to mount the cas.properties file to /etc/cas/config/cas.properties.

  • CAS_SERVER_NAME - The hostname of the CAS server, e. g., https://company.com, property cas.server.name in cas.properties. Default: not set.

  • CAS_SERVER_SCOPE - Scope of the access manager. Used, for example, for SAML metadata scope. In the form of a domain name, e.g. example.com. Default: not set

  • CAS_SERVER_PREFIX - The actual link at which CAS is available, e. g., https://company.com/cas (property cas.server.prefix in cas.properties). Default: not set → $CAS_SERVER_NAME/cas.

  • CAS_SERVICES_REGISTRY_JSON_LOCATION - The location of the JSON services definitions, property cas.service-registry.json.location in cas.properties. Default: /conf/cas/services.

  • CAS_LOGGING_LEVEL - The global logging level for CAS, use either INFO or DEBUG, property logging.level.org.apereo.cas in cas.properties. Only use DEBUG temporarily, after you solve your problem, set the value back to INFO. Default: 'INFO'.

LDAP configuration

LDAP is used as the source of data about users by CAS. By default, all properties related to it are not set (commented out) because CAS will not start if LDAP is defined but unavailable.

  • CAS_LDAP_0_ID - The ID of this LDAP attribute repository, property in cas.properties cas.authn.attribute-repository.ldap[0].id. You can specify this name in the service registration file if you want to load principal’s attributes from a particular attribute repository. Default: not set.

  • CAS_LDAP_0_TYPE - The type of LDAP connection, property in cas.properties cas.authn.ldap[0].type. Recommended setting AUTHENTICATED. Default: not set.

  • CAS_LDAP_0_LDAP_URL - The LDAP URI in format: ldap://openldap:389, property in cas.properties cas.authn.ldap[0].ldap-url=. Default: not set.

  • CAS_LDAP_0_SUBTREE_SEARCH - Set whether subtree search should be used, set to true, property in cas.properties cas.authn.ldap[0].subtree-search. Default: not set.

  • CAS_LDAP_0_BASE_DN - The starting point of search, property in cas.properties cas.authn.ldap[0].base-dn. Default: not set.

  • CAS_LDAP_0_SEARCH_FILTER - Define the search filter, property in cas.properties cas.authn.ldap[0].search-filter. Default: not set.

  • CAS_LDAP_0_BIND_DN - The DN of the user CAS uses to read LDAP, property in cas.properties cas.authn.ldap[0].bind-dn. Default: not set.

  • CAS_LDAP_0_BIND_CREDENTIAL_PASSFILE - The name of the file containing the password for the user account defined above, property in cas.properties cas.authn.ldap[0].bind-credential. Use ldap.pwfile and mount this file. Default: 'not set'.

  • CAS_LDAP_0_PRINCIPAL_ATTR_LIST - List of principal attributes in LDAP directory. Format is the same as for the CAS property cas.authn.ldap[0].principal-attribute-list. Attributes are comma-separated, without spaces. You can remap attribute name by using datasourceName:casName syntax. Default: empty.

Ticket granting ticket and Service ticket behavior configuration

  • CAS_TGT_IDLE_TIMEOUT - Set the ticket granting ticket idle timeout in seconds (ticket’s validity will be extended if used), property in cas.properties cas.ticket.tgt.timeout.max-time-to-live-in-seconds. Default: 28800 (8 hours).

  • CAS_TGT_HARD_TIMEOUT - Set the ticket granting ticket hard timeout in seconds (ticket will be expired after this time), property in cas.properties cas.ticket.tgt.hard-timeout.time-to-kill-in-seconds. Default: 43200 (12 hours).

  • CAS_TICKET_NUMBER_OF_USES - Set the default service ticket expiration policy (how many times a ticket can be used before becoming invalid), property in cas.properties cas.ticket.st.number-of-uses. Default: 25.

  • CAS_ST_HARD_TIMEOUT - Set the default service ticket expiration timeout in seconds, property in cas.properties cas.ticket.st.time-to-kill-in-seconds. Default: 900 (15 minutes).

  • CAS_LOGOUT_FOLLOW_SERVICE_REDIRECTS - Allow logout redirects defined in services, property in cas.properties cas.logout.follow-service-redirects. Default: true.

Custom frontend changes

  • CAS_CUSTOM_FRONTEND - Name of the custom CAS theme to be used as default. If not set, the container will use default CAS theme. Property in cas.properties cas.theme.default-theme-name=. Default: not set.

  • CAS_CUSTOM_FRONTEND_FOOTER_DISPLAY - Set whether a footer should appear at the bottow of the page, property in cas.properties cas.custom.properties.frontend.footer.display. Default: false.

  • CAS_CUSTOM_FRONTEND_FOOTER_LINK - Set the URL of the link shown in the footer, property in cas.properties cas.custom.properties.frontend.footer.link.href. Default: https://www.idstory.com.

  • CAS_CUSTOM_FRONTEND_LOGO_LINK - Set the URL of the logo, property in cas.properties cas.custom.properties.frontend.logo.link. Default: https://www.idstory.com.

  • CAS_CUSTOM_FRONTEND_PASSWORDRESET_DISPLAY - Set whether password reset link will appear bellow login form, property in cas.properties cas.custom.properties.frontend.password-reset.display. Default: false.

  • CAS_CUSTOM_FRONTEND_PASSWORDRESET_LINK - Set relative(/link), domain relative (~/link) or full url(with http) link cas.custom.properties.frontend.password-reset.link. Default: not set. If value is not set, there will be fallback for default value in CAS template, server.url/passwordForgot

  • CAS_CUSTOM_FRONTEND_NEWACCOUNT_DISPLAY - Set whether sign-up link will appear bellow login form, property in cas.properties cas.custom.properties.frontend.new-account.display. Default: false.

  • CAS_CUSTOM_FRONTEND_NEWACCOUNT_LINK - Set relative(/link), domain relative (~/link) or full url(with http) link cas.custom.properties.frontend.new-account.link. Default: not set. If value is not set, there will be fallback for default value in CAS template, server.url/newAccount

Enable the custom frontend with an environment variable (see above) and then replace the cas.css and header-logo.png files.

SPNEGO authentication

  • CAS_SPNEGO_ENABLED - Set SPNEGO should be enabled. This will set some static properties necessary for SPNEGO to work. Default: false.

  • CAS_KERBEROS_REALM - Set the Kerberos realm, property in cas.properties cas.authn.spnego.system.kerberos-realm. Default: not set.

  • CAS_KERBEROS_DEBUG - Enable Kerberos debug mode, property in cas.properties cas.authn.spnego.system.kerberos-debug. Default: false.

  • CAS_KERBEROS_KDC - Set the Kerberos KDC URL, property in cas.properties cas.authn.spnego.system.kerberos-kdc. Multiple KDCs can be set, separate them by a single space ' '.Default: not set.

  • CAS_KERBEROS_SERVICE_PRINCIPAL - Set the Kerberos service principal name, property in cas.properties cas.authn.spnego.properties[0].jcifs-service-principal. Default: not set.

SAML2 IdP

  • CAS_SAML_IDP_ENTITYID - EntityID of the IdP in SAML metadata. Default: $CAS_SERVER_PREFIX/idp

  • CAS_SAML_IDP_ATTRQUERY - If set (even if empty), enables SAML AttributeQueryProfile. Default: disabled

OAuth2/OIDC IdP

  • CAS_OIDC_IDP_ISSUER - Identity of the issuing party in the OIDC. Default: $CAS_SERVER_PREFIX/oidc

Google Authenticator / OTP 2FA

  • CAS_MFA_GAUTH_ISSUER - Issuer name for the OTP token. Default: IAM CAS

  • CAS_MFA_GAUTH_LABEL - Label of the OTP token. Default: OTP

Mounted files and volumes

  • Optional

    • CAS configuration file

      • This file contains all configuration of CAS. You can use it this way if you turn off container autoconfiguration by specifying DOCKER_SKIP_CAS_CONFIGURATION environment variable. This is not recomended, though.

      • Example

        volumes:
  - type: bind
    source: ./cas.properties
    target: /etc/cas/config/cas.properties
    read_only: true

    • CAS configuration .d/ directory

      • This is a .d/ directory similar to Linux .d/ directories. All files in this directory which name ends with .properties will be appended to final cas.properties configuration file. This is preferred before replacing cas.properties file as a whole.

      • Example

        volumes:
  - type: bind
    source: ./cas.properties.d
    target: /casstart/cas.properties.d
    read_only: true

    • Custom message catalogs directory

      • This directory contains user-supplied localization strings in custom_messages_xx.properties file where xx is a language specifier. File custom_messages.properties is consulted when no language-specific string is found. If you place a message string into these files, it will override default bundled message string.

      • Example

        volumes:
  - type: bind
    source: ./msgcat
    target: /etc/cas/msgcat
    read_only: true

    • Trusted certificates directory

      • See 000_002-generateJavaTruststore.sh script documentation in the baseimage doc.

      • Without this directory mounted, CAS will not trust any SSL certificates. This effectively prevents CAS to securely connect to other systems. Nowadays, it is simply dangerous to run all communication in plaintext, so populating and mounting this directory is highly recommended.

      • Example

        volumes:
  - type: bind
    source: ./certs
    target: /opt/tomcat/truststore/certs
    read_only: true

    • CAS services

      • CAS uses JSON files as sources for definitions of services which are configured to use CAS as an identity provider. The files should be in this folder. This is a shared volume because it can be populated by CAS Management.

      • Example

        volumes:
  - type: bind
    source: ./services
    target: /conf/cas/services
    read_only: true

    • SPNEGO configuration files and the keytab

      • If you want to use SPNEGO authentication (SSO with MS AD), you need to supply a folder which contains the generated keytab file file.keytab, the krb5.conf file and the login.conf file.

      • Example

        volumes:
  - type: bind
    source: ./spnego
    target: /casstart/spnego
    read_only: true

    • SAML metadata directory

      • If you want to use CAS as SAML IdP, you need to supply a folder where CAS stores its IdP metadata and keys. CAS must be able to write files there.

      • Example

        volumes:
  - type: bind
    source: ./saml
    target: /etc/cas/saml
    read_only: false

    • Debug directory

      • Debug information written by various tools can be stored here. Java debug tools can dump CAS-related thing directly into this directory.

      • Example

        volumes:
  - type: bind
    source: ./debug
    target: /opt/debug
    read_only: false

    • Scripts directory

      • Sometimes you need to give some customized Groovy scripts to CAS. This is the way.

      • Example

        volumes:
  - type: bind
    source: ./scripts
    target: /opt/scripts
    read_only: true

Forbidden variables

The same variables as for Tomcat baseimage.

Hacking away

See Tomcat baseimage doc.