This document contains the uApprove Jet Pack 3.24(in short, uApprove JP) deployment guide and the general manual.
The uApprove JP is an extension for the Shibboleth Identity Provider 3.x. It is intended to be made available part of the functions supported by the uApprove Jet Pack 2.5 on the Shibboleth Identity Provider. It allows users authenticating at an Identity Provider to release attribute selectively. See See more information about the concept of the uApprove JP.
...
- This guide assumes that the 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_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 installed at
$IDP_HOME$
(e.g.,/opt/shibboleth-idp
). - The Tomcat is installed at
$CATALINA_HOME$
(e.g.,/usr/java/tomcat
), and IdP's Instance is configured at$CATALINA_BASE$
(e.g.,$CATALINA_HOME$
). - The uApprove JP is downloaded and unpacked at
$UAPPROVE_INSTALL$
(e.g.,/usr/local/src/uApproveJP-#version#
).
Prerequisites
- Shibboleth Identity Provider 3.24.0 or later.
1 Basic Deployment
1.1 Library installation
Copying the libraries to the IdP's library directory:
...
注意 |
---|
Assure that only one version of each library is present in |
1.2 Velocity template file
Copying the Velocity template file files for view of attributes selection to the IdP's views directory:
書式設定済み |
---|
# cp $UAPPROVE_INSTALL$/manual/examples/views/intercept/* $IDP_HOME$/views/intercept |
1.3 CSS file
Copying the CSS file files to the IdP's edit-webapp directory:
書式設定済み |
---|
# cp $UAPPROVE_INSTALL$/manual/examples/edit-webapp/css/* $IDP_HOME$/edit-webapp/css |
1.4
...
Modify idp.consent.allowPerAttribute and
idp.consent.compareValues
to true in $IDP_HOME$/conf/idp.properties
:
パネル | ||||||
---|---|---|---|---|---|---|
| ||||||
|
Add bean named "shibboleth.FallbackLanguages
" and bean named "shibboleth.CustomViewContext
" for view of attribute selection as below in $IDP_HOME$/conf/global.xml
:
...
borderColor | silver |
---|---|
bgColor | white |
title | $IDP_HOME$/conf/global.xml |
Message file
Copying the message files to the IdP's message directory:
書式設定済み |
---|
# cp $UAPPROVE_INSTALL$/manual/examples/messages/* $IDP_HOME$/messages/ |
Add <value>%{idp.home}/messages/uApproveJP</value>
to id="shibboleth.MessageSourceResources"
to as below in $IDP_HOME$/conf/service.xml
:
パネル | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
|
1.5 Custom of Configuration
Modify idp.consent.allowPerAttribute and
idp.consent.compareValues
to true in $IDP_HOME$/conf/idp.properties
:
パネル | ||||||
---|---|---|---|---|---|---|
| ||||||
|
Add bean named "shibboleth.FallbackLanguages
" and bean named "shibboleth.CustomViewContext
" for view of attribute selection as below in $IDP_HOME$/conf/global.xml
:
...
<bean id="shibboleth.FallbackLanguages" parent="shibboleth.CommaDelimStringArray" c:_0="#{'%{idp.ui.fallbackLanguages:}'.trim()}" />
<
util:map
id="shibboleth.CustomViewContext">
<entry key="OptionalAttributeFunction">
<bean class="jp.gakunin.idp.consent.logic.impl.OptionalAttributeFunction" />
</entry>
<entry key="AttributeIntendedUseFunction">
<bean class="jp.gakunin.idp.consent.logic.impl.AttributeIntendedUseFunction" p:defaultLanguages-ref="shibboleth.FallbackLanguages" />
</entry>
</util:map>
...
Modify <constructor-arg name="strategy">
in bean named "shibboleth.AttributeFilterService"
to as below in $IDP_HOME$/system/conf/services-system.xml
:
...
パネル | ||||||
---|---|---|---|---|---|---|
| ||||||
p:serviceConfigurations-ref
|
Modify the class definition in Modify <constructor-arg name="strategy">
in bean named "IsConsentRequiredPredicateshibboleth.AttributeFilterService"
to to as below in in $IDP_HOME$/system/flowsconf/intercept/attribute-release-beansservices-system.xml
:
注意 |
---|
You must make the change again when you install the Shibboleth IdP again(upgrade, etc.) because the change will be overwritten. |
パネル | ||||||
---|---|---|---|---|---|---|
| ||||||
|
1.5 Custom Templates
In case you want to customize the templates, follow section Custom View Templates.
At least, you should change to your organization’s logo, since a placeholder logo is installed by default.
Modify to the federaion logo to as below:
...
Copying the logo file organization-logo.png
to IdPs edit-webapp/images/
directory:
書式設定済み |
---|
$ ls $IDP_HOME$/edit-webapp/images/
dummylogo-mobile.png dummylogo.png organization-logo.png |
Modify configuration in $IDP_HOME$/messages/error-messages.properties
. Modify idp.logo
to the filename of copied at above. Note that, the filename begin at /images/
. In addition, modify the idp.logo.alt-text:
パネル | ||||||
---|---|---|---|---|---|---|
| ||||||
|
|
Modify the class definition in bean named "IsConsentRequiredPredicate"
to as below in $IDP_HOME$/system/flows/intercept/attribute-release-beans.xml
:
注意 |
---|
You must make the change again when you install the Shibboleth IdP again(upgrade, etc.) because the change will be overwritten. |
パネル | ||||||
---|---|---|---|---|---|---|
| ||||||
|
1.6 Custom Templates
In case you want to customize the templates, follow section Installation and Configuration of uApprove Jet Pack 3.4.
At least, you should change to your organization’s logo, since a placeholder logo is installed by default.
1.7
...
Rebuild the idp.war:
書式設定済み |
---|
$ cd $IDP_HOME$
$ sudo -u tomcat env JAVA_HOME="${JAVA_HOME}" bin/build.sh
Installation Directory: [/opt/shibboleth-idp]
Rebuilding /opt/shibboleth-idp/war/idp.war ...
...done
BUILD SUCCESSFUL
Total time: 16 seconds |
...
Logging
Add as below to activate logging of the uApprove JP in in $IDP_HOME$/conf/logback.xml
:
パネル | ||||||
---|---|---|---|---|---|---|
| ||||||
|
1.
...
8 Deployment
To activate the uApprove JP, the IdP must be re-deployed:
...
書式設定済み |
---|
# cp $IDP_HOME$/war/idp.war $CATALINA_BASE$/webapps/ |
Restart Tomcat:
書式設定済み |
---|
# service tomcat7systemctl restart tomcat |
2 Advanced Deployment
This section contains advanced configuration topics.
2.1 How to save the consent information of user into Relational Database
You can be use the relational database (in short, RDB) to save the user's consent information.
2.1.1. MySQL Configuration
注意 |
---|
The following database parameters are example. Change as necessary the actual value. Please prepare a safe particular password. |
...
Create Database
Create a database shibboleth used by the Shibboleth IdP:パネル borderColor silver bgColor white db$ mysql -u root
mysql>
CREATE DATABASE shibboleth;
Create User
Create a user shibboleth for access to database shibboleth from IdP. In addition, grant permissions to the database shibboleth to the created user:パネル borderColor silver bgColor white db$ mysql -u root
mysql>
CREATE USER 'shibboleth'@'localhost' IDENTIFIED BY '
shibpassword
'; #←arbitrary password
GRANT INSERT, SELECT, UPDATE, DELETE ON shibboleth.* TO 'shibboleth'@'localhost';
Create Table
Create a table StorageRecords used by JPAStorageService:
パネル borderColor silver bgColor white db$ mysql -u root
mysql>
use shibboleth;
CREATE TABLE `StorageRecords` (
`context` varchar(255) NOT NULL,
`id` varchar(255) NOT NULL,
`expires` bigint(20) DEFAULT NULL,
`value` longtext NOT NULL,
`version` bigint(20) NOT NULL,
PRIMARY KEY (`context`,`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8
;COLLATE=utf8_bin
2.1.3. MySQL Connector/J Installation
Install the MySQL Connector/J (mysql-connector-java.jar) required to access the MySQL:
書式設定済み # yum install mysql-connector-java
The libraries are installed under
/usr/share/java
. Create a symbolic link from they to the lib directory of Tomcat:書式設定済み # rpm -ql mysql-connector-java ... /usr/share/java/mysql-connector-java.jar ... # ln -s /usr/share/java/mysql-connector-java.jar $CATALINA_BASE$/lib/
2.1.4.
...
idp.consent.
...
StorageService Configuration
Modify Modify idp.consent.StorageService
to to shibboleth.JPAStorageService:
パネル | ||||||
---|---|---|---|---|---|---|
| ||||||
# Maximum number of consent storage records # Set to -1 for unlimited server-side storage idp.consent.maxStoredRecords = -1 |
2.1.5. shibboleth.JPAStorageService Configuration
Define the the shibboleth.JPAStorageService
set to set to idp.sesssion.StorageService
at at setting change of 2.1.4. idp.consent.StorageService Configuration.of Installation and Configuration of uApprove Jet Pack 3.4.
Set the properties (p:url, p:username, p:assword
) in bean named "Shibboleth.MySQLDataSource"
according to of 2.1.1. MySQL Configurationof Installation and Configuration of uApprove Jet Pack 3.4:
パネル | ||||||
---|---|---|---|---|---|---|
| ||||||
|
2.1.6. Restart Tomcat
Restart Tomcat:
書式設定済み |
---|
# service tomcat7 restart |
2.2 Templates
Custom View Templates
Feel free to customize the Velocity templates, CSS and image files located in $IDP_HOME$/edit-webapp/
.
For convenience the Velocity is used, cf. Velocity User Guide.
2.3 Localization
Custom Messages
You might adjust/extend the provided resource bundles in $IDP_HOME$/messages.
Must be restarted Tomcat if was adjusted or extended.
There is template files for Japanese localization at $UAPPROVE_INSTALL$/manual/examples/messages/
. It will be to display Japanese messages by copying the template files to $IDP_HOME$/messages/
.
Must be restarted Tomcat to activate:
書式設定済み |
---|
# cp $UAPPROVE_INSTALL$/manual/examples/messages/* $IDP_HOME$/messages/
# service tomcat7 restart |
書式設定済み |
---|
# systemctl restart tomcat |
2.2 Templates
Custom View Templates
Feel free to customize the Velocity templates, CSS and image files located in $IDP_HOME$/edit-webapp/
.
For convenience the Velocity is used, cf. Velocity User Guide.
2.3 Localization
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:
パネル | ||||
---|---|---|---|---|
| ||||
|
ヒント |
---|
If they are both described <mdui:UIInfo> element takes precedence. Also, it contains this information about SP of GakuNin except for some overseas SP. |
...
3 Attribute In Attribute Requester’s Metadata Plugin
3.1 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 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 http://www.gakunin.jp/schema/idp/gakunin-afp-mf-uapprovejp.xsd
.
Define the Rule
This rule is defined by the <PermitValueRule xsi:type="uajpmf:AttributeInMetadata">
element with the following optional attribute:
onlyIfRequired | Boolean flag indicated that only those attributes which are marked as required should be released, those marked as optional will not be. Default value: |
matchIfMetadataSilent | Boolean flag indicated that is marked as optional when the metadata has no no Default value: |
onlyIfChecked | Boolean flag indicated that only those attributes which are marked as optional and user has permitted should be released. Default value: |
...
パネル | ||||
---|---|---|---|---|
| ||||
<PermitValueRule xsi:type="uajpmf:AttributeInMetadata" onlyIfRequired="false" onlyIfChecked="true"> |
Attributes marked as optional will be displayed with checkbox. It is released when checkbox is checked only.
Example Permit Value Rule using the AttributeInMetadata Match Function:
パネル | ||||
---|---|---|---|---|
| ||||
<!-- ================================================================================== 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 Troubleshooting
...
4.1 Troubleshooting
- Check
$IDP_HOME$/logs/idp-process.log
forERROR
orWARN
messages. - Check Tomcat’s log files located at
$CATALINA_BASE$/logs
for error messages.
...
4.2 Detailed logging
Enabling DEBUG
or TRACE
log level for the uApprove JP in $IDP_HOME$/conf/idp.properties
:
パネル | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
idp.loglevel.uApproveJP = DEBUG |
A Notification of the using purpose of attributes on SP
A An SP administrator can notify users of the using purpose (ex, use as initial value of user's profile) of attributes on the 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 be described by multiple languages. If both of attribute and element are set to one attribute, <uajpmd:RequestedAttributeExtension>
element takes precedence.
uajpmd:description
This attribute is defined by the <ResquestedAttribute>
element:
uajpmd:description | String indicated of the using purpose of attributes on SP |
Example of the <RequestedAttribute>
element with uajpmd:descrption
:
パネル | ||||
---|---|---|---|---|
| ||||
<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:
uajpmd:FriendlyName | The value of FriendlyName of the <RequestedAttribute> element to of FriendlyName of the <RequestedAttribute> element to associate<u element element. |
The <uajpmd:Description> element describes the using purpose of attributes on SP and defines with the following attributes:
xml:lang | The language used in the using purpose of attributes on SP |
Example of the <uajpmd:RequestedAttributeExtension>
:
パネル | ||||
---|---|---|---|---|
| ||||
<md:EntitiesDescriptor Name="uapprovejp-dev-metadata.xml" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:shibmd="urn:mace:shibboleth:metadata:1.0" xmlns:uajpmd="http://www.gakunin.jp/ns/uapprove-jp/metadata" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> ... <md:EntityDescriptor entityID="..."> <md:SPSSODescriptor> ... <md:Extensions> ... <uajpmd:RequestedAttributeExtension FriendlyName="mail"> <uajpmd:Description xml:lang="en">The mail attribute is used as the initial value of the mail address field of the registration form.</uajpmd:Description> <uajpmd:Description xml:lang="ja">mail 属性を登録ページのメールアドレス欄の初期値として使用します</uajpmd:Description> </uajpmd:RequestedAttributeExtension> ... </md:Extensions> ... <md:AttributeConsumingService index="1"> <md:ServiceName xml:lang="en">Sample Service</md:ServiceName> <md:RequestedAttribute FriendlyName="eduPersonPrincipalName" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" isRequired="true"/> <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"/> </md:AttributeConsumingService> |
...
...
</md:EntityDescriptor>
...
</md:EntitiesDescriptor> |