You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

Requirements

  • Java 11.x (Tested with Amazon Corretto 11)
  • RDBMS for persistent configuration storage
    • Postgres 14 is the presumed default.
    • Tested with latest docker images of mariadb, Mysql and SQLserver.  An example docker-compose and application.yml for each DB can be found in the testbed directory in the Git repository. 

Running

The Shibboleth IdP UI 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, Jetty etc..). It can also be deployed using a Docker image.

Deployment Considerations

Choosing which method to run the Shibboleth IdP UI is largely dependent on your own infrastructure and knowledge base.  The UI was designed with the mindset that it would run alongside the Shibboleth IdP and integrate with it via a shared volume.  This is only one possible method of integration and the UI does not force any conventions on how the data is shared with the IdP.  For an example of using a shared docker volume to integrate with the IdP look at the integration testbed in the Git repository. 

Configuration Files

Regardless of which method is used to run the Shibboleth IdP UI a configuration file(s) is required. Much of the behavior of the UI can be set and controlled through properties files which can be in one or both of the following formats:

  • application.properties , a Spring property file similar to the ones used in the Shibboleth IdP – a simple text file with a property name, equals sign, and the property value, one per line.
  • application.yml , a YAML format file

Choosing which format to use is largely a personal choice as functionally they are identical. One caveat is in the case that there is both a properties and yml file, the properties file will be read first. 

The ShibUI comes with a basic example of both, with the example application.properties file having the core settings for authentication, database connection information, users file, directory/location settings for where the UI 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 technical reason that you need to follow the examples and keep the distinction; you could manage everything through a single application.properties or application.yml 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. 

Authentication

There are three methods for authenticating users. The first two involve choosing an encryption scheme for the password from one of the following:

  • noop -- clear text password follows
  • bcrypt -- the following value has been encrypted with the $2a$ Bcrypt algorithm (limitation of the underlying Spring library currently incorporated is that only the $2a$ Bcrypt algorithm is supported.)

1. A single root user. This is the default and will generate a random password displayed in the console for the root user at runtime.  The name and password for this user can also be set in application.properties with

shibui.default-rootuser=root
shibui.default-password={ENCRYPT_SCHEME}somepassword

2. Users defined via a file with a format of:

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

Where ROLE_VALUE is one of:

  • ROLE_ADMIN -- No limits, can do anything the Shibboleth IdP UI supports. Currently, Metadata Provider configuration (and filter configuration) requires ROLE_ADMIN access
  • ROLE_USER -- These users can only add individual metadata sources and modify metadata sources that they created.  When creating a new SP entry, that SP metadata will not be active until a user with ROLE_ADMIN approves it.
  • ROLE_ENABLE – These are "enhanced" ROLE_USER users that have the ability to enable/publish SP metadata but cannot access/configure Metadata Provider (and filter) configurations

Note: you must have at least one user with ROLE_ADMIN.

Then instruct the UI where to find that file in application.properties

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

3. User authenticated via SAML

The Shibboleth IdP UI includes a Java-based SAML SP based on the Pac4j ( https://www.pac4j.org ) library (SAML support built on top of the Shibboleth Consortium's OpenSAML software).  Configuration requires a few external steps and configuration of application.properties.

  1. Configure, in a users file, at least one user that will match up with a Shibboleth IdP supplied user identifier with ROLE_ADMIN (password is a required field in the file but is irrelevant/ignored in the user file)
  2. Create a copy of the Shibboleth IdP's metadata and place within the file system where the UI can access
  3. Create the Metadata for the SP and place within the file system where the UI can access

  4. Configure the following settings in application.properties or application.yml

    shibui:
  default-password: "{noop}password"
  user-bootstrap-resource: file:/opt/shibui/conf/users.csv
  roles: ROLE_ADMIN,ROLE_NONE,ROLE_USER,ROLE_ENABLE,ROLE_PONY
  pac4j-enabled: true
  pac4j:
    keystorePath: "/opt/shibui/conf/samlKeystore.jks"
    keystorePassword: "password"
    privateKeyPassword: "password"
    serviceProviderEntityId: "https://shibui.local/shibui"
    serviceProviderMetadataPath: "/opt/shibui/conf/sp-metadata.xml"
    identityProviderMetadataPath: "/opt/shibboleth-idp/metadata/idp-metadata.xml"
    forceServiceProviderMetadataGeneration: false
    callbackUrl: "https://shibui.local/shibui/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
      groups: urn:oid:2.5.4.15  # businessCategory
      roles: urn:oid:1.3.6.1.4.1.5923.1.1.1.7  # eduPersonEntitlement

Deployment Examples

Embedded Tomcat

This example assumes all the files are placed in the same directory that the war will be run from and that the Postgres database is running locally.

  1. Download the war from https://github.internet2.edu/TIER/shib-idp-ui/releases/

  2. Create a users.csv with:

    root,{bcrypt}$2a$10$V1jeTIc0b2u7Y3yU.LqkXOPRVTBFc7SW07QaJR4KrBAmWGgTcO9H.,first,last,ROLE_ADMIN,user1@example.org

  3. Start the database

    docker run --rm --name postgres-db -p 5432:5432 -e POSTGRES_PASSWORD=shibui -e POSTGRES_USER=shibui -d postgres

  4. Create a basic Shibboleth IdP UI configuration with database settings

    spring:
  profiles:
    include:
  datasource:
    platform: postgres
    driver-class-name: org.postgresql.Driver
    url: jdbc:postgresql://localhost:5432/shibui
    username: shibui
    password: shibui
  jpa:
    show-sql: false
    properties:
      hibernate:
        dialect: org.hibernate.dialect.PostgreSQL95Dialect
        format_sql: true
shibui:
  user-bootstrap-resource: file:users.csv
  roles: ROLE_ADMIN,ROLE_NONE,ROLE_USER,ROLE_PONY

  5. Run the war and tell it where to find your configuration files

    java -Xmx1g -jar shibui-1.16.0.war --spring.config.additional-location=file:application.yml
  6. You can access the application at http://localhost:8080 and login with root/password

  7. Running under https is accomplished by adding the following to your configuration file

    server:
  ssl:
    key-store: keystore.p12
    key-store-password: password
    key-store-type: pkcs12
    key-alias: tomcat
    key-password: password
  port: 8443
Java Servlet Container
This example assume Tomcat but the procedure for Jetty or others will be similar.  Also assumes configuration files will be placed in /opt/shibui/ and that the Postgres database is already running.
  1. Download the war from https://github.internet2.edu/TIER/shib-idp-ui/releases/ and place it in your Tomcat webapps dir.  Ex. /opt/tomcat/webapps/

  2. Create a /opt/shibui/users.csv with:

    root,{bcrypt}$2a$10$V1jeTIc0b2u7Y3yU.LqkXOPRVTBFc7SW07QaJR4KrBAmWGgTcO9H.,first,last,ROLE_ADMIN,user1@example.org

  3. Create a basic Shibboleth IdP UI configuration with database settings

    spring:
  profiles:
    include:
  datasource:
    platform: postgres
    driver-class-name: org.postgresql.Driver
    url: jdbc:postgresql://localhost:5432/shibui
    username: shibui
    password: shibui
  jpa:
    show-sql: false
    properties:
      hibernate:
        dialect: org.hibernate.dialect.PostgreSQL95Dialect
        format_sql: true
shibui:
  user-bootstrap-resource: file:/opt/shibui/users.csv
  roles: ROLE_ADMIN,ROLE_NONE,ROLE_USER,ROLE_PONY

  4. Tell Tomcat where to find the configuration files by adding the following to $CATALINA_HOME/bin/setenv.sh

    export JAVA_OPTS="$JAVA_OPTS -Dspring.config.additional-location=file:/opt/shibui/"
  5. You can access the application at http://localhost:8080 and login with root/password
  6. Running under https is accomplished using the standard Tomcat or Jetty SSL connectors.
Docker

There are many ways to deploy an application with Docker and the following example is only meant to show a simplistic approach for demonstration purposes.  A docker compose example of a fully functioning Shibboleth IdP UI with full integration with the Shibboleth IdP can be found in the smoke-test testbed in the Git repository.  

  1. Create a users.csv with:

    root,{bcrypt}$2a$10$V1jeTIc0b2u7Y3yU.LqkXOPRVTBFc7SW07QaJR4KrBAmWGgTcO9H.,first,last,ROLE_ADMIN,user1@example.org

  2. Start the database

    docker run --rm --name postgres-db -p 5432:5432 -e POSTGRES_PASSWORD=shibui -e POSTGRES_USER=shibui -d postgres

  3. Create a basic Shibboleth IdP UI configuration with database settings

    spring:
  profiles:
    include:
  datasource:
    platform: postgres
    driver-class-name: org.postgresql.Driver
    url: jdbc:postgresql://localhost:5432/shibui
    username: shibui
    password: shibui
  jpa:
    show-sql: false
    properties:
      hibernate:
        dialect: org.hibernate.dialect.PostgreSQL95Dialect
        format_sql: true
shibui:
  user-bootstrap-resource: file:/opt/shibui/users.csv
  roles: ROLE_ADMIN,ROLE_NONE,ROLE_USER,ROLE_PONY

  4. Start the Shibboleth IdP UI

    docker run -p 8080:8080 -v application.yml:/opt/shibui/application.yml -v users.csv:/opt/shibui/users.csv i2incommon/shib-idp-ui
  5. You can access the application at http://localhost:8080 and login with root/password
  • No labels