...
- This guide assumes that uApprove JP is installed on a Linux system. It’s also possible to install it on a different operating system, like Windows. In this case, you may need to adapt some paths and commands accordingly.
- The guide shows paths and commands using variables like, e.g.
$IDP_INSTALL$
,$IDP_HOME$
or$UAPPROVE_INSTALL$
. You need to substitute these variables by the real paths, except where it is explicitly stated that you don’t need to substitute them.
...
Table of Contents
目次 | ||
---|---|---|
|
Assumptions
- The Shibboleth Identity Provider is unpacked at
$IDP_INSTALL$
(e.g.,/usr/local/src/shibboleth-identity-provider-#version#
). - The Shibboleth Identity Provider is installed at
$IDP_HOME$
(e.g.,/opt/shibboleth-idp
). - Tomcat is installed at
$CATALINA_HOME$
(e.g.,/usr/java/tomcat
). - uApprove JP is downloaded and unpacked at
$UAPPROVE_INSTALL$
(e.g.,/usr/local/src/uApproveJP-#version#
).
1 Installation
1.1 Prerequisites
- Shibboleth Identity Provider 2.4.0 or later.
- MySQL 5.1 or later.
1.2 Library Installation
Copying the libraries to the IdPs library directory:
...
注意 |
---|
Assure that only one version of each library is present in |
1.3 Configuration Template
Copying the configuration template to the IdPs configuration directory:
書式設定済み |
---|
# cp $UAPPROVE_INSTALL$/manual/configuration/uApprove.properties $IDP_HOME$/conf # cp $UAPPROVE_INSTALL$/manual/configuration/uApprove.xml $IDP_HOME$/conf |
1.4 Webapp files
Copying of the web application files like the JSPs, CSS files and images to the IdPs webapp directory:
書式設定済み |
---|
# mkdir $IDP_INSTALL$/src/main/webapp/uApprove # cp $UAPPROVE_INSTALL$/webapp/* $IDP_INSTALL$/src/main/webapp/uApprove |
1.5 Database Preparation
注意 |
---|
The following database parameters are examples. Adapt the values as required. Especially, choose a secure password. |
- Create a database with the name “uApprove”.
- Create a database user with the username “uApprove” and password “secret”.
- Grant
INSERT, SELECT, UPDATE, DELETE
rights for the user. - Create the initial table structures using the schemas:
$UAPPROVE_INSTALL$/manual/storage/terms-of-use-schema.sql
$UAPPROVE_INSTALL$/manual/storage/attribute-release-schema.sql
$UAPPROVE_INSTALL$/manual/storage/service-access-data-schema.sql
2 Basic Deployment
2.1 Web Application Deployment Descriptor
Extend the IdP web application deployment descriptor ( $IDP_INSTALL$/src/main/webapp/WEB-INF/web.xml
). Adapt your existing file as shown below.
...
コード ブロック | ||
---|---|---|
| ||
<web-app ...> <context-param> <param-name>contextConfigLocation</param-name> <param-value>$IDP_HOME$/conf/internal.xml; $IDP_HOME$/conf/service.xml; $IDP_HOME$/conf/uApprove.xml;</param-value> </context-param> <!-- IdP Listeners, Filters and Servlets --> <!-- ... --> <!-- uApprove Filter and Servlets --> <filter> <filter-name>uApprove</filter-name> <filter-class>ch.SWITCH.aai.uApprove.Intercepter</filter-class> </filter> <filter-mapping> <filter-name>uApprove</filter-name> <url-pattern>/profile/Shibboleth/SSO</url-pattern> <url-pattern>/profile/SAML1/SOAP/AttributeQuery</url-pattern> <url-pattern>/profile/SAML1/SOAP/ArtifactResolution</url-pattern> <url-pattern>/profile/SAML2/POST/SSO</url-pattern> <url-pattern>/profile/SAML2/POST-SimpleSign/SSO</url-pattern> <url-pattern>/profile/SAML2/Redirect/SSO</url-pattern> <url-pattern>/profile/SAML2/Unsolicited/SSO</url-pattern> <url-pattern>/Authn/UserPassword</url-pattern> </filter-mapping> <servlet> <servlet-name>uApprove - Terms Of Use</servlet-name> <servlet-class>ch.SWITCH.aai.uApprove.tou.ToUServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>uApprove - Terms Of Use</servlet-name> <url-pattern>/uApprove/TermsOfUse</url-pattern> </servlet-mapping> <servlet> <servlet-name>uApprove - Attribute Release</servlet-name> <servlet-class>ch.SWITCH.aai.uApprove.ar.AttributeReleaseServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>uApprove - Attribute Release</servlet-name> <url-pattern>/uApprove/AttributeRelease</url-pattern> </servlet-mapping> </web-app> |
2.2 Custom of Configuration
Modify IdP at $IDP_HOME$/conf/internal.xml
. Add id="uajpMetadataExtensions"
bean definition in <constructor-arg>
element in id="shibboleth.OpensamlConfig"
bean definition as below:
...
- Adapt
$IDP_HOME$/conf/terms-of-use.html
as required. Adapt the value of
tou.resource
in$IDP_HOME$/conf/uApprove.properties
accordingly:書式設定済み tou.resource = file:$IDP_HOME$/conf/terms-of-use.html
2.3 Custom Templates
In case you want to customize the templates, follow section Custom View Templates.
At least, you should copy your organization’s logo to the file $IDP_INSTALL$/src/main/webapp/uApprove/logo.png
, since a placeholder logo is installed by default.
You may also want to put your federation’s logo to the file $IDP_INSTALL$/src/main/webapp/uApprove/federation-logo.png
(which is an empty placeholder logo by default).
ヒント | |||||
---|---|---|---|---|---|
The logo is very large so that you may adjust the size using height, width in
|
2.4 Deployment
To activate uApprove JP the IdP must be re-deployed:
...
書式設定済み |
---|
# service tomcat6 restart |
3 Upgrade
3.1 Upgrade from uApprove.jp 2.2.1
注意 |
---|
You have to completely remove this old version first and perform a clean install. Please have a look at 1 Installation above for further information on how to install uApprove. |
...
Configuration files: Please use the new configuration file and tailor them to your needs.
ヒント The new ToU is an HTML file, which you can customize, just copy the content from your legacy ToU XML to a plain HTML file.
- uajpmf:AttributeUapprove matching rules: You cannot use anymore. Please rewrite rules using uajpmf:AttributeInMetadata instead. Please refer to 4.7 Attribute In Attribute Requester's Metadata Plugin for further information.
...
- JSP: Please use the new provided JSP files. If you use 4.1 Reset Attribute Release Consent, please adjust your
login.jsp
. - Database Migration: It is impossible to migrate.
4 Advanced Deployment
This section contains advanced configuration topics.
4.1 Reset Attribute Release Consent
For providing the feature that a user is able to clear 1 her attribute release consent during the login flow, add a checkbox to $IDP_INSTALL$/src/main/webapp/login.jsp
:
...
1 Clear means to delete general consent if it was given as well delete as all attribute release consents for the accessed relying party.
4.2 Storage
File-only
For a simple deployment a file only database can be used. HSQL provides such an option.
Define the according database properties in uApprove.properties
:
...
注意 |
---|
Assure that the user running the container (e.g., Jetty) has write permission to the db directory. |
Custom SQL Statements
- Copy the provided
$UAPPROVE_INSTALL$/manual/storage/sql-statements.properties
to$IDP_HOME$/conf/uApprove.sql-statements.properties
. - Adjust
$IDP_HOME$/conf/uApprove.sql-statements.properties
according your needs. Enable your custom
sql-statements.properties
in$IDP_HOME$/conf/uApprove.xml
:コード ブロック language xml <bean id="uApprove.touModule" class="ch.SWITCH.aai.uApprove.tou.ToUModule" ...> <!-- ... --> <property name="storage"> <bean class="ch.SWITCH.aai.uApprove.tou.storage.JDBCStorage" ... p:sqlStatements="file:/$IDP_HOME$/conf/uApprove.sql-statements.properties" ... /> </property> </bean> <!-- ... --> <bean id="uApprove.attributeReleaseModule" class="ch.SWITCH.aai.uApprove.ar.AttributeReleaseModule" ...> <!-- ... --> <property name="storage"> <bean class="ch.SWITCH.aai.uApprove.ar.storage.JDBCStorage" ... p:sqlStatements="file:/$IDP_HOME$/conf/uApprove.sql-statements.properties" ... /> </property> </bean>
Graceful JDBC Connection Handling
The JDBC storage can be configured to act graceful in case of a temporary database issue (e.g., communication link is not available). Instead throwing exceptions and display the error page, no persistent actions are applied.
This implies that the users, independently of former ToU acceptances and/or attribute release consents have to accept/consent again (if they already had) or have to do it during the next login (if it was the first time).
...
コード ブロック | ||
---|---|---|
| ||
<bean id="uApprove.touModule" class="ch.SWITCH.aai.uApprove.tou.ToUModule" ...> <!-- ... --> <property name="storage"> <bean class="ch.SWITCH.aai.uApprove.tou.storage.JDBCStorage" ... p:graceful="true" ... /> </property> </bean> <!-- ... --> <bean id="uApprove.attributeReleaseModule" class="ch.SWITCH.aai.uApprove.ar.AttributeReleaseModule" ...> <!-- ... --> <property name="storage"> <bean class="ch.SWITCH.aai.uApprove.ar.storage.JDBCStorage" ... p:graceful="true" ... /> </property> </bean> |
JDBC Connection Pool Tuning
情報 |
---|
|
...
ヒント |
---|
You are free to use another JDBC connection pooling library (e.g., BoneCP). Just provide the right data source class name in the bean definition as well the required libraries in the classpath. |
4.3 Templates
Custom View Templates
Feel free to customize the JSP, CSS and image files located in $IDP_INSTALL$/src/main/webapp/uApprove/
.
For convenience the JSTL is used, cf. JSTL reference.
4.4 Localization
Custom Messages
You might adjust/extend the provided resource bundles in $UAPPROVE_INSTALL$/manual/examples/messages
and copy them into the IdPs classpath (e.g., $IDP_INSTALL$/src/main/webapp/WEB-INF/classes/uApprove/messages
).
Specify your bundles base in $IDP_HOME$/conf/uApprove.xml
:
...
書式設定済み |
---|
# cd $UAPPROVE_INSTALL$/manual/examples/messages (Edit attribute-release_ja-UTF8.properties) # native2ascii attribute-release_ja-UTF8.properties attribute-release_ja.properties # cp attribute-release_ja.properties $IDP_INSTALL$/src/main/webapp/WEB-INF/classes/uApprove/messages/ |
Attribute Names and Descriptions
See $UAPPROVE_INSTALL$/manual/examples/attribute-descriptions.xml
for an example how to configure the localized attribute names and descriptions.
Relying Party Names and Descriptions
Currently only <AttributeConsumingService>
element in metadata is supported to retrieve localized relying party names and descriptions.
For providing such names and descriptions extend the metadata for the SP like:
...
ヒント |
---|
The metadata of the SWITCHaai federation contain these information. |
4.5 Strict Comparison
Terms Of Use Content Comparison
In the default configuration, only the ToU version is compared to evaluate if a user accepted the ToU. You might enable that the ToU content is compared too in $IDP_HOME$/conf/uApprove.xml
:
コード ブロック | ||
---|---|---|
| ||
<bean id="uApprove.touModule" ... p:compareContent="true" ... /> |
4.6 Audit Logging
uApprove JP allows (facilitating the IdP’s audit log) to enable audit logging to $IDP_HOME$/logs/idp-audit.log
.
Enable Terms Of Use Audit Log
You might enable ToU audit log in $IDP_HOME$/conf/uApprove.xml
:
...
書式設定済み |
---|
20120101T010000Z|ch.SWITCH.aai.uApprove|||tou.acceptance|null|null|null|student1||1.0,5b2ee897c08c79a09cd57e8602d605bf8c52db17de9793677c36b5c78644b2b3,| |
Enable Attribute Release Audit Log
You might enable attribute release audit log in $IDP_HOME$/conf/uApprove.xml
:
...
書式設定済み |
---|
20120101T010000Z|ch.SWITCH.aai.uApprove||https://sp.example.org/shibboleth|ar.consent|null|null|null|student1||uid,surname,givenName,| 20120101T010000Z|ch.SWITCH.aai.uApprove||https://sp.example.org/shibboleth|ar.clearConsent|null|null|null|student1||| 20120101T010000Z|ch.SWITCH.aai.uApprove|||ar.generalConsent|null|null|null|student1||| |
4.7 Attribute In Attribute Requester’s Metadata Plugin
Configuration Attribute In Requester's Metadata Matching Rule
This rule allows the release of an attribute if, via its metadata, the SP indicates a need/desire for the attribute. The attributes are indicated by means of <AttributeConsumingService>
element within the<SPSSODescriptor>
element. Attributes with isRequired='true'
at <RequestedAttribute>
is marked as required, and with isRequired='false'
is marked as optional. See SAML metadata for more information.
注意 |
---|
Please be aware of the following:
|
Define the Namespace
In your attribute filter policy file you’ll need to add the namespace declaration for this plugin. To do this:
- Add the attribute
xmlns:uajpmf="http://www.gakunin.jp/ns/uapprove-jp/afp/mf"
before thexmlns:xsi
attribute on the root<AttributeFilterPolicyGroup>
element. - Add the following at the end of the whitespace delimited list of values for the
xsi:schemaLocation
attribute:http://www.gakunin.jp/ns/uApprove-jp/afp/mf classpath:/schema/shibboleth-2.0-afp-mf-uApprovejp.xsd
Define the Rule
This rule is defined by the <PermitValueRule xsi:type="uajpmf:AttributeInMetadata">
element with the following optional attribute:
...
コード ブロック | ||
---|---|---|
| ||
<!-- ================================================================================== case 1: rule which compares metadata definitions with attributes mail, eduPersonPrincipalName, eduPersonAffiliation. Metadata which is marked as required, Everything is required information and always released. Metadate which is marked as optional: * mail attribute is required information and always released. * eduPersonPrincipalName attribute is optional information. In attribute selection window, it is displayed with checkbox. If the user checked the checkbox, it is released. * eduPersonAffiliation attribute is not released. No attributes are released when SP has no <AttributeConsumingService> element in metadata. ================================================================================== --> <afp:AttributeFilterPolicy id="PolicyforSPwithAttributeConsumingService"> <afp:PolicyRequirementRule xsi:type="basic:ANY" /> <afp:AttributeRule attributeID="mail"> <afp:PermitValueRule xsi:type="uajpmf:AttributeInMetadata" onlyIfRequired="false" /> </afp:AttributeRule> <afp:AttributeRule attributeID="eduPersonPrincipalName"> <afp:PermitValueRule xsi:type="uajpmf:AttributeInMetadata" onlyIfRequired="false" onlyIfChecked="true" /> </afp:AttributeRule> <afp:AttributeRule attributeID="eduPersonAffiliation"> <afp:PermitValueRule xsi:type="uajpmf:AttributeInMetadata" /> </afp:AttributeRule> </afp:AttributeFilterPolicy> <!-- ================================================================================== case 2: Example rule to add rule to SP which has no <AttributeConsumingService> element in metadata. When SP has no <AttributeConsumingService> element: * mail attribute is required information and always released. * eduPersonPrincipalName attribute is optional information. In attribute selection window, it is displayed with checkbox. If the user checked the checkbox, it is released. * eduPersonAffiliation attribute is not released. When SP has <AttributeConsumingService> element, it is the same as case 1. ================================================================================== --> <afp:AttributeFilterPolicy id="PolicyforSPwithoutAttributeConsumingService"> <afp:PolicyRequirementRule xsi:type="basic:ANY" /> <afp:AttributeRule attributeID="mail"> <afp:PermitValueRule xsi:type="uajpmf:AttributeInMetadata" matchIfMetadataSilent="true" onlyIfRequired="false" /> </afp:AttributeRule> <afp:AttributeRule attributeID="eduPersonPrincipalName"> <afp:PermitValueRule xsi:type="uajpmf:AttributeInMetadata" matchIfMetadataSilent="true" onlyIfRequired="false" onlyIfChecked="true" /> </afp:AttributeRule> <afp:AttributeRule attributeID="eduPersonAffiliation"> <afp:PermitValueRule xsi:type="uajpmf:AttributeInMetadata" /> </afp:AttributeRule> </afp:AttributeFilterPolicy> |
4.8 Modification of AttributeQuery profile handler
uApprove JP generates a list of attributes of SAML response message in Attribute Query according to the content of user's acceptance.
Configuration of profile handler
Define the name space
You need to add the definition of name space for this plugin to profile handler file(ex. $IDP_HOME$/conf/handler.xml
) like,
...
コード ブロック | ||
---|---|---|
| ||
... <ph:ProfileHandlerGroup xmlns:ph="urn:mace:shibboleth:2.0:idp:profile-handler" xmlns:uajpph="http://www.gakunin.jp/ns/uapprove-jp/profile-handler" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:mace:shibboleth:2.0:idp:profile-handler classpath:/schema/shibboleth-2.0-idp-profile-handler.xsd http://www.gakunin.jp/ns/uapprove-jp/profile-handler classpath:/schema/shibboleth-2.0-idp-profile-handler-uapprovejp.xsd"> ... |
Change of Profile Handler definition
You need to change AttributeQuery profile handler like:
...
コード ブロック | ||
---|---|---|
| ||
... <ph:ProfileHandler xsi:type="uajpph:SAML1AttributeQueryUApprove" inboundBinding="urn:oasis:names:tc:SAML:1.0:bindings:SOAP-binding" outboundBindingEnumeration="urn:oasis:names:tc:SAML:1.0:bindings:SOAP-binding"> <ph:RequestPath>/SAML1/SOAP/AttributeQuery</ph:RequestPath> </ph:ProfileHandler> ... <ph:ProfileHandler xsi:type="uajpph:SAML2AttributeQueryUApprove" inboundBinding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" outboundBindingEnumeration="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"> <ph:RequestPath>/SAML2/SOAP/AttributeQuery</ph:RequestPath> </ph:ProfileHandler> ... |
Behavior when the SP is blacklisted.
If services.blacklist
property of uApprove.properties
is set true, services
property becomes to the black list of the SP. The SP that matches the entity ID with a regular expression in the services
property connect without using uApprove. In this case, attributes that has been send are not saved to the storage.
...
注意 |
---|
Do not blacklist a SAML1 SP when the IdP has been configured to use the AttribureQuery profile handler of uApprove JP. This IdP can not send the attributes to SAML1 SP that has blacklisted. |
4.9 List of attribute approved SP
Installation and Configuration of Shibboleth SP
The URL of the list of attribute approved SP must be protected at the Shibboleth SP which provides REMOTE_USER.
Install Shibboleth SP to your IdP server and configure as below.
Configuration of REMOTE_USER
Add uid
to REMOTE_USER
at /etc/shibboleth/shibboleth2.xml
:
コード ブロック | ||
---|---|---|
| ||
... <!-- The ApplicationDefaults element is where most of Shibboleth's SAML bits are defined. --> <ApplicationDefaults entityID="https://idp.example.ac.jp/shibboleth-sp" REMOTE_USER="uid"> ... |
Configuration of SSO
Delete the configuration for the DS from the <SSO>
element at /etc/shibboleth/shibboleth2.xml
because of accessing the IdP on the same machine:
コード ブロック | ||
---|---|---|
| ||
... <SSO entityID="https://idp.example.ac.jp/idp/shibboleth"> SAML2 SAML1 </SSO> ... |
Configuration IdP's metadata
Add configuration to read the IdP's metadata at /etc/shibboleth/shibboleth2.xml
:
コード ブロック | ||
---|---|---|
| ||
... <!-- Example of locally maintained metadata. --> <MetadataProvider type="XML" file="$IDP_HOME$/metadata/idp-metadata.xml" /> ... |
Configuration of receiving uid
Add configuration to receive uid
from IdP at /etc/shibboleth/attribute-map.xml
:
...
After configuration, restart shibd.
Configuration of IdP
Configuration of SP's metadata
Add configuration to read the SP's metadata at $IDP_HOME$/conf/relying-party.xml
:
...
ヒント |
---|
You will get the template of the SP's metadata from the below URL: |
Configuration of attribute-resolver.xml
Add definition of uid
at $IDP_HOME$/conf/attribute-resolver.xml
:
コード ブロック | ||
---|---|---|
| ||
<resolver:AttributeDefinition xsi:type="ad:Simple" id="uid" sourceAttributeID="uid"> <resolver:Dependency ref="myLDAP" /> <resolver:AttributeEncoder xsi:type="enc:SAML1String" name="urn:mace:dir:attribute-def:uid" /> <resolver:AttributeEncoder xsi:type="enc:SAML2String" name="urn:oid:0.9.2342.19200300.100.1.1" friendlyName="uid" /> </resolver:AttributeDefinition> |
Configuration of attribute-filter.xml
Configure only uid
is released at $IDP_HOME$/conf/attribute-filter.xml
:
コード ブロック | ||
---|---|---|
| ||
<afp:AttributeFilterPolicy id="..."> <afp:PolicyRequirementRule xsi:type="basic:AttributeRequesterString" value="https://idp.example.ac.jp/shibboleth-sp" /> <afp:AttributeRule attributeID="uid"> <afp:PermitValueRule xsi:type="basic:ANY"/> </afp:AttributeRule> </afp:AttributeFilterPolicy |
Configuration of uApprove.properties
Configure to skip consent by uApprove because the SP to work at the IdP host.
...
You need to re-deploy IdP. See 2.4 Deployment above.
Configuration of httpd
Configure httpd at /etc/httpd/conf.d/ssl.conf as below:
...
After configuration, restart httpd.
URL of the list of attribute approved SP
The URL of the list of attribute approved SP is as below:
https://idp.example.ac.jp/idp/uApprove/ListConsentedSP
Configure Exit page
When Exit button pressed, redirects to https://idp.example.ac.jp/idp/uApprove/list-approvals-exit.html
. You can change the location by setting the URL to lcsp.returnURL
of the uApprove.properties
.
...
書式設定済み |
---|
lcsp.returnURL = https://idp.exmaple.ac.jp/your-made-page.html |
5 Troubleshooting
5.1 Troubleshooting
- Check
$IDP_HOME$/logs/idp-process.log
forERROR
orWARN
messages. - Check Tomcat’s log files located at
$CATALINA_HOME$/logs
for error messages.
5.2 Detailed logging
Enabling DEBUG
or TRACE
log level for uApprove JP in $IDP_HOME$/conf/logging.xml
:
コード ブロック | ||
---|---|---|
| ||
<logger name="ch.SWITCH.aai.uApprove" level="DEBUG"/> <logger name="jp.gakunin.shibboleth" level="DEBUG"/> <logger name="jp.gakunin.uApprovejp" level="DEBUG"/> |
A Notification of the using purpose of attributes on SP
A SP administrator can notify users of the using purpose (ex, use as initial value of user's profile) of attributes on uApporve JP when they add the using purpose of attributes to their SP metadata.
A.1 Configuration
The notification of the using purpose of attributes on SP can be used to add uajpmd:description
to <RequestedAttribute>
element, or add <uajpmd:RequestedAttributeExtension>
element in <Extensions>
element in <SPSSODescriptor>
element.
<uajpmd:RequestedAttributeExtension>
element can describe by multiple languages. If both are set to one attribute, <uajpmd:RequestedAttributeExtension>
element takes precedence.
uajpmd:description
This attribute is defined by the <ResquestedAttribute>
element:
...
コード ブロック | ||
---|---|---|
| ||
<md:RequestedAttribute FriendlyName="mail" Name="urn:oid:0.9.2342.19200300.100.1.3" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" uajpmd:description="The mail attribute is used as the initial value of the mail address field of the registration form."/> |
<uajpmd:RequestedAttributeExtension>
This element defines with the following attributes and one and more <uajpmd:
Description>
elements:
...