Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  • The ShibUI requires a backing relational database for storage. Out of the box, you can run the application using an in memory to get familiar with the application, but you will need a permanent data store in order to retain configurations
  • Java 11+ - the Docker version of the deployment includes the needed Java environment to run the application

Downloads

...

...

  • version 1.11.0 released 07/26/2022)

Configuration Notes

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

...

Note: the settings for where Pac4j will store its SAML-related certificates ( shibui.pac4j.keystorePath and related passwords) and SP metadata ( shibui.pac4j.serviceProviderMetadataPath ) will be the locations where you want Pac4j to store (it will self-generate files on first attempt to access. These don't need to be existing files, it is easiest to let Pac4j do the generation for you.)


Code Block
titleapplication.properties config example
# Enable Pac4j, should generate its own certs and metadata on first attempt to use
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.saml2ProfileMapping.username = urn:oid:0.9.2342.19200300.100.1.1
shibui.pac4j.saml2ProfileMapping.firstname = urn:oid:2.5.4.42
shibui.pac4j.saml2ProfileMapping.lastname = urn:oid:2.5.4.4
shibui.pac4j.saml2ProfileMapping.email = urn:oid:0.9.2342.19200300.100.1.3





Code Block
titleapplication.yml config example
shibui:
  pac4j-enabled: true # Enable Pac4j, should generate its own certs and metadata on first attempt to use
  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: false
    callbackUrl: https://localhost:8443/callback
    maximumAuthenticationLifetime: 3600000
    saml2ProfileMapping:
      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 ShibUI, and try to access the dashboard, you should be directed to the configured IdP for authentication. The IdP should present an error, because you have not yet configured it with metadata and attribute release for the ShibUI.

...

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


Code Block
# 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

...

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.

...

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.

...

  1. In your application properties, configure: shibui.metadataProviders.target - this should be the full path, including filename, of the XML output ShibUI will generate for metadata providers (the location must be writable by the ShibUi application and readable by the Shibboleth IdP , but not a temp directory that will get deleted/cleaned by the host system processes. eg - file:/opt/shibboleth/config/dynamic_config/metadata-providers.xml
  2. In your application properties, configure: shibui.metadata-dir - this should be the full path of the directory to create metadata source files. Again, the location should be writeable by the ShibUI and readable by the IDP. eg - /opt/shibboleth/config/dynamic_metadata
  3. In your Shibboleth configuration's services.xml file, update the block for shibboleth.MetadataResolverResources to include the shibui.metadataProviders.target location 



Code Block
titleexample
<util:list id="shibboleth.MetadataResolverResources">
    <value>%{idp.home}/conf/metadata-providers.xml</value>
    <value>%{idp.home}/system/conf/metadata-providers-system.xml</value>
    <value>${idp.home}/conf/dynamic_config/metadata-providers.xml</value> <!-- match the shibui.metadataProviders.target value -->
</util:list>


Shibboleth will require a restart to pick up the change.

...