Date: Fri, 29 Mar 2024 08:24:56 +0000 (UTC) Message-ID: <1787489802.7701.1711700696865@ip-10-10-7-29.ec2.internal> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_7700_1563581379.1711700696863" ------=_Part_7700_1563581379.1711700696863 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
Pre-built docker images are on Docker Hub.
Releases for the Java war file can be found in the Inte= rnet2 GitHub project repository.
Using Docker:
docker = run \ -p 8080:8080 \ -p 9090:9090 \ i2incommon/shib-idp-ui:latest
As a standalone app:
VERSION= =3D1.16.0 wget https://github.internet2.edu/TIER/shib-idp-ui/releases/download/v$VERS= ION/shibui-$VERSION.war java -jar -Dshibui.default-password=3D{noop}abcd1234 shibui-$VERSION.war
Once up, the application can be accessed at http://localhost:8080/. The demo include=
s an in-memory H2 database, and a default administration user. For the dock=
er demo, the user is "root" and password is "password". For the standalone =
app, there is no default password. The demo above sets it to "abcd1234" by =
setting application property shibui.default-password
.
API documentation from Swagger is available on port 9090. This po= rt is exposed in this demo, but is not for user access in production.
The principal output from the Shib IDP UI application are XML files. Met= adata provider records in the UI correspond to MetadataConfiguration resources, which contain po= inters 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 LocalDynamicMetadataProvi= der, and the entity file names follow its convention of lower case hex-enco= ded SHA-1 digest of the entityID, suffixed with ".xml" The locations in the= filesystem to save the output are defined by UI application properties, an= d have no defaults. See {Configuration} for details on how to define these.=
The IDP reads metadata provider and entity metadata from these files, so= they must be accessible by the IDP. There are a number of ways these files= can get from the UI to the IDP:
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 a= pplication (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 we= b server, or packaged inside a Docker image. Internet2 supplies pre-built D= ocker images for released versions. The deployment method is largely depend= ent on your own infrastructure and knowledge base.
Regardless of which method is used to run the Shibboleth IdP UI, configu= ration is required. Much of the behavior of the UI can be set and controlle= d through property files which can be in one or both of the following forma= ts:
Choosing which format to use is largely a personal choice as functionall= y they are identical. One caveat is in the case that there is both a proper= ties and yml file, the properties file will be read first.
The ShibUI comes with a basic example of both, with the example application.pr= operties file having the core settings for authentication, database con= nection information, users file, directory/location settings for where the = UI should write out the metadata files and metadata-providers.xml file it m= anages, etc. The example application.yml file contains all the settings that impact = the information, options, list elements, etc. that are actually shown in th= e UI.
There is no technical reason that you need to follow the examples and ke= ep the distinction; you could manage everything through a single applicatio= n.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" dis= tinct from the "front-end/UI" settings.
The application properties are Spring configuration files, and follow its built-in methods for w= here it looks for these files:
--spring.config.loc=
ation=3Dfile://{absolute-path-to-file}
--spring.config.locat=
ion=3Dfile://{absolute-path-to-directory}
-Dspring.config.location
SPRING_CONFIG_LOCATION
spring.config.additional-location
Spring properties also utilize profile designations, which target the reading of an environmen=
t-specific configuration file. For example, when passing Java system proper=
ty -Dspring.profiles.active=3Dprod
, setting environment variab=
le SPRING_PROFILES_ACTIVE=3Dprod
, or setting property sp=
ring.profiles.active=3Dprod
in application.properties, application s=
tartup will additionally load file application-prod.properties
=
, using the same search order as for application.properties.
The Shib IDP UI can be integrated with a variety of back end databases t= o store registry information. The distribution includes JDBC drivers for Po= stgreSQL, MySQL, MariaDB, and SQL Server. With no custom database configura= tion, the application will default to an embedded in-memory H2 database, wh= ich will be cleared out on application exit. Database-specific properties t= o set are:
PostgreSQL:
spring: datasource: platform: postgres driver-class-name: org.postgresql.Driver url: jdbc:postgresql://db-hostname:5432/db-name username: shibui password: shibui jpa: properties: hibernate: dialect: org.hibernate.dialect.PostgreSQLDialect
MySQL:
spring: datasource: platform: mysql driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://db-hostname:3306/db-name username: shibui password: shibui jpa: properties: hibernate: dialect: org.hibernate.dialect.MySQL8Dialect
MariaDB:
spring: datasource: platform: mysql driver-class-name: org.mariadb.jdbc.Driver url: jdbc:mariadb://db-hostname:3306/db-name username: shibui password: shibui jpa: properties: hibernate: dialect: org.hibernate.dialect.MariaDB103Dialect
SQL Server:
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
There are three methods for authenticating users. The first two involve = choosing an encryption scheme for the password from one of the following:= p>
1. A single root user. The default user is root
, but can be=
set to another username via property shibui.default-rootuser
.=
there is no default password in the war file, but it can be defined via pr=
operty shibui.default-password
. NOTE: The Internet2 docker image does include a users.txt wh=
ich has a default root password of password
<=
/span>.
2. Users defined in a bootstrap file, and imported at startup by definin=
g property shibui.user-bootstrap-resource=3Dfile:/full/path/to/user-f=
ile
. In the Internet2 image, a sample users.txt file, with user password
, is included in the app f=
older, and imported in the default startup command.
The file is a comma-separated list of users to bootstrap, with a format = of:
username,{ENCRYPT_SCHEME}password,firstname,lastname,ROLE_VALUE,em=
ail
Where ROLE_VALUE is one of:
ROLE_ADMIN -- No limits, can do anything the Shibbo= leth IdP UI supports. Currently, Metadata Provider configuration (and filte= r configuration) requires ROLE_ADMIN access
ROLE_USER -- These users can only add individual me= tadata sources and modify metadata sources that they created. When cr= eating a new SP entry, that SP metadata will not be active until a user wit= h ROLE_ADMIN approves it.
ROLE_ENABLE =E2=80=93 These are "enhanced" ROLE_USE= R users that have the ability to enable/publish SP metadata but cannot acce= ss/configure Metadata Provider (and filter) configurations
Note: you must have at least one user with ROLE_ADMIN.<= /p>
To encrypt a password using Bcrypt, there are online Bcrypt encryption t= ools. For security, if you want to encrypt offline, the following python sc= ript can be used.
import bcrypt
password =3D 'passw0rd123'
bytes =3D password.encode('utf-8')
salt =3D bcrypt.gensalt()
hash =3D bcrypt.hashpw(bytes, salt)
print(hash)
3. User authenticated via SAML
The Shibboleth IdP UI includes a Java-based SAML SP based on the Pac4j (= https://www.pac= 4j.org ) library (SAML support built on top of the Shibboleth Consortiu= m's OpenSAML software). Configuration requires a few external steps a= nd configuration of application.properties.
Configure, in a users file, at least one user that will match up wit= h 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)
<= /li>Create a copy of the Shibboleth IdP's metadata and place within the = file system where the UI can access
Create the Metadata for the SP and place within the file system wher= e the UI can access
Configure the following settings in application.properties or applic= ation.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-metadat= a.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 is not written to XML files by default. To periodically = write the generated metadata files to a target directory, define:
shibui.= metadata-dir=3D/path/to/metadata/output/directory shibui.taskRunRate=3Dmilliseconds-or-duration
Property shibui.metadata-dir
is an absolute path to the out=
put directory. Entity filenames will be constructed by combining the direct=
ory and the base name derived from the SHA-1 digest of the entityID, adding=
the path separator if needed.
The shibui.taskRunRate
property (default 30000 or every 30 =
seconds) sets the output to be generated at timed intervals. The property c=
an accept a number which represents milliseconds, or a Java Duration s=
uch as PT20M.
Each entity corresponds to a single XML file defining its metadata. To calculate the SHA-1 base name fro= m an entityID, the following can be run on the command line:
$ echo -n "urn:test:foobar" | openssl sha1
d278c9975472a6b4827b1a8723192b4e99aa969c
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:
shibui.= metadataProviders.target=3Dfile:/path/to/provider-file.xml shibui.metadataProviders.taskRunRate=3Dmilliseconds-or-duration
Property shibui.metadataProviders.target
is the filename fo=
r the output xml. It expects a Java Resource, thus requires file: before the path.
Similar to the entity task run rate, the shibui.metadataProviders.=
taskRunRate
property defaults to 30000 or every 30 seconds and can a=
ccept a number which represents milliseconds, or a Java Duration.
TODO
The full set of properties used in the UI, with their defaults, are embe= dded in the war file application.yml and application.properties.
Spring properties can also be utilized to define server beh= avior. Logging levels, JDBC tuning, or HTTPS are common ones to use.
Add these Spring properties 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
Spring boot supports keystores in either the PKCS12 or JKS format. An ex= ample command to generate a new keystore:
keytool= -genkeypair -alias tomcat -keyalg RSA -keysize 2048 -storetype PKCS12 -key= store keystore.p12 -validity 3650
In this example, properties include shibui.user-bootstrap-resource=
=3Dfile:/opt/shibui/users.csv
, along with connections to an existing=
database.
docker = run -d \ -p 8080:8080 \ -e SPRING_PROFILES_ACTIVE=3Dprod \ -v $PWD/conf/application.properties:/opt/shibui/application.properties = \ -v $PWD/conf/prod/application.properties:/opt/shibui/application-prod.p= roperties \ -v $PWD/conf/users.csv:/opt/shibui/users.csv \ -v $PWD/output/providers:/var/log/providers \ -v $PWD/output/metadata:/var/log/metadata \ i2incommon/shib-idp-ui:latest
There are many ways to deploy an application with Docker and the followi= ng example is only meant to show a simplistic approach for demonstration pu= rposes. A docker compose example of a fully functioning Shibboleth Id= P UI with full integration with the Shibboleth IdP can be found in the smoke-test testbed in the Git reposit= ory.
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 local= ly.
Create a basic Shibboleth IdP UI config=
uration 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
Run the war and tell it where to find y=
our configuration files
java -Xmx1g -jar shibui-1.16.0.war --spring.config.additional-location=3Dfi=
le:application.yml
Running under https is accomplished by = adding the following to your configuration file
serve= r: ssl: key-store: keystore.p12 key-store-password: password key-store-type: pkcs12 key-alias: tomcat key-password: password port: 8443
This example assume Tomcat but the procedure for Jetty or others will be= similar. Also assumes configuration files will be placed in /opt/shi= bui/ and that the Postgres database is already running.
Download the war from https://github.internet2.edu/= TIER/shib-idp-ui/releases/ and place it in your Tomcat webapps dir. &nb= sp;Ex. /opt/tomcat/webapps/
Create a /opt/shibui/users.csv with:
root,{bcrypt}$2a$10$V1jeTIc0b2u7Y3yU.LqkXOPRVTBFc7SW07QaJR4KrBAmWGgTcO9H.,f=
irst,last,ROLE_ADMIN,user1@example.org
Create a basic Shibboleth IdP UI configuration with database setting= s
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