[Shibboleth Metadata Management UI/UX] Pages FeedConfluence Syndication Feedhttps://spaces.at.internet2.eduDeployment Instructionssean.porth@at.internet2.edutag:spaces.at.internet2.edu,2009:page-172263803-122024-03-26T17:08:20Z2020-09-10T17:08:42Z<div class="feed"> <p>
Page
<b>edited</b> by
<a href=" https://spaces.at.internet2.edu/display/~sean.porth@at.internet2.edu
">sean.porth@at.internet2.edu</a>
</p>
<div style="border-top: 1px solid #ddd; border-bottom: 1px solid #ddd; padding: 10px;">
<p><style type='text/css'>/*<![CDATA[*/
div.rbtoc1711709330044 {padding: 0px;}
div.rbtoc1711709330044 ul {margin-left: 0px;}
div.rbtoc1711709330044 li {margin-left: 0px;padding-left: 0px;}
/*]]>*/</style><div class='toc-macro rbtoc1711709330044'>
<ul class='toc-indentation'>
<li><a href='#DeploymentInstructions-Requirements'>Requirements</a></li>
<li><a href='#DeploymentInstructions-Downloads'>Downloads</a></li>
<li><a href='#DeploymentInstructions-ConfigurationNotes'>Configuration Notes</a>
<ul class='toc-indentation'>
<li><a href='#DeploymentInstructions-DemoEnvironment'>Demo Environment</a>
<ul class='toc-indentation'>
<li><a href='#DeploymentInstructions-DockerTestbed'>Docker Testbed</a></li>
</ul>
</li>
</ul>
</li>
<li><a href='#DeploymentInstructions-DeploymentOptions'>Deployment Options</a>
<ul class='toc-indentation'>
<li><a href='#DeploymentInstructions-DeploymentviaDocker'>Deployment via Docker</a></li>
<li><a href='#DeploymentInstructions-DeploymentviaembeddedTomcatmode'>Deployment via embedded Tomcat mode</a></li>
<li><a href='#DeploymentInstructions-Deploymentviaexternalservletcontainer(Tomcat,Jettyetal)'>Deployment via external servlet container (Tomcat, Jetty et al)</a>
<ul class='toc-indentation'>
<li><a href='#DeploymentInstructions-ConfigureHTTPS'>Configure HTTPS</a></li>
</ul>
</li>
</ul>
</li>
<li><a href='#DeploymentInstructions-auth.optsAuthenticationOptions'>Authentication Options</a>
<ul class='toc-indentation'>
<li><a href='#DeploymentInstructions-Default-Single"root"user'>Default - Single "root" user</a></li>
<li><a href='#DeploymentInstructions-UsersDefinedviaFile'>Users Defined via File</a></li>
<li><a href='#DeploymentInstructions-UsersAuthenticatedviaShibbolethIDP'>Users Authenticated via Shibboleth IDP</a></li>
</ul>
</li>
<li><a href='#DeploymentInstructions-ConfigurationProperties'>Configuration Properties</a>
<ul class='toc-indentation'>
<li><a href='#DeploymentInstructions-DatabaseConfigurationviaapplication.yaml'>Database Configuration via application.yaml</a></li>
<li><a href='#DeploymentInstructions-app.propsapplication.propertiessettings'>application.properties settings</a></li>
<li><a href='#DeploymentInstructions-AdditionalConfigurationviaYAMLProperties'>Additional Configuration via YAML Properties</a>
<ul class='toc-indentation'>
<li><a href='#DeploymentInstructions-Attributes(forAttributeRelease)'>Attributes (for Attribute Release)</a>
<ul class='toc-indentation'>
<li><a href='#DeploymentInstructions-Defaultsattributes'>Defaults attributes</a></li>
</ul>
</li>
<li><a href='#DeploymentInstructions-RelyingPartyOverrides'>Relying Party Overrides</a>
<ul class='toc-indentation'>
<li><a href='#DeploymentInstructions-Defaultproperties'>Default properties</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a href='#DeploymentInstructions-StepstointegrateaSAML2basedIdPwithShibUI'>Steps to integrate a SAML2 based IdP with ShibUI</a>
<ul class='toc-indentation'>
<li><a href='#DeploymentInstructions-UsingTestbedEnvironment:'>Using Testbed Environment:</a></li>
<li><a href='#DeploymentInstructions-ShibUISetup'>ShibUI Setup</a></li>
<li><a href='#DeploymentInstructions-ShibbolethIdPSetup'>Shibboleth IdP Setup</a></li>
</ul>
</li>
<li><a href='#DeploymentInstructions-SuggestedSetupNote'>Suggested Setup Note</a></li>
<li><a href='#DeploymentInstructions-UserMaintenance'>User Maintenance</a></li>
<li><a href='#DeploymentInstructions-TAPBeaconinstrumentation'>TAP Beacon instrumentation</a></li>
</ul>
</div></p><p><br/></p><p>The SAML Metadata Configuration Manager (MCM) is built as a Java Spring Boot (<span> </span><a class="external-link" href="https://spring.io/projects/spring-boot" rel="nofollow">https://spring.io/projects/spring-boot</a><span> </span>) 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.</p><p>The MCM currently supports three distinct roles:</p><ul><li><strong>ROLE_ADMIN</strong><span> </span>-- No limits, can do anything the MCM supports. Currently, Metadata Provider configuration (and filter configuration) requires<span> </span><strong>ROLE_ADMIN</strong><span> </span>access</li><li><strong>ROLE_USER</strong><span> </span>-- These users can only add individual metadata sources (single entityID SP metadata file), and modify metadata sources that they created. And when creating a new SP entry, that SP metadata will not be active until after a user with<span> </span><strong>ROLE_ADMIN<span> </span></strong>approves it.</li><li><strong>ROLE_ENABLE</strong><span> </span>– These are "enhanced" ROLE_USER users that have the ability to<span> </span><strong>enable/publish</strong><span> </span>SP metadata but cannot access/configure Metadata Provider (and filter) configurations</li></ul><h1 id="DeploymentInstructions-Requirements">Requirements</h1><ul><li>The MCM requires a relational database for persistent storage. Out of the box you can run the application using an in memory database to get familiar with the application but you will need a permanent data store in order to retain configurations</li><li>Java 11+ - the Docker version of the deployment includes the needed Java environment to run the application</li></ul><h1 id="DeploymentInstructions-Downloads">Downloads</h1><ul><li>WAR releases available at:<span> </span><a class="external-link" href="https://github.internet2.edu/TIER/shib-idp-ui/releases" rel="nofollow">https://github.internet2.edu/TIER/shib-idp-ui/releases</a></li><li>Docker image available at:<span> </span><a class="external-link" href="https://hub.docker.com/r/i2incommon/shib-idp-ui/tags" rel="nofollow">https://hub.docker.com/r/i2incommon/shib-idp-ui/tags</a></li></ul><h1 id="DeploymentInstructions-ConfigurationNotes">Configuration Notes</h1><p>The following are some things that are useful to consider and know regardless of which deployment model you choose to go with.</p><p>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:</p><ul><li>A Spring property file – a simple text file with a property name, equals sign, and the property value, one per line. This file is named:<span> </span><em>application.properties</em></li><li>a YAML format file, named<span> </span><em>application.yml</em></li></ul><p>The MCM comes with basic examples of both types of properties files.</p><p>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.</p><p>The example application.yml file contains all the settings that impact the information, options, list elements, etc. that are actually shown in the UI.</p><p>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.</p><h2 id="DeploymentInstructions-DemoEnvironment">Demo Environment</h2><h3 id="DeploymentInstructions-DockerTestbed">Docker Testbed</h3><p>There are multiple "Testbed" environments that you can run that are available in the repository (in the testbed folder of the repository project). The instances include various database setups as simple examples of how to quickly run the application configured for each database (Maria, Postgres, SQL Server, MySQL).</p><p>There is also a fully integrated example in the testbed folder in the <strong>integration</strong><span> </span>folder. It includes the:</p><ul><li>SAML MCM</li><li>a Shibboleth IdP<ul><li>with a shared filesystem between the MCM and Shibboleth IdP</li></ul></li><li>an LDAP server as the base credential/attribute store for the IdP</li><li>a Postgres database image for the MCM's persistent database.</li></ul><p>To setup the "Testbed", you will need to:</p><ul><li>Create local DNS entries for idp.unicon.local and shibui.unicon.local pointing to 127.0.0.1. If you want to use other DNS names you can change the Host in the docker-compose.yml, <em>traefik.http.routers.idp.rule</em> and <em>traefik.http.routers.shibui.rule</em></li><li><p class="auto-cursor-target">Clone the repository:</p><div class="table-wrap"><table class="wrapped confluenceTable" style="text-align: left;"><tbody style="text-align: left;"><tr style="text-align: left;"><td style="text-align: left;" class="confluenceTd"><p style="text-align: left;"><code class="bash plain" style="text-align: left;">$> git clone https:</code><code class="bash plain" style="text-align: left;">//github</code><code class="bash plain" style="text-align: left;">.<a class="external-link" href="http://internet2.edu">internet2.edu</a></code><code class="bash plain" style="text-align: left;">/TIER/shib-idp-ui</code><code class="bash plain" style="text-align: left;">.git</code></p></td></tr></tbody></table></div></li></ul><ul><li><strong>cd</strong><span> </span>into<span> <em>shib-ui/</em></span><em>testbed/integration</em></li><li>Run the following command:<br/><code>docker compose up</code></li></ul><p>Once Docker has completed the startup of all containers you can access the SAML MCM login screen with the following URL:</p><pre><code>https://shibui.unicon.local
</code></pre><ul><li>Default userid = root</li><li>Default password = letmein7</li></ul><h1 id="DeploymentInstructions-DeploymentOptions">Deployment Options</h1><h2 id="DeploymentInstructions-DeploymentviaDocker">Deployment via Docker</h2><p>The Docker image of the SAML MCM follows the TIER Docker packaging standards, utilizing CentOS7, the Zulu JDK, supervisor, and the TIER Beacon configuration.</p><p>Basic usage:</p><p><br/></p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: java; gutter: false; theme: Confluence" data-theme="Confluence">docker run -p 8080:8080 -v <your local application.properties>:/opt/shibui/application.properties i2incommon/shib-idp-ui</pre>
</div></div><p><code><br class="auto-cursor-target"/></code>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.<span> </span></p><p>The current set of supported properties can be found <a href="#DeploymentInstructions-app.props">here</a>.</p><p>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: <span> </span><strong>Using generated security password:</strong>. The username is:<span> </span><strong>user</strong><code>
</code></p><h2 id="DeploymentInstructions-DeploymentviaembeddedTomcatmode">Deployment via embedded Tomcat mode</h2><p><span style="color: rgb(0,0,0);">The SAML MCM war file includes an embedded Tomcat mode allowing you to run the application without any external dependencies beyond your configuration overrides.</span></p><p><span style="color: rgb(0,0,0);">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 <a class="external-link" href="https://github.internet2.edu/TIER/shib-idp-ui/tree/master/testbed">repository</a>.</span></p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: java; gutter: false; theme: Confluence" data-theme="Confluence">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</pre>
</div></div><p>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 <a href="#DeploymentInstructions-auth.opts">here</a>.</p><p><br/></p><p>Then you will run the war and tell Spring Boot where to find the externalized<span> </span><strong>application.yml</strong>.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: java; gutter: false; theme: Confluence" data-theme="Confluence">java -Xmx1g -jar shibui-1.18.0.war --spring.config.additional-location=file:/etc/shibboleth-ui/</pre>
</div></div><p>You can then access the application on<span> </span><a class="external-link" href="http://localhost:8080/" rel="nofollow">http://localhost:8080</a> and login as root with the password you set in application.yml<br/><br/></p><h2 id="DeploymentInstructions-Deploymentviaexternalservletcontainer(Tomcat,Jettyetal)">Deployment via external servlet container (Tomcat, Jetty et al)</h2><p>This section describes how to deploy Shibboleth UI application as web archive with external configuration sources which override default configuration setting embedded in Shibboleth UI war to external Tomcat servlet container.</p><p>Shibboleth UI is a Spring Boot web application which supports all standard Spring Boot property sources and configuration options. So, let's assume that our external configuration directory is `/etc/shibboleth-ui`. 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 and then available to configure Shibboleth UI web application. All the standard Spring Boot property sources precedence rules apply here, but for our purposes we need to know that Shibboleth UI war deployed to external servlet container, embeds the set of default configuration properties on runtime classpath in `application.properties` file and then any standard property could be overridden by externalizing them in additional `application.properties` or `application.yml` files. So, back to our example, let's assume we use `/etc/shibboleth-ui/application.yml` file to run our Shibboleth UI application and connect to MariaDB RDBMS instead of a default embedded H2 database that is configured in `application.properties` embedded in shibui.war which would be deployed to external servlet container. The sample `/etc/shibboleth-ui/application.yml` containing properties to connect to MariaDB instance would look like this:</p><pre>shibui: <br/> default-password: "{noop}pass"<br/><br/>spring: <br/> datasource:<br/> platform: mysql<br/> driver-class-name: org.mariadb.jdbc.Driver<br/> url: jdbc:<a href="mariadb://localhost:3306/shibui" rel="nofollow">mariadb://localhost:3306/shibui</a><br/> username: shibui<br/> password: shibui<br/> jpa:<br/> properties:<br/> hibernate:<br/> dialect: org.hibernate.dialect.MariaDBDialect</pre><p>Then you would tell Spring Boot where to find externalized `application.yml`. That would be accomplished by passing `spring.config.additional-location` property. For Tomcat it could be accomplished in `$CATALINA_HOME/bin/setenv.sh` file like so:</p><p>`export JAVA_OPTS="$JAVA_OPTS -Dspring.config.additional-location=<a class="external-link" href="http://file/etc/shibboleth-ui/" rel="nofollow">file:/etc/shibboleth-ui/</a>"`</p><p>then deploy `shibui.war` to external Tomcat and then you could access application on `<a class="external-link" href="http://localhost:8080/" rel="nofollow">http://localhost:8080</a>` with `root/pass` username/password combination</p><p>So, now you could use externalized `/etc/shibboleth-ui/application.yml` file to override/configure any property available to Shibboleth UI web aplication independent of what is embedded in shibui.war deployed to external Tomcat container.</p><h3 id="DeploymentInstructions-ConfigureHTTPS">Configure HTTPS</h3><p>To deploy under HTTPS, if the external Tomcat is used, the standard configuration of Tomcat HTTP connector applies here. When deploying in the embedded Tomcat mode, in order to enable HTTPS, the following configuration properties (sample) should be used:</p><pre>server:<br/> ssl:<br/> key-store: /etc/shibui/keystore.p12<br/> key-store-password: password<br/> key-store-type: pkcs12<br/> key-alias: tomcat<br/> key-password: password<br/> port: 8443<br/><br/>Note that `keystore.p12` would contain a valid SSL certificate</pre><h1 id="DeploymentInstructions-auth.optsAuthenticationOptions"><span class="confluence-anchor-link" id="DeploymentInstructions-auth.opts"></span>Authentication Options</h1><p>One key decision that you will need to make is how to control authentication of users of the ShibUI. If you use the default user or a users file, note the following on defining passwords</p><p>Currently, the supported values for ENCRYPT_SCHEME are either:</p><ul><li>noop -- clear text password follows</li><li>bcrypt -- the following value has been encrypted with the $2a$ Bcrypt algorithm (limitation of the underlying Spring library currently incorporated is that only the<span> </span><a class="external-link" href="https://en.wikipedia.org/wiki/Bcrypt#Versioning_history" rel="nofollow">$2a$ Bcrypt algorithm<span> </span></a>is supported.)</li></ul><p>For more info on supported Spring Security's password storage formats, see: <a class="external-link" href="https://docs.spring.io/spring-security/site/docs/current/reference/htmlsingle/#pe-dpe-format" rel="nofollow">https://docs.spring.io/spring-security/site/docs/current/reference/htmlsingle/#pe-dpe-format</a></p><h2 id="DeploymentInstructions-Default-Single"root"user">Default - Single "root" user</h2><p><em>Simple, recommended only for secure environments (private networks available accessible via VPN or local access) with very limited user base (1-2 admin)</em></p><p>If you "do nothing", the ShibUI will set up a single "<strong>root</strong>" (that's the username) user, with a password it will generate the first time you run it. That password should be displayed in the console log as the UI 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.</p><p>application.properties:<span> </span><strong>shibui.default-password</strong><span> </span>= {ENCRYPT_SCHEME}password</p><h2 id="DeploymentInstructions-UsersDefinedviaFile">Users Defined via File</h2><p><em>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)</em></p><p>Obviously, you could start playing with the ShibUI, and even have multiple people use that same single root account. But likely just about any deployer is going to want to instead supply a "users file", and/or integrate your Shibboleth IdP as the authentication source.</p><p>Even if you are going to do the latter, you really need to "bootstrap" the Shibboleth IdP integration with at least a single user in that "users file". The reason for that is you need to establish at least one user who has the<span> </span><strong>ROLE_ADMIN</strong><span> </span>role.</p><p>The ShibUI application does support accepting the UI role for a user as an attribute from the Shibboleth IdP. If the IDP user information is not able to provide roles as listed above, you will need to configure a users file with at least one username (that will be passed from the IdP) listed with the ROLE_ADMIN role. You can configure the users file to have as many users as you want. The format of the users file is the following set of fields, separated by commas:</p><p><strong>username,{ENCRYPT_SCHEME}password,firstname,lastname,ROLE_VALUE,email</strong></p><div class="confluence-information-macro confluence-information-macro-information"><p class="title conf-macro-render">Example Users File</p><span class="aui-icon aui-icon-small aui-iconfont-info confluence-information-macro-icon"></span><div class="confluence-information-macro-body">dummy,{noop}password,first,last,ROLE_DUMMY,dummy@<a class="external-link" href="http://bill.com">bill.com</a><br/>admin,{noop}password,admin,admin,ROLE_ADMIN,admin@<a class="external-link" href="http://foo.com">foo.com</a><br/>user,{noop}password,some,user,ROLE_USER,user@<a class="external-link" href="http://foo.com">foo.com</a></div></div><p>The property name that is used to indicate users file is:</p><ul><li>shibui.user-bootstrap-resource = <a class="external-link" href="http://file/full/path/to/users/file.txt">file:/full/path/to/users/file.txt</a></li></ul><p>**(the name of the file does not matter)</p><p>Every time you restart the ShibUI, it will read in that file, and update the internal user database entries with any changes. Password is still a required field, but won't be used if your Shibboleth IdP is being used to authenticate your ShibUI users.</p><p>The property name that is used to indicate users file is:</p><ul><li>shibui.user-bootstrap-resource = <a class="external-link" href="http://file/full/path/to/users/file.txt">file:/full/path/to/users/file.txt</a></li></ul><p>**(the name of the file does not matter)</p><p>Every time you restart the ShibUI, it will read in that file, and update the internal user database entries with any changes. Password is still a required field, but won't be used if your Shibboleth IdP is being used to authenticate your ShibUI users.</p><h2 id="DeploymentInstructions-UsersAuthenticatedviaShibbolethIDP">Users Authenticated via Shibboleth IDP</h2><p><em>Recommended when a large volume of users needs to access the ShibUI or the application will be publicly accessible</em></p><p>Many deployers will presumably want to use their Shibboleth IdP for authentication. The ShibUI includes a Java-based SAML SP based on the Pac4j (<span> </span><a class="external-link" href="https://www.pac4j.org/" rel="nofollow">https://www.pac4j.org</a><span> </span>) library (SAML support built on top of the Shibboleth Consortium's OpenSAML software). This is pretty easy to configure, but it requires doing the following steps, before you start up the ShibUI.</p><ol><li>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)</li><li>Create a copy of the Shibboleth IdP's metadata, and place within the file system where the ShibUI can access</li><li>Configure the following settings in<span> </span><em>application.properties or application.yml</em>.</li></ol><p>Note: the settings for where Pac4j will store its SAML-related certificates (<span> </span><strong>shibui.pac4j.keystorePath</strong><span> </span>and related passwords) and SP metadata (<span> </span><strong>shibui.pac4j.serviceProviderMetadataPath</strong><span> </span>) will be the locations where you want Pac4j to store (it will self-generate files on first attempt to access.<span> </span><strong>These don't need to be existing files, it is easiest to let Pac4j do the generation for you.</strong>)</p><p><br/></p><p><br/></p><div class="table-wrap"><table class="wrapped confluenceTable" style="text-align: left;"><colgroup><col/></colgroup><tbody style="text-align: left;"><tr style="text-align: left;"><td style="text-align: left;" class="confluenceTd"><div class="content-wrapper"><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>application.properties config example</b></div><div class="codeContent panelContent pdl">
<pre class="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: java; gutter: false; theme: Confluence" data-theme="Confluence"># 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.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</pre>
</div></div></div></td></tr></tbody></table></div><p><br/><br/></p><div class="table-wrap"><table class="wrapped confluenceTable" style="text-align: left;"><colgroup><col/></colgroup><tbody style="text-align: left;"><tr style="text-align: left;"><td style="text-align: left;" class="confluenceTd"><div class="content-wrapper"><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>application.yml config example</b></div><div class="codeContent panelContent pdl">
<pre class="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: java; gutter: false; theme: Confluence" data-theme="Confluence">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
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</pre>
</div></div></div></td></tr></tbody></table></div><p><br/></p><p>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.</p><p>As the files you provided for SP keystore and metadata were "non-existent", Pac4j will generate those.<span> </span><strong>So now you will have a ShibUI SP metadata file (for ShibUI) that you can add to the IdP, and configure attribute release to the ShibUI entityID, matching up with the attribute mapping you configured above.</strong></p><p>Re-try to access the ShibUI dashboard again, and you should be "good to go".</p><p>The above process should work no matter what deployment model you choose. What will be different between the models is how the ShibUI interacts with the file system, and its expectations as to where various files will be found.</p><h1 id="DeploymentInstructions-ConfigurationProperties"><span>Configuration Properties</span></h1><h2 id="DeploymentInstructions-DatabaseConfigurationviaapplication.yaml"><span>Database Configuration via application.yaml</span></h2><p>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</p><p>Support for MySQL, Postgres, MariaDB, and SQL Server are available</p><div class="table-wrap"><table class="wrapped confluenceTable" style="text-align: left;"><colgroup><col/></colgroup><tbody style="text-align: left;"><tr style="text-align: left;"><td style="text-align: left;" class="confluenceTd"><div class="content-wrapper"><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>database configuration</b></div><div class="codeContent panelContent pdl">
<pre class="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: java; gutter: false; theme: Confluence" data-theme="Confluence">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</pre>
</div></div></div></td></tr></tbody></table></div><h2 id="DeploymentInstructions-app.propsapplication.propertiessettings"><span class="confluence-anchor-link" id="DeploymentInstructions-app.props"></span>application.properties settings</h2><p>This is a reflection of the default<span> </span><code>application.properties</code><span> </span>file included in the distribution. Note that lines beginning with<span> </span><code>#</code><span> </span>are commented out.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: java; gutter: false; theme: Confluence" data-theme="Confluence"># 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</pre>
</div></div><p><br/></p><h2 id="DeploymentInstructions-AdditionalConfigurationviaYAMLProperties">Additional Configuration via YAML Properties</h2><p><span class="conf-macro output-inline">The following properties may be customized through an `application.yml` file. </span></p><h3 id="DeploymentInstructions-Attributes(forAttributeRelease)">Attributes (for Attribute Release)</h3><p>Example:</p><p><strong>Attribute Release</strong></p><div class="table-wrap"><table class="wrapped confluenceTable" style="text-align: left;"><colgroup><col/></colgroup><tbody style="text-align: left;"><tr style="text-align: left;"><td style="text-align: left;" class="confluenceTd"><p style="text-align: left;"><code class="yml variable" style="text-align: left;">custom:</code><br/><code class="yml spaces" style="text-align: left;"> </code><code class="yml variable" style="text-align: left;">attributes:</code><br/><code class="yml spaces" style="text-align: left;"> </code><code class="yml string bold" style="text-align: left;">-</code><span> </span><code class="yml plain" style="text-align: left;">name</code><code class="yml constants" style="text-align: left;">:</code><span> </span><code class="yml plain" style="text-align: left;">eduPersonPrincipalName</code><br/><code class="yml spaces" style="text-align: left;"> </code><code class="yml variable" style="text-align: left;">displayName:</code><span> </span><code class="yml plain" style="text-align: left;">label.attribute-eduPersonPrincipalName</code><br/><code class="yml spaces" style="text-align: left;"> </code><code class="yml string bold" style="text-align: left;">-</code><span> </span><code class="yml plain" style="text-align: left;">name</code><code class="yml constants" style="text-align: left;">:</code><span> </span><code class="yml plain" style="text-align: left;">uid</code><br/><code class="yml spaces" style="text-align: left;"> </code><code class="yml variable" style="text-align: left;">displayName:</code><span> </span><code class="yml plain" style="text-align: left;">label.attribute-uid</code></p></td></tr></tbody></table></div><p><strong>name</strong>: The name of the entry. used to uniquely identify this entry.</p><p><strong>displayName</strong>: This will normally be the label used when displaying this override in the UI. (set in messages.properties)</p><h4 id="DeploymentInstructions-Defaultsattributes"><u>Defaults attributes</u></h4><ul><li><strong>eduPersonPrincipalName</strong>: label.attribute-eduPersonPrincipalName</li><li><strong>uid</strong>: label.attribute-uid</li><li><strong>mail</strong>: label.attribute-mail</li><li><strong>surname</strong>: label.attribute-surname</li><li><strong>givenName</strong>: label.attribute-givenName</li><li><strong>eduPersonAffiliation</strong>: label.attribute-eduPersonAffiliation</li><li><strong>eduPersonScopedAffiliation</strong>: label.attribute-eduPersonScopedAffiliation</li><li><strong>eduPersonPrimaryAffiliation</strong>: label.attribute-eduPersonPrimaryAffiliation</li><li><strong>eduPersonEntitlement</strong>: label.attribute-eduPersonEntitlement</li><li><strong>eduPersonAssurance</strong>: label.attribute-eduPersonAssurance</li><li><strong>eduPersonUniqueId</strong>: label.attribute-eduPersonUniqueId</li><li><strong>employeeNumber</strong>: label.attribute-employeeNumber</li></ul><h3 id="DeploymentInstructions-RelyingPartyOverrides">Relying Party Overrides</h3><div class="confluence-information-macro confluence-information-macro-information"><span class="aui-icon aui-icon-small aui-iconfont-info confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>Note: The <code>application.yml</code> 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 <code>application.yml</code> file will be ignored in favor of the configuration in the database. Adding overrides to the <code>application.yml</code> file is not recommended unless you have a large number of overrides to add all at once. </p></div></div><p>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".</p><p>Example:<br/><strong>Relying Party Overrides</strong></p><div class="table-wrap"><table class="wrapped confluenceTable" style="text-align: left;"><colgroup><col/></colgroup><tbody style="text-align: left;"><tr style="text-align: left;"><td style="text-align: left;" class="confluenceTd"><div class="content-wrapper"><p style="text-align: left;"><br/></p><p style="text-align: left;"><br/></p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: java; gutter: false; theme: Confluence" data-theme="Confluence">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</pre>
</div></div><p style="text-align: left;"><br/></p><p style="text-align: left;"><br/></p></div></td></tr></tbody></table></div><p><strong>name:<span> </span></strong>The name of the entry. used to uniquely identify this entry.</p><p><strong>displayName</strong>: This will normally be the label used when displaying this override in the UI. (set in messages.properties)</p><p><strong>displayType:</strong> The type to use when displaying this option</p><p><strong>defaultValue(s)</strong>: One or more values to be displayed as default options in the UI</p><p><strong>helpText</strong>: This is the help-icon hover-over text</p><p><strong>attributeName</strong>: This is the name of the attribute to be used in the xml. This is assumed to be a URI.</p><p><strong>attributeFriendlyName</strong>: This is the friendly name associated with the above attributeName.</p><p><strong>invert</strong>: </p><p><strong>persistType</strong>: 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.</p><p><strong>persistValue</strong>: Required only when persistType is used. Defines the value to be persisted.</p><h4 id="DeploymentInstructions-Defaultproperties"><u>Default properties</u></h4><ul><li><strong>signAssertion</strong><br/>displayName: label.sign-the-assertion<br/>displayType: boolean<br/>defaultValue: false<br/>helpText: tooltip.sign-assertion<br/>attributeName:<span> </span><a class="external-link" href="http://shibboleth.net/ns/profiles/saml2/sso/browser/signAssertions" rel="nofollow" style="text-decoration: none;">http://shibboleth.net/ns/profiles/saml2/sso/browser/signAssertions</a><br/>attributeFriendlyName: signAssertions</li><li><strong>dontSignResponse</strong><br/>displayName: label.dont-sign-the-response<br/>displayType: boolean<br/>defaultValue: false<br/>helpText: tooltip.dont-sign-response<br/>attributeName:<span> </span><a class="external-link" href="http://shibboleth.net/ns/profiles/saml2/sso/browser/signResponses" rel="nofollow" style="text-decoration: none;">http://shibboleth.net/ns/profiles/saml2/sso/browser/signResponses</a><br/>attributeFriendlyName: signResponses<br/>invert: true</li><li><strong>turnOffEncryption</strong><br/>displayName: label.turn-off-encryption-of-response<br/>displayType: boolean<br/>defaultValue: false<br/>helpText: tooltip.turn-off-encryption<br/>attributeName:<span> </span><a class="external-link" href="http://shibboleth.net/ns/profiles/encryptAssertions" rel="nofollow" style="text-decoration: none;">http://shibboleth.net/ns/profiles/encryptAssertions</a><br/>attributeFriendlyName: encryptAssertions<br/>invert: true</li><li><strong>useSha</strong><br/>displayName: label.use-sha1-signing-algorithm<br/>displayType: boolean<br/>defaultValue: false<br/>helpText: tooltip.usa-sha-algorithm<br/>persistType: string<br/>persistValue: shibboleth.SecurityConfiguration.SHA1<br/>attributeName:<span> </span><a class="external-link" href="http://shibboleth.net/ns/profiles/securityConfiguration" rel="nofollow" style="text-decoration: none;">http://shibboleth.net/ns/profiles/securityConfiguration</a><br/>attributeFriendlyName: securityConfiguration</li><li> <strong>ignoreAuthenticationMethod</strong><br/>displayName: label.ignore-any-sp-requested-authentication-method<br/>displayType: boolean<br/>defaultValue: false<br/>helpText: tooltip.ignore-auth-method<br/>persistType: string<br/>persistValue: 0x1<br/>attributeName:<span> </span><a class="external-link" href="http://shibboleth.net/ns/profiles/disallowedFeatures" rel="nofollow" style="text-decoration: none;">http://shibboleth.net/ns/profiles/disallowedFeatures</a><br/>attributeFriendlyName: disallowedFeatures</li><li><strong>omitNotBefore</strong><br/>displayName: label.omit-not-before-condition<br/>displayType: boolean<br/>defaultValue: false<br/>helpText: tooltip.omit-not-before-condition<br/>attributeName:<span> </span><a class="external-link" href="http://shibboleth.net/ns/profiles/includeConditionsNotBefore" rel="nofollow" style="text-decoration: none;">http://shibboleth.net/ns/profiles/includeConditionsNotBefore</a><br/>attributeFriendlyName: includeConditionsNotBefore<br/>invert: true</li><li><strong>responderId</strong><br/>displayName: label.responder-id<br/>displayType: string<br/>defaultValue: null<br/>helpText: tooltip.responder-id<br/>attributeName:<span> </span><a class="external-link" href="http://shibboleth.net/ns/profiles/responderId" rel="nofollow" style="text-decoration: none;">http://shibboleth.net/ns/profiles/responderId</a><br/>attributeFriendlyName: responderId</li><li><strong>nameIdFormats</strong><br/>displayName: label.nameid-format-to-send<br/>displayType: set<br/>helpText: tooltip.nameid-format<br/>defaultValues:<br/>- urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified<br/>- urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress<br/>- urn:oasis:names:tc:SAML:2.0:nameid-format:persistent<br/>- urn:oasis:names:tc:SAML:2.0:nameid-format:transient<br/>attributeName:<span> </span><a class="external-link" href="http://shibboleth.net/ns/profiles/nameIDFormatPrecedence" rel="nofollow" style="text-decoration: none;">http://shibboleth.net/ns/profiles/nameIDFormatPrecedence</a><br/>attributeFriendlyName: nameIDFormatPrecedence</li><li><strong>authenticationMethods</strong><br/>displayName: label.authentication-methods-to-use<br/>displayType: set<br/>helpText: tooltip.authentication-methods-to-use<br/>defaultValues:<br/>-<span> </span><a class="external-link" href="https://refeds.org/profile/mfa" rel="nofollow" style="text-decoration: none;">https://refeds.org/profile/mfa</a><br/>- urn:oasis:names:tc:SAML:2.0:ac:classes:TimeSyncToken<br/>- urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport<br/>attributeName:<span> </span><a class="external-link" href="http://shibboleth.net/ns/profiles/defaultAuthenticationMethods" rel="nofollow" style="text-decoration: none;">http://shibboleth.net/ns/profiles/defaultAuthenticationMethods</a><br/>attributeFriendlyName: defaultAuthenticationMethods</li><li><strong>forceAuthn</strong><br/>displayName: label.force-authn<br/>displayType: boolean<br/>defaultValue: false<br/>helpText: tooltip.force-authn<br/>attributeName:<span> </span><a class="external-link" href="http://shibboleth.net/ns/profiles/forceAuthn" rel="nofollow" style="text-decoration: none;">http://shibboleth.net/ns/profiles/forceAuthn</a><br/>attributeFriendlyName: forceAuthn</li></ul><h1 id="DeploymentInstructions-StepstointegrateaSAML2basedIdPwithShibUI">Steps to integrate a SAML2 based IdP with ShibUI</h1><p>Note: be sure to read through the Authentication options above, they provide some details that apply regardless of the deployment option you have chosen.</p><h2 id="DeploymentInstructions-UsingTestbedEnvironment:">Using Testbed Environment:</h2><p>We will be using the Docker Testbed environment for this working demo. The Testbed is included in the source project. Please make sure you have already deployed the Testbed environment and<br/>verified it is working:</p><ul><li>Verify can log into ShibUI via<span> </span><a class="external-link" href="http://localhost:8080/" rel="nofollow">http://localhost:8080</a></li><li>Verify Shibboleth is running by accessing metadata page for Shibboleth instance<span> </span><a class="external-link" href="https://localhost/idp/shibboleth" rel="nofollow">https://localhost:443/idp/shibboleth</a><br/>We will be needing this metadata info later, so feel free to save to a file now. <pre>curl -k <a class="external-link" href="https://localhost/idp/shibboleth" rel="nofollow">https://localhost:443/idp/shibboleth</a> --output <ShibUI Root>/test-compose/shibui/conf/idp_metadata.xml</pre></li></ul><p>You will need to stop the Docker containers before continuing in the next section:</p><pre>docker-compose down</pre><h2 id="DeploymentInstructions-ShibUISetup">ShibUI Setup</h2><p>We will be using the Pac4j's library for SAML2 support in ShibUI. This will be easy to implement since ShibUI uses a pluggable architecture.</p><p>To enable Pac4j, open and update the following files:</p><ul><li><em>test-compose/shibui/conf/applications.properties:</em><pre>shibui.pac4j-enabled=true</pre></li><li><em>test-compose/shibui/conf/applications.yml:</em><br/>* Under ShibUI section add:<pre> pac4j-enabled: true<br/> pac4j:<br/> keystorePath: "/etc/opt/samlKeystore.jks"<br/> keystorePassword: "changeit"<br/> privateKeyPassword: "changeit"<br/> serviceProviderEntityId: "<a class="external-link" href="https://idp.example.com/shibui" rel="nofollow">https://idp.example.com/shibui</a>"<br/> serviceProviderMetadataPath: "/etc/opt/sp-metadata.xml"<br/> identityProviderMetadataPath: "/etc/opt/idp-metadata.xml"<br/> forceServiceProviderMetadataGeneration: false<br/> callbackUrl: "<a class="external-link" href="https://localhost:8443/callback" rel="nofollow">https://localhost:8443/callback</a>"<br/> maximumAuthenticationLifetime: 3600000<br/> simpleProfileMapping:<br/> username: urn:oid:0.9.2342.19200300.100.1.1<br/> firstname: urn:oid:2.5.4.42<br/> lastname: urn:oid:2.5.4.4<br/> email: urn:oid:0.9.2342.19200300.100.1.3</pre><pre><br/></pre><ul><li>Key fields:<ul><li><strong>keystorePath</strong>: URL to an existing or newly created keystore. Create or move keystore to <em>test-compose/shibui/conf/.</em><br/>Create command:<br/><em>keytool -genkeypair -alias pac4j -keypass changeit -keystore samlKeystore.jks -storepass changeit -keyalg RSA -keysize 2048 -validity 3650</em></li><li><strong>serviceProviderEntityId</strong>: Entity ID of ShibUI</li><li><strong>serviceProviderMetadataPath</strong>: Location of where you want SP metadata file to be created</li><li><strong>identityProviderMetadataPath</strong>: Location of saved Shibb IdP metadata file (saved earlier when verifying Testbed environment)</li><li><strong>simpleProfileMapping</strong>: Attributes needed by ShibUI to work with SAML2 IdP</li></ul></li></ul></li></ul><p>Make sure the keystore file, idp metadata file, and both application files are moved to the ShibUI container when started:</p><ul><li>test-compose/docker-compose.yml:<br/>under shibui: volumes:<br/><pre>- ./shibui/conf/application.yml:/opt/shibui/application.yml<br/>- ./shibui/conf/samlKeystore.jks:/opt/shibui/samlKeystore.jks<br/>- ./shibui/conf/application.properties:/opt/shibui/application.properties<br/>- ./shibui/conf/idp-metadata.xml:/opt/shibui/idp-metadata.xml</pre></li></ul><p>Now run Docker:</p><pre>docker-compose up</pre><p>When the Docker containers are running, you will need to log into the ShibUI container and copy the newly created sp-metadata.xml file to a new <em>test-compose/idp/container-files/services/sp-metadata.xml</em><span> </span>file. </p><p>Once this is complete, add the following to the<span> </span><em>test-compose/idp/Dockerfile</em>:</p><pre><span style="color: rgb(204,120,50);">COPY </span>container-files<span style="color: rgb(204,120,50);">/</span>services<span style="color: rgb(204,120,50);">/</span>sp-metadata.xml <span style="color: rgb(204,120,50);">/</span>opt<span style="color: rgb(204,120,50);">/</span>shibboleth-idp<span style="color: rgb(204,120,50);">/</span>metadata<span style="color: rgb(204,120,50);">/</span>sp-metadata.xml</pre><h2 id="DeploymentInstructions-ShibbolethIdPSetup">Shibboleth IdP Setup</h2><p>At this point you will need to add the ShibUI application as a new SP to Shibboleth IdP. The files you will need to update are located at<span> </span><em>test-compose/idp/container-files/conf/. <span> </span></em>It is assumed that you understand adding a new SP to your Shibboleth IDP</p><h1 id="DeploymentInstructions-SuggestedSetupNote">Suggested Setup Note</h1><p>The following suggested setup will allow you to configure the generation of configuration from the ShibUI to be ingested for use in your Shibboleth IDP with the minimal amount of effort.</p><ol><li>In your application properties, configure:<span> </span><strong>shibui.metadataProviders.target</strong><span> </span>- 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 -<span> </span><strong><a class="external-link" href="http://file/opt/shibboleth/config/dynamic_config/metadata-providers.xml">file:/opt/shibboleth/config/dynamic_config/metadata-providers.xml</a></strong></li><li>In your application properties, configure:<span> </span><strong>shibui.metadata-dir</strong><span> </span>- 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 -<span> </span><strong>/opt/shibboleth/config/dynamic_metadata</strong></li><li>In your Shibboleth configuration's services.xml file, update the block for shibboleth.MetadataResolverResources to include the shibui.metadataProviders.target location </li></ol><p><br/><br/><strong>example</strong></p><div class="table-wrap"><table class="wrapped confluenceTable" style="text-align: left;"><colgroup><col/></colgroup><tbody style="text-align: left;"><tr style="text-align: left;"><td style="text-align: left;" class="confluenceTd"><p style="text-align: left;"><code class="xml plain" style="text-align: left;"><</code><code class="xml keyword" style="text-align: left;">util:list</code><span> </span><code class="xml color1" style="text-align: left;">id</code><code class="xml plain" style="text-align: left;">=</code><code class="xml string" style="text-align: left;">"shibboleth.MetadataResolverResources"</code><code class="xml plain" style="text-align: left;">></code><br/><code class="xml spaces" style="text-align: left;"> </code><code class="xml plain" style="text-align: left;"><</code><code class="xml keyword" style="text-align: left;">value</code><code class="xml plain" style="text-align: left;">>%{idp.home}/conf/metadata-providers.xml</</code><code class="xml keyword" style="text-align: left;">value</code><code class="xml plain" style="text-align: left;">></code><br/><code class="xml spaces" style="text-align: left;"> </code><code class="xml plain" style="text-align: left;"><</code><code class="xml keyword" style="text-align: left;">value</code><code class="xml plain" style="text-align: left;">>%{idp.home}/system/conf/metadata-providers-system.xml</</code><code class="xml keyword" style="text-align: left;">value</code><code class="xml plain" style="text-align: left;">></code><br/><code class="xml spaces" style="text-align: left;"> </code><code class="xml plain" style="text-align: left;"><</code><code class="xml keyword" style="text-align: left;">value</code><code class="xml plain" style="text-align: left;">>${idp.home}/conf/dynamic_config/metadata-providers.xml</</code><code class="xml keyword" style="text-align: left;">value</code><code class="xml plain" style="text-align: left;">><span> </span></code><code class="xml comments" style="text-align: left;"><!-- match the shibui.metadataProviders.target value --></code><br/><code class="xml plain" style="text-align: left;"></</code><code class="xml keyword" style="text-align: left;">util:list</code><code class="xml plain" style="text-align: left;">></code></p></td></tr></tbody></table></div><p>Shibboleth will require a restart to pick up the change.</p><p>Once ShibUI is up and running, login as an admin user and create a new Metadata Provider (type:<span> </span><strong>LocalDynamicMetadataResolver</strong>). Use the shibui.metadata-dir location from step 2 above as the directory location. </p><p>The dynamic provider will provide Shibboleth with the location of any SP configured using the ShibUI. </p><p>*NOTE: you can use the testbed/integration setup in the project source code to test how this integration works and to see an example of the full end-to-end workings of the ShibUi and Shibboleth IDP</p><h1 id="DeploymentInstructions-UserMaintenance">User Maintenance</h1><h1 id="DeploymentInstructions-TAPBeaconinstrumentation">TAP Beacon instrumentation</h1><p>Shibboleth Idp UI 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: <a class="external-link" href="https://spaces.at.internet2.edu/display/TWGH/TIER+Instrumentation+-+The+TIER+Beacon" rel="nofollow">https://spaces.at.internet2.edu/display/TWGH/TIER+Instrumentation+-+The+TIER+Beacon</a> 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:</p><p><strong>shibui.beacon-enabled=true</strong><br/><br/>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:<br/><br/><strong>LOGHOST="<a class="external-link" href="https://collector.testbed.tier.internet2.edu/" rel="nofollow">https://collector.testbed.tier.internet2.edu</a>"</strong><br/><strong>LOGPORT="5001"</strong><br/><strong>IMAGE="shibui_local_no_image"</strong><br/><strong>MAINTAINER="local_no_maintainer"</strong><br/><strong>VERSION="1.11.0-SNAPSHOT"</strong><br/><strong>TIERVERSION="191010"</strong></p><p><br/><br/><a class="external-link" href="https://confluence.unicon.net/confluence/display/ProServ/Shibboleth+IdP+UI+Deployment+Instructions" style="text-decoration: none;"><span class="like-button-text">Like</span></a> <span style="text-align: right;letter-spacing: 0.0px;">No labels</span></p><ul class="label-list label-list-right has-pen" style="text-align: right;"><li class="labels-edit-container"><a class="external-link" href="https://confluence.unicon.net/confluence/display/ProServ/Shibboleth+IdP+UI+Deployment+Instructions" style="text-decoration: none;" title="Edit Labels (Type 'l')"><span class="aui-icon aui-icon-small aui-iconfont-devtools-tag-small" style="color: rgb(80,95,121);">Edit Labels</span></a></li></ul><p><br/></p><p class="comment-user-logo"><a class="external-link" href="https://confluence.unicon.net/confluence/users/profile/editmyprofilepicture.action" style="text-decoration: none;" title=""><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image userLogo logo defaultLogo confluence-external-resource" draggable="false" src="https://confluence.unicon.net/confluence/s/pipxsy/8505/f5e71ce5e7eab96b69c873705d53960b71f86fff/_/images/icons/profilepics/add_profile_pic.svg" data-image-src="https://confluence.unicon.net/confluence/s/pipxsy/8505/f5e71ce5e7eab96b69c873705d53960b71f86fff/_/images/icons/profilepics/add_profile_pic.svg"></span></a></p><p><span>Write a comment...</span></p>
</div>
<div style="padding: 10px 0;">
<a href="https://spaces.at.internet2.edu/display/SMMU/Deployment+Instructions">View Online</a>
·
<a href="https://spaces.at.internet2.edu/pages/diffpagesbyversion.action?pageId=172263803&revisedVersion=12&originalVersion=11">View Changes Online</a>
</div>
</div>sean.porth@at.internet2.edu2020-09-10T17:08:42Z