The SAML Metadata Configuration Manager (MCM) is built as a Java Spring Boot ( https://spring.io/projects/spring-boot ) application. It can be run as a standalone web application that has Tomcat embedded in it. The same WAR file can be deployed into an external servlet container (standalone Tomcat etc). It can also be deployed using a Docker image. And in the Docker realm, the project also provides a full "testbed environment" that includes a database, an IdP, a LDAP server, etc.

Requirements

Downloads

Configuration Notes

The following are some things that are useful to consider and know regardless of which deployment model you choose to go with.

Much of the behavior of the MCM can be set and controlled through properties files which can be in one or both of the following formats:

The MCM comes with basic examples of both types of properties files.

The example application.properties file includes the core settings for authentication, database connection information, users file, the directory/location settings for where the MCM should write out the metadata files and metadata-providers.xml file it manages, etc.

The example application.yml file contains all the settings that impact the information, options, list elements, etc. that are actually shown in the UI.

There is no reason that you need to keep that distinction; you could manage everything through a single properties or YAML-format file if you wanted. On the other hand, it can be a convenient distinction to keep the core "internal/baked-in settings" distinct from the "front-end/UI" settings. By default, property sources named `application.properties` and `application.yml` will be recognized by Spring Boot and merged at runtime to form a finalized `Environment` object holding all the properties gathered from all the property sources locations. Details on the properties that can/should be configured are detailed later in this document.

Deployment Options

Deployment via Docker

The Docker image of the SAML MCM follows the TIER Docker packaging standards, utilizing CentOS7, the Zulu JDK, supervisor, and the TIER Beacon configuration.

Basic usage:

docker run -p 8080:8080 -v <your local application.properties>:/opt/shibui/application.properties i2incommon/shib-idp-ui


You will want to create a local application.properties file that contains the core application settings you want overriding the defaults that are in the SAML MCM war file. Your file should be mounted at the location /opt/shibui/application.properties. 

The current set of supported properties can be found here.

Note: If you did not set an explicit password in your local application.properties then you will have to look at the startup "console messages" and find the one generated at startup. Look for the line:  Using generated security password:. The username is: user

Deployment via embedded Tomcat mode

The SAML MCM war file includes an embedded Tomcat mode allowing you to run the application without any external dependencies beyond your configuration overrides and database.

The following example shows how you can override the default database and use mariadb instead.  Example application.yml(s) for configuring common RDBMS can be found in the github repository.

shibui:
  default-password: "{noop}pass"
spring:
  datasource:
    platform: mysql
    driver-class-name: org.mariadb.jdbc.Driver
	url: jdbc:mariadb://localhost:3306/shibui
	username: shibui
	password: shibui
  jpa:
    properties:
	  hibernate:
	    dialect: org.hibernate.dialect.MariaDB103Dialect

Note:  You need to list an "encryption scheme" for the default-password which is what the '{noop}' is preceding it.  More info on the encryption scheme can be found here.


Then you will run the war and tell Spring Boot where to find the externalized application.yml.

java -Xmx1g -jar shibui-1.18.0.war --spring.config.additional-location=file:/opt/shibui/

You can then access the application on http://localhost:8080 and login as root with the password you set in application.yml

HTTPS

To use HTTPS with the embedded Tomcat add the following properties to application.yml.  The values are examples and should be replaced.

server:
  ssl:
    key-store: /opt/shibui/keystore.p12
	key-store-password: password
	key-store-type: pkcs12
	key-alias: tomcat
	key-password: password
  port: 8443


Deployment via servlet container (Tomcat, Jetty et al)

The SAML MCM war file can be deployed via Tomcat or Jetty.  The following examples show the minimum configuration needed to deploy under Tomcat 9.

The following example shows how you can use mariadb as the database.  Example application.yml(s) for configuring common RDBMS can be found in the github repository.

shibui: 
  default-password: "{noop}pass"
spring: 
  datasource:
    platform: mysql
    driver-class-name: org.mariadb.jdbc.Driver
    url: jdbc:mariadb://localhost:3306/shibui
    username: shibui
    password: shibui
  jpa:
    properties:
      hibernate:
        dialect: org.hibernate.dialect.MariaDBDialect

Note:  You need to list an "encryption scheme" for the default-password which is what the '{noop}' is preceding it.  More info on the encryption scheme can be found here.


Assuming Tomcat is installed in /opt/tomcat then place the war file into the webapps directory:

curl -o /opt/tomcat/webapps/shibui.war -L https://github.internet2.edu/TIER/shib-idp-ui/releases/download/v$SHIBUI_VERSION/shibui-$SHIBUI_VERSION.war


Place your application.yml and/or application.properties in /opt/shibui and you can access the application at http://<your tomcat host>/shibui


Authentication Options


The MCM currently supports three distinct roles:


One key decision that you will need to make is how to control authentication of users of the SAML MCM. If you use the default user or a users file, note the following on defining passwords:

Currently, the supported values for ENCRYPT_SCHEME are either:

For more info on supported Spring Security's password storage formats, see: https://docs.spring.io/spring-security/site/docs/current/reference/htmlsingle/#pe-dpe-format

Default - Single "root" user

Simple, recommended only for secure environments (private networks available accessible via VPN or local access) with very limited user base (1-2 admin)

By default the SAML MCM will set up a single "root" user with a password it will generate the first time you run it. That password should be displayed in the console log as the MCM starts up – but you probably really don't want to rely on that. If you are going to go with this option, you should set the password for that single "root" user in the configuration file.

application.properties: 

shibui.default-password = {ENCRYPT_SCHEME}password


application.yml:

shibui:
  default-password: "{ENCRYPT_SCHEME}password"


Users Defined via File

Simple, recommended only for secure environments (private networks available accessible via VPN or local access) with limited user base (where users will not share a single login)

Users and their permissions can be set in a CSV formatted file that is loaded by the MCM on start.

The format is:

username,{ENCRYPT_SCHEME}password,firstname,lastname,ROLE_VALUE,email

dummy,{noop}password,first,last,ROLE_DUMMY,dummy@bill.com
admin,{noop}password,admin,admin,ROLE_ADMIN,admin@foo.com
user,{noop}password,some,user,ROLE_USER,user@foo.com


application.properties:

shibui.user-bootstrap-resource = file:/full/path/to/users/file.csv


application.yml:

shibui:
  user-bootstrap-resource: file:/full/path/to/users/file.csv


Users Authenticated via SAML

Recommended when a large volume of users needs to access the SAML MCM or the application will be publicly accessible

The SAML MCM includes a Java SAML SP based on the Pac4j ( https://www.pac4j.org ) library (SAML support built on top of the Shibboleth Consortium's OpenSAML software).

The examples are from the perspective of using the Shibboleth IdP but the SP will work with any SAML compliant IdP.

Even though authentication will happen at the IdP a users file is still required to set at least one ROLE_ADMIN. This admin will then be able to set the roles of other users within the MCM. The password is still a required field in the users file but the value will be ignored.

Setting up the Pac4j SP is similiar to adding any SAML SP.  You will need a copy of the IdP's metadata and you will need to create metadata and certifcates for the SP.  The Pac4j library will generate the needed metadata and certificates during first start or you can generate your own.


application.properties:


shibui.pac4j-enabled = true
shibui.pac4j.keystorePath = /full/path/to/ShibUI/samlKeystore.jks
shibui.pac4j.keystorePassword = whatever_you_want
shibui.pac4j.privateKeyPassword = whatever_you_want
shibui.pac4j.serviceProviderMetadataPath = /full/path/to/ShibUI/sp-metadata.xml
shibui.pac4j.serviceProviderEntityId = http(s)://entityID/url/for/ShibUI
 
# Path to file containing Shibboleth IdP metadata
shibui.pac4j.identityProviderMetadataPath = /full/path/to/ShibIdP/idp-metadata.xml
shibui.pac4j.forceServiceProviderMetadataGeneration = false
shibui.pac4j.callbackUrl = https://localhost:8443/callback         ← Note this depends on the URL at which the ShibUI will be available
 
# Following is the max allowed age of AuthnInstant allowed
# in SAML response sent to Pac4j SP
shibui.pac4j.maximumAuthenticationLifetime = 36000
 
# SAML attribute mapping. Name of the attribute the IdP will
# supply that the UI should use to populate its internal user store.
# As long as it least one Shibboleth IdP username matches up with at least one
# in the supplied users file that has the Admin (ROLE_ADMIN) roel, that person
# can manage the role assignment  of all other users thru the UI directly.
shibui.pac4j.simpleProfileMapping.username = urn:oid:0.9.2342.19200300.100.1.1
shibui.pac4j.simpleProfileMapping.firstname = urn:oid:2.5.4.42
shibui.pac4j.simpleProfileMapping.lastname = urn:oid:2.5.4.4
shibui.pac4j.simpleProfileMapping.email = urn:oid:0.9.2342.19200300.100.1.3



application.yml:  (see application.properties above for comments on the settings)


shibui:
  pac4j-enabled: true
  pac4j:
    keystorePath: /full/path/to/ShibUI/samlKeystore.jks
    keystorePassword: whatever_you_want
    privateKeyPassword: whatever_you_want
    serviceProviderMetadataPath: /full/path/to/ShibUI/sp-metadata.xml
    serviceProviderEntityId: http(s)://entityID/url/for/ShibUI
    identityProviderMetadataPath: /full/path/to/ShibIdP/idp-metadata.xml
    forceServiceProviderMetadataGeneration: true
    callbackUrl: https://localhost:8443/callback
    maximumAuthenticationLifetime: 3600000 
    simpleProfileMapping:
      username: urn:oid:0.9.2342.19200300.100.1.1
      firstname: urn:oid:2.5.4.42
      lastname: urn:oid:2.5.4.4
      email: urn:oid:0.9.2342.19200300.100.1.3



Once you have those settings in place then start up the SAML MCM and try to access the dashboard.  You should be directed to the configured IdP for authentication and it should present an error because you have not yet configured it with metadata and attribute release for the MCM.  This will cause Pac4j to generate the sp-metadata.xml file you will need to configure the IdP side.


Configuration Properties

Database Configuration via application.yaml

This set of examples shows the basic configuration for each of the database types - please adjust server-names/addresses/ports/db-name/dbusers accordingly with your database. Defaults shown below

Support for MySQL, Postgres, MariaDB, and SQL Server are available


spring:
  profiles:
    include:
  datasource:
    platform: mysql
    driver-class-name: org.mariadb.jdbc.Driver
    url: jdbc:mariadb://db:3306/shibui
    username: shibui
    password: shibui
  jpa:
    properties:
      hibernate:
        dialect: org.hibernate.dialect.MariaDB103Dialect
 
----------------------------------------------------------------
 
spring:
  profiles:
    include:
  datasource:
    platform: mysql
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://db:3306/shibui
    username: shibui
    password: shibui
  jpa:
    properties:
      hibernate:
        dialect: org.hibernate.dialect.MySQL8Dialect
 
----------------------------------------------------------------
 
spring:
  profiles:
    include:
  datasource:
    platform: postgres
    driver-class-name: org.postgresql.Driver
    url: jdbc:postgresql://db:5432/shibui
    username: shibui
    password: shibui
  jpa:
    properties:
      hibernate:
        dialect: org.hibernate.dialect.PostgreSQL95Dialect
 
----------------------------------------------------------------
 
spring:
  profiles:
    include:
  datasource:
    platform: sqlserver
    driver-class-name: com.microsoft.sqlserver.jdbc.SQLServerDriver
    url: jdbc:sqlserver://db:1433
    username: shibui
    password: shibui
  jpa:
    properties:
      hibernate:
        dialect: org.hibernate.dialect.SQLServerDialect


application.properties settings

This is a reflection of the default application.properties file included in the distribution. Note that lines beginning with # are commented out.

# Server Configuration
#server.port=8080
 
# Logging Configuration
#logging.config=classpath:log4j2.xml
 
#logging.level.org.springframework.security=INFO
logging.level.org.springframework=INFO
logging.level.edu.internet2.tier.shibboleth.admin.ui=INFO
 
spring.main.allow-bean-definition-overriding=true
 
# Database Credentials
spring.datasource.username=shibui
spring.datasource.password=shibui
 
# Database Configuration H2
spring.datasource.url=jdbc:h2:mem:shibui;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE
spring.datasource.platform=h2
spring.datasource.driverClassName=org.h2.Driver
spring.jpa.database-platform=org.hibernate.dialect.H2Dialect
spring.h2.console.enabled=true
spring.h2.console.settings.web-allow-others=true
 
# spring.jackson.default-property-inclusion=non_absent
spring.jackson.default-property-inclusion=NON_NULL
spring.jackson.mapper.accept-case-insensitive-enums=true
 
# Database Configuration PostgreSQL
#spring.datasource.url=jdbc:postgresql://localhost:5432/shibui
#spring.datasource.driverClassName=org.postgresql.Driver
#spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect
 
#Maria/MySQL DB
#spring.datasource.url=jdbc:mariadb://localhost:3306/shibui
#spring.datasource.driverClassName=org.mariadb.jdbc.Driver
#spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MariaDBDialect
 
# Liquibase properties
spring.liquibase.enabled=false
 
# Hibernate properties
# for production never ever use create, create-drop. It's BEST to use validate
spring.jpa.hibernate.ddl-auto=update
spring.jpa.hibernate.naming.implicit-strategy=org.hibernate.boot.model.naming.ImplicitNamingStrategyJpaCompliantImpl
spring.jpa.show-sql=false
spring.jpa.properties.hibernate.format_sql=false
spring.jpa.properties.hibernate.check_nullability=true
spring.jpa.hibernate.use-new-id-generator-mappings=true
 
#Envers versioning
spring.jpa.properties.org.hibernate.envers.store_data_at_delete=true
 
#Needed in the latest versions of Spring Boot when doing manual transaction management like we do in envers versioning code
spring.jpa.properties.hibernate.current_session_context_class=org.springframework.orm.hibernate5.SpringSessionContext
 
# Set the following property to periodically write out the generated metadata files. There is no default value; the following is just an example
# shibui.metadata-dir=/opt/shibboleth-idp/metadata/generated
shibui.logout-url=/dashboard
 
# spring.profiles.active=default
 
## Default root user can be set in application.yml or here - setting in both places can be undeterministic
## Default password must be set for the default user to be configured and setup
#shibui.default-password={noop}somepassword
shibui.default-rootuser=root
 
shibui.metadata-sources-ui-schema-location=classpath:metadata-sources-ui-schema.json
shibui.entity-attributes-filters-ui-schema-location=classpath:entity-attributes-filters-ui-schema.json
shibui.nameid-filter-ui-schema-location=classpath:nameid-filter.schema.json
 
#Actuator endpoints (info)
# Un-comment to get full git details exposed like author, abbreviated SHA-1, commit message
#management.info.git.mode=full
 
###
# metadata-providers.xml write configuration
 
# Set the following property to periodically write out metadata providers configuration. There is no default value; the following is just an example
# The run rate is defined in milliseconds. You will need to configure your Shibboleth IDP to read the produced file
# shibui.metadataProviders.target=file:/opt/shibboleth-idp/conf/shibui-metadata-providers.xml
# shibui.metadataProviders.taskRunRate=30000
 
# Email configuration (local mailhog)
# spring.mail.host=mailhog
# spring.mail.port=1025
# spring.mail.username=username
# spring.mail.password=password
# spring.mail.properties.mail.smtp.auth=false
# spring.mail.properties.mail.smtp.starttls.enable=false
 
shibui.mail.text-email-template-path-prefix=/mail/text/
shibui.mail.html.email-template-path-prefix=/mail/html/
shibui.mail.system-email-address=doNotReply@shibui.org
 
 
#ShibUIConfiguration slurps in these values and they are bootstrapped in on startup
shibui.roles=ROLE_ADMIN,ROLE_ENABLE,ROLE_USER,ROLE_NONE
#Authenticated access roles - used by Spring Security to allow access when authenticated
shibui.roles.authenticated=ADMIN,ENABLE,USER
 
#In order to enable authentication via configured pac4j library (with external SAMl Idp, for example)
#This property must be set to true and pac4j properties configured. For sample pac4j properties, see application.yml
#for an example pac4j configuration
#shibui.pac4j-enabled=true
 
#This property must be set to true in order to enable posting stats to beacon endpoint. Furthermore, appropriate
#environment variables must be set for beacon publisher to be used (the ones that are set when running shib-ui in
#docker container
shibui.beacon-enabled=true


Additional Configuration via YAML Properties

The following properties may be customized through an `application.yml` file. 

Attributes (for Attribute Release)

Example:

Attribute Release

custom:
  attributes:
    - name: eduPersonPrincipalName
      displayName: label.attribute-eduPersonPrincipalName
    - name: uid
      displayName: label.attribute-uid

name: The name of the entry. used to uniquely identify this entry.

displayName: This will normally be the label used when displaying this override in the UI. (set in messages.properties)

Defaults attributes

Relying Party Overrides

Note: The application.yml file allows you to create Relying Party overrides that will be imported into the database configuration at startup. This can be used to bootstrap the database with a set of Relying Party overrides. Once the Shibb UI has imported these overrides, they will be managed through the user interface (as Custom Attributes) and any changes to them in the application.yml file will be ignored in favor of the configuration in the database. Adding overrides to the application.yml file is not recommended unless you have a large number of overrides to add all at once. 

It is imperative when defining these that the "displayType" and "persistType" are known types. Typos or unsupported values here will result in that override being skipped! Supported types are as follows: boolean, integer, string, set, list. Note that "persistType" doesn't have to match "displayType". However, the only unmatching combination currently supported is a "displayType" of "boolean" and "persistType" of "string".

Example:
Relying Party Overrides




custom:
  overrides:
    - name: signAssertion
      displayName: label.sign-the-assertion
      displayType: boolean
      defaultValue: false
      helpText: tooltip.sign-assertion
      attributeName: http://shibboleth.net/ns/profiles/saml2/sso/browser/signAssertions
      attributeFriendlyName: signAssertions
    - name: dontSignResponse
      displayName: label.dont-sign-the-response
      displayType: boolean
      defaultValue: false
      helpText: tooltip.dont-sign-response
      attributeName: http://shibboleth.net/ns/profiles/saml2/sso/browser/signResponses
      attributeFriendlyName: signResponses
      invert: true




name: The name of the entry. used to uniquely identify this entry.

displayName: This will normally be the label used when displaying this override in the UI. (set in messages.properties)

displayType: The type to use when displaying this option

defaultValue(s): One or more values to be displayed as default options in the UI

helpText: This is the help-icon hover-over text

attributeName: This is the name of the attribute to be used in the xml. This is assumed to be a URI.

attributeFriendlyName: This is the friendly name associated with the above attributeName.

invert: 

persistType: Optional. If it is necessary to persist something different than the override's display type, set that type here. For example, display a boolean, but persist a string.

persistValue: Required only when persistType is used. Defines the value to be persisted.

Default properties

User Maintenance

TAP Beacon instrumentation

SAML MCM software includes piece of instrumentation functionality which sends a small batch of statistical data about the environment in which application is deployed such as Docker image name, version, application name, etc. to a running "Beacon collector" facility which is exposed as a REST HTTP endpoint, as defined here: https://spaces.at.internet2.edu/display/TWGH/TIER+Instrumentation+-+The+TIER+Beacon In the specification page it is described to be implemented as a external cron job running inside Docker container, which is true for other TAP docker images instrumented with Beacon, but Shibboleth Idp UI application has this functionality implemented as an optional Java module. It is an opt-in type of functionality which is off by default but could be turned on with the following application property:

shibui.beacon-enabled=true

Once it is turned on it will assynchronoiusly send beacon data which it will gather from necessary environment variables (which will be set by TAP Docker image for shibboleth idp ui application), but if running outside of TAP Docker container and those environment variables are not set, even though the beacon module is enabled, the data will not be sent. Below is the example of necessary environment variables that need to be set in order for Beacon module to kick in if running outside of TAP Docker container:

LOGHOST="https://collector.testbed.tier.internet2.edu"
LOGPORT="5001"
IMAGE="shibui_local_no_image"
MAINTAINER="local_no_maintainer"
VERSION="1.11.0-SNAPSHOT"
TIERVERSION="191010"



                                                                                                                                                                                                                                                                                                                                                               No labels


Write a comment...