This document contains the uApprove Jet Pack 3.2(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 more information about the concept of the uApprove JP.
Notes about this guide:
$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.
$IDP_HOME$
(e.g., /opt/shibboleth-idp
).$CATALINA_HOME$
(e.g., /usr/java/tomcat
), and IdP's Instance is configured at $CATALINA_BASE$
(e.g., $CATALINA_HOME$
).$UAPPROVE_INSTALL$
(e.g., /usr/local/src/uApproveJP-#version#
).Copying the libraries to the IdP's library directory:
# cp $UAPPROVE_INSTALL$/lib/*.jar $IDP_HOME$/edit-webapp/WEB-INF/lib |
Assure that only one version of each library is present in |
Copying the Velocity template file for view of attributes selection to the IdP's views directory:
# cp $UAPPROVE_INSTALL$/manual/examples/views/intercept/* $IDP_HOME$/views/intercept |
Copying the CSS file to the IdP's edit-webapp directory:
# cp $UAPPROVE_INSTALL$/manual/examples/edit-webapp/css/* $IDP_HOME$/edit-webapp/css |
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
:
...
|
Modify <constructor-arg name="strategy">
in bean named "shibboleth.AttributeFilterService"
to as below in $IDP_HOME$/system/conf/services-system.xml
:
You must make the change again when you install the Shibboleth IdP again(upgrade, etc.) because the change will be overwritten. |
|
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. |
class="jp.gakunin.idp.consent.logic.impl.IsConsentRequiredPredicate" />
|
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:
|
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 |
Add as below to activate logging of the uApprove JP in $IDP_HOME$/conf/logback.xml
:
|
To activate the uApprove JP, the IdP must be re-deployed:
# cd $IDP_HOME$ # ./bin/build.sh Installation Directory: [/opt/shibboleth-idp] Rebuilding /opt/shibboleth-idp/war/idp.war ... ...done BUILD SUCCESSFUL Total time: 16 seconds |
Copy idp.war
to $CATALINA_BASE$/webapps
:
# cp $IDP_HOME$/war/idp.war $CATALINA_BASE$/webapps/ |
Restart Tomcat:
# service tomcat7 restart |
This section contains advanced configuration topics.
You can be use the relational database (in short, RDB) to save the user's consent information.
The following database parameters are example. Change as necessary the actual value. Please prepare a safe particular password. |
Setting MySQL.
Create Database
Create a database shibboleth used by the Shibboleth IdP:
|
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:
|
Create Table
Create a table StorageRecords used by JPAStorageService:
|
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/ |
Modify idp.consent.StorageService
to shibboleth.JPAStorageService:
idp.consent.StorageService = shibboleth.JPAStorageService # Maximum number of consent storage records # Set to -1 for unlimited server-side storage idp.consent.maxStoredRecords = -1 |
Define the shibboleth.JPAStorageService
set to idp.sesssion.StorageService
at setting change of 2.1.4. idp.consent.StorageService Configuration.
Set the properties(p:url, p:username, p:assword
) in bean named "Shibboleth.MySQLDataSource"
according to of 2.1.1. MySQL Configuration:
|
Restart Tomcat:
# service tomcat7 restart |
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.
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 |
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. |
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:
|
In your attribute filter policy file you’ll need to add the namespace declaration for this plugin. To do this:
xmlns:uajpmf="http://www.gakunin.jp/ns/uapprove-jp/afp/mf"
before the xmlns:xsi
attribute on the root <AttributeFilterPolicyGroup>
element.xsi:schemaLocation
attribute: http://www.gakunin.jp/ns/uApprove-jp/afp/mf http://gakunin.jp/schema/idp/gakunin-afp-mf-uapprovejp.xsd
.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 Default value: |
onlyIfChecked | Boolean flag indicated that only those attributes which are marked as optional and user has permitted should be released. Default value: |
How to write Permit Value Rule using the AttributeInMetadata Match Function:
<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> |
$IDP_HOME$/logs/idp-process.log
for ERROR
or WARN
messages.$CATALINA_BASE$/logs
for error messages.Enabling DEBUG
or TRACE
log level for the uApprove JP in $IDP_HOME$/conf/idp.properties
:
idp.loglevel.uApproveJP = DEBUG |
A 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.
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.
This attribute is defined by the <ResquestedAttribute>
element:
uajpmd:description | String indicated of the using purpose of attributes on SP |
Example 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."/> |
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 associate <u 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 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:SPSSODescriptor> |