| Table of Contents | ||
|---|---|---|
|
Requirements
- Docker or other OCI server OR Java 11 or higher (Tested with Amazon Corretto 11)
- %TODO% G memory
- RDBMS for persistent configuration storage:
- PostgreSQL (version 14 is the presumed default)
- Tested with latest docker images of MariaDB, MySQL and SQL Server.
- docker-compose and application.yml examples for each DB can be found in the testbed directory in the Git repository.
- A method for providing generated metadata to the associated IDP:
- Shared filesystem
- Git push/pull
- file transfer
- MDQ
Downloads
Pre-built docker images are on Docker Hub.
Releases for the Java war file can be found in the Internet2 GitHub project repository.
Quick Start Demo
Using Docker:
| Code Block | ||||
|---|---|---|---|---|
| ||||
docker run \
-p 8080:8080 \
-p 9090:9090 \
i2incommon/shib-idp-ui:latest |
...
API documentation from Swagger is available on port 9090. This port is exposed in this demo, but is not for user access in production.
Deployment Considerations
The principal output from the Shib IDP UI application are XML files. Metadata provider records in the UI correspond to MetadataConfiguration resources, which contain pointers to the actual entity metadata to consume. Metadata source records in the UI define individual entities, and each entity corresponds to a single XML file defining its metadata. The entity files are generally to be used with a LocalDynamicMetadataProvider, and the entity file names follow its convention of lower case hex-encoded SHA-1 digest of the entityID, suffixed with ".xml" The locations in the filesystem to save the output are defined by UI application properties, and have no defaults. See {Configuration} for details on how to define these.
...
- UI running as a web application on the same server as the IDP, and saved to local filesystem
- Shared filesystem between the UI and the IDP
- Git push/pull jobs
- file transfer jobs
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 Java application (using an embedded Tomcat server), or as a Java web application running under an installed Tomcat or Jetty web application server. Both the standalone and web application methods can be used either directly on a web server, or packaged inside a Docker image. Internet2 supplies pre-built Docker images for released versions. The deployment method is largely dependent on your own infrastructure and knowledge base.
Configuration
Regardless of which method is used to run the Shibboleth IdP UI, configuration is required. Much of the behavior of the UI can be set and controlled through property files which can be in one or both of the following formats:
...
Spring properties also utilize profile designations, which target the reading of an environment-specific configuration file. For example, when passing Java system property -Dspring.profiles.active=prod, setting environment variable SPRING_PROFILES_ACTIVE=prod, or setting property spring.profiles.active=prod in application.properties, application startup will additionally load file application-prod.properties, using the same search order as for application.properties.
Database properties
The Shib IDP UI can be integrated with a variety of back end databases to store registry information. The distribution includes JDBC drivers for PostgreSQL, MySQL, MariaDB, and SQL Server. With no custom database configuration, the application will default to an embedded in-memory H2 database, which will be cleared out on application exit. Database-specific properties to set are:
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
spring:
datasource:
platform: sqlserver
driver-class-name: com.microsoft.sqlserver.jdbc.SQLServerDriver
url: jdbc:sqlserver://db-hostname:1433
username: sa
password: Password1
jpa:
properties:
hibernate:
dialect: org.hibernate.dialect.SQLServerDialect |
Authentication
There are three methods for authenticating users. The first two involve choosing an encryption scheme for the password from one of the following:
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
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 |
Entity Metadata Files
Entity metadata is not written to XML files by default. To periodically write the generated metadata files to a target directory, define:
...
| Info |
|---|
Each entity corresponds to a single XML file defining its metadata. To calculate the SHA-1 base name from an entityID, the following can be run on the command line: |
Metadata Provider File
The metadata providers defined in the UI are not written to an external XML file by default. To periodically write the generated configuration to a filesystem resource, define:
...
Similar to the entity task run rate, the shibui.metadataProviders.taskRunRate property defaults to 30000 or every 30 seconds and can accept a number which represents milliseconds, or a Java Duration.
Metadata External Provider File
TODO
Other properties
The full set of properties used in the UI, with their defaults, are embedded in the war file application.yml and application.properties.
Spring properties can also be utilized to define server behavior. Logging levels, JDBC tuning, or HTTPS are common ones to use.
Enabling HTTPS Listener
Add these Spring properties to your configuration file:
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
keytool -genkeypair -alias tomcat -keyalg RSA -keysize 2048 -storetype PKCS12 -keystore keystore.p12 -validity 3650 |
Deployments Examples
Internet2 Docker image - base image with mounted configuration
In this example, properties include shibui.user-bootstrap-resource=file:/opt/shibui/users.csv, along with connections to an existing database.
...
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.
Standalone war file
This example assumes all the files are placed in the same directory that the war will be run from and that the PostgreSQL database is running locally.
- Download the war from https://github.internet2.edu/TIER/shib-idp-ui/releases/
- Create a users.csv with:
root,{bcrypt}$2a$10$V1jeTIc0b2u7Y3yU.LqkXOPRVTBFc7SW07QaJR4KrBAmWGgTcO9H.,first,last,ROLE_ADMIN,user1@example.org - Start the database
docker run --rm --name postgres-db -p 5432:5432 -e POSTGRES_PASSWORD=shibui -e POSTGRES_USER=shibui -d postgres Create a basic Shibboleth IdP UI configuration with database settings
Code Block language yml title startup - standalone war file 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_PONYRun 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- You can access the application at http://localhost:8080 and login with root/password
Running under https is accomplished by adding the following to your configuration file
Code Block server: ssl: key-store: keystore.p12 key-store-password: password key-store-type: pkcs12 key-alias: tomcat key-password: password port: 8443
Tomcat web application
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.
...