Overview

Item	Description
Purpose	Provide component and role authorization settings for TDS components
Communicates With	ProgMan ART Proctor Teacher Hand-Scoring System TestSpecBank
Repository Location	https://github.com/SmarterApp/SS_Permissions
Additional Documentation	Permissions DTD Permissions API Permissions Database Design Permissions User Guide Permissions High-Level Design Permissions Roles to Components Map

Instructions

Create AWS MySQL Instance

Create server instance to host the MySQL instance that will support the component being deployed
- Select an image with the Ubuntu 14.04 LTS 64-bit operating system
Create or choose an AWS security group with the following ports for inbount TCP traffic (can be done during instance creation):
- 22
- 3306
Remove apparmor:
- sudo /etc/init.d/apparmor stop
- sudo update-rc.d -f apparmor remove
- sudo apt-get --purge remove -y apparmor apparmor-utils libapparmor-perl libapparmor1
Update package manager:
- sudo apt-get update
- sudo apt-get upgrade -y
Install MySQL and package dependencies:
- sudo apt-get install -y ntp php5-mysql mysql-server-5.6 python-mysqldb libapache2-mod-auth-mysql
Create directories:
- sudo mkdir -p /var/tmp/mysql
- sudo chown mysql:mysql /var/tmp/mysql
Update /etc/mysql/my.cnf to appear as follows:


#
# The MySQL database server configuration file.
#
# You can copy this to one of:
# - "/etc/mysql/my.cnf" to set global options,
# - "~/.my.cnf" to set user-specific options.
#
# One can use all long options that the program supports.
# Run program with --help to get a list of available options and with
# --print-defaults to see which it would actually understand and use.
#
# For explanations see
# http://dev.mysql.com/doc/mysql/en/server-system-variables.html

# This will be passed to all mysql clients
# It has been reported that passwords should be enclosed with ticks/quotes
# escpecially if they contain "#" chars...
# Remember to edit /etc/mysql/debian.cnf when changing the socket location.
[client]
port        = 3306
socket      = /var/run/mysqld/mysqld.sock

# Here is entries for some specific programs
# The following values assume you have at least 32M ram

# This was formally known as [safe_mysqld]. Both versions are currently parsed.
[mysqld_safe]
socket      = /var/run/mysqld/mysqld.sock
nice        = 0

[mysqld]
#
# * Basic Settings
#
user        = mysql
pid-file    = /var/run/mysqld/mysqld.pid
socket      = /var/run/mysqld/mysqld.sock
port        = 3306
#basedir        = /opt/mysql/server-5.6
basedir     = /usr
datadir     = /var/lib/mysql
tmpdir      = /var/tmp/mysql
#lc-messages-dir    = /opt/mysql/server-5.6/share
lc-messages-dir = /usr/share/mysql/english
skip-external-locking
#
# Instead of skip-networking the default is now to listen only on
# localhost which is more compatible and is not less secure.
#bind-address       = 127.0.0.1
#
# * Fine Tuning
#
key_buffer      = 16M
max_allowed_packet  = 16M
thread_stack        = 192K
thread_cache_size       = 8
# This replaces the startup script and checks MyISAM tables if needed
# the first time they are touched
myisam-recover         = BACKUP
#max_connections        = 100
#table_cache            = 64
#thread_concurrency     = 10
#
# * Query Cache Configuration
#
query_cache_limit   = 1M
query_cache_size        = 16M
#
# * Logging and Replication
#
# Both location gets rotated by the cronjob.
# Be aware that this log type is a performance killer.
# As of 5.1 you can enable the log at runtime!
#general_log_file        = /var/log/mysql/mysql.log
#general_log             = 1
#
# Error log - should be very few entries.
#
log_error = /var/log/mysql/error.log
#
# Here you can see queries with especially long duration
#log_slow_queries   = /var/log/mysql/mysql-slow.log
#long_query_time = 2
#log-queries-not-using-indexes
#
# The following can be used as easy to replay backup logs or for replication.
# note: if you are setting up a replication slave, see README.Debian about
#       other settings you may need to change.
#server-id      = 1
#log_bin            = /var/log/mysql/mysql-bin.log
expire_logs_days    = 10
max_binlog_size         = 100M
#binlog_do_db       = include_database_name
#binlog_ignore_db   = include_database_name
#
# * InnoDB
#
# InnoDB is enabled by default with a 10MB datafile in /var/lib/mysql/.
# Read the manual for more InnoDB related options. There are many!
#
# * Security Features
#
# Read the manual, too, if you want chroot!
# chroot = /var/lib/mysql/
#
# For generating SSL certificates I recommend the OpenSSL GUI "tinyca".
#
# ssl-ca=/etc/mysql/cacert.pem
# ssl-cert=/etc/mysql/server-cert.pem
# ssl-key=/etc/mysql/server-key.pem



[mysqldump]
quick
quote-names
max_allowed_packet  = 16M

[mysql]
#no-auto-rehash # faster start of mysql but no tab completition

[isamchk]
key_buffer      = 16M

#
# * IMPORTANT: Additional settings that can override those from this file!
#   The files must end with '.cnf', otherwise they'll be ignored.
#
!includedir /etc/mysql/conf.d/

Restart MySQL:
- sudo service mysql restart

Create Remote User Account

IMPORTANT: This is definitely not secure and should not be done for a production system!

Edit the /etc/mysql/my.cnf file:
- Update the bind-address = 127.0.0.1 to bind-address = 0.0.0.0 and un-comment the line (if necessary)
Restart MySQL:
- sudo service mysql restart
Log into MySQL:
- mysql -uroot -p
Execute the following commands:
- CREATE USER '[Choose a user name]'@'localhost' IDENTIFIED BY '[Choose a password]';
- CREATE USER '[Choose a user name]'@'%' IDENTIFIED BY '[The same password]';
- GRANT ALL ON *.* TO '[Choose a user name]'@'localhost';
- GRANT ALL ON *.* TO '[Choose a user name]'@'%';
Example commands:
- CREATE USER 'remoteuser'@'localhost' IDENTIFIED BY '[redacted]';
- CREATE USER 'remoteuser'@'%' IDENTIFIED BY '[redacted]';
- GRANT ALL ON *.* TO 'remoteuser'@'localhost';
- GRANT ALL ON *.* TO 'remoteuser'@'%';

Create Permissions Database

Install git and mercurial:
- sudo apt-get install -y git mercurial
Clone the SS_Permissions repository from Smarter Balanced GitHub to the server:
- git clone https://github.com/SmarterApp/SS_Permissions.git
Unless already done, clone the TDS_Build repository from GitHub:
- git clone https://github.com/SmarterApp/TDS_Build.git
NOTE: When cloning the repositories above, they should be “siblings” at the same level. For example, if both repositories are cloned in the ubuntu user’s home directory, the directory will look like this:

ubuntu@perm-db-deploy:~$ ls -alh
total 44K
drwxr-xr-x  6 ubuntu ubuntu 4.0K Apr 11 04:25 .
drwxr-xr-x  3 root   root   4.0K Apr 10 18:08 ..
-rw-r--r--  1 ubuntu ubuntu  220 Apr  9  2014 .bash_logout
-rw-r--r--  1 ubuntu ubuntu 3.6K Apr 11 03:22 .bashrc
drwx------  2 ubuntu ubuntu 4.0K Apr 11 03:22 .cache
-rw-------  1 ubuntu ubuntu  193 Apr 11 04:20 .mysql_history
drwxrwxr-x  5 ubuntu ubuntu 4.0K Apr 11 04:25 SS_Permissions
-rw-r--r--  1 ubuntu ubuntu  675 Apr  9  2014 .profile
drwx------  2 ubuntu ubuntu 4.0K Apr 11 04:09 .ssh
drwxrwxr-x 13 ubuntu ubuntu 4.0K Apr 11 04:16 TDS_Build
-rw-------  1 ubuntu ubuntu 4.0K Apr 11 04:16 .viminfo

Navigate to the TDS_Build\database\permissions directory:
- cd TDS_Build\database\permissions
Update the db-perm-schema-setup.sh script to use the correct user name and password (lines 20 and 21):
- USER=[A valid MySQL user name that can create databases]
- PW=[The MySQL user’s password]
If necessary, update the port and hostame (lines 18 and 19)
Make the db-perm-schema-setup.sh executable:
- sudo chmod u+x db-perm-schema-setup.sh
Run the db-perm-schema-setup.sh script to create the Permissions database schema and load it with seed data:
- ./db-perm-schema-setup.sh

Verify the Permissions Database Schema Was Created and Populated With Seed Data

Log into MySQL:
- mysql -u root -p
Execute the following query:
- show databases;
Output should appear as follows:

+--------------------+
| Database           |
+--------------------+
| information_schema |
| mysql              |
| performance_schema |
| permissions_db     |
+--------------------+

Change to the permissions_db database:
- use permissions_db;
List the tables in the database:
- show tables;

+--------------------------+
| Tables_in_permissions_db |
+--------------------------+
| component                |
| entitytype               |
| permission               |
| permission_role          |
| role                     |
| role_entity              |
+--------------------------+

Get number of records in the permission_role table:
- select count(*) from permission_role;

+----------+
| count(*) |
+----------+
|      416 |
+----------+

OPTIONAL: Get record counts from other tables in the permissions_db. All of the tables should have records in them

Create AWS Web Application Instance

Create server instance to host the Permissions component
- Select an image with the Ubuntu 14.04 LTS 64-bit operating system
Create or choose an AWS security group with the following ports for inbound TCP traffic (can be done during instance creation):
- 22
- 80
- 443
- 1043
- 8080
- 8084
- 8443

Permissions Setup

Update package manager:
- sudo apt-get update
- sudo apt-get upgrade -y
Install packages to satisfy dependencies:
- sudo apt-get install -y ntp mercurial openjdk-7-jdk

Set Up Tomcat Server

Remove apparmor:
- sudo /etc/init.d/apparmor stop
- sudo update-rc.d -f apparmor remove
- sudo apt-get --purge remove -y apparmor apparmor-utils libapparmor-perl libapparmor1
Install Tomcat Server (if not installed already):
- sudo apt-get install -y tomcat7
Stop the Tomcat service:
- sudo service tomcat7 stop
Remove the ROOT directory:
- sudo rm -rf /var/lib/tomcat7/webapps/ROOT
Update the server.xml to allow for large HTTP Headers:
- Edit the /etc/tomcat7/server.xml file
- Find the <Connector> element
- Add the following attribute and value to the <Connector> element:
  - maxHttpHeaderSize="65536"
- Example of an updated <Connector> element:


     <Connector port="8080" protocol="HTTP/1.1"
          connectionTimeout="20000"
          URIEncoding="UTF-8"
          redirectPort="8443"
          maxHttpHeaderSize="65536" />

Set Up a Keystore

Create resources directory and child directories:
- sudo mkdir -p /var/lib/tomcat7/resources/{progman,security}
- sudo chown -R tomcat7:tomcat7 /var/lib/tomcat7/resources/
Create the wildcard SSL cert public key (*.sbtds.org):
- sudo vi /var/lib/tomcat7/resources/security/sbtds_org.cer
Copy the certificate contents (including the BEGIN CERTIFICATE and END CERTIFICATE lines) into /var/lib/tomcat7/resources/security/sbtds_org.cer
- Example:

-----BEGIN CERTIFICATE-----
// This is where the certificate content is
-----END CERTIFICATE-----

Create the keystore (NOTE: the keystore file must be named samlKeystore.jks):
- cd /var/lib/tomcat7
- sudo keytool -importcert -alias [<A meaningful alias] -keystore ./resources/security/samlKeystore.jks -file ./resources/security/[name of certificate file]
  - Example: sudo keytool -importcert -alias sbtdsorg -keystore ./resources/security/samlKeystore.jks -file ./resources/security/sbtds_org.cer
  - provide password
  - Type yes when prompted to trust the certificate
Generate the private key:
- sudo keytool -genkey -alias [choose a meaningful alias] -keyalg RSA -keystore [path/to/keystore] -keysize 2048
  - Example: sudo keytool -genkey -alias proctor-saml-sp -keyalg RSA -keystore ./resources/security/samlKeystore.jks -keysize 2048
- Provide the password to the keystore created previously.
- Answer the prompts. Example of the command and prompts shown below:

sudo keytool -genkey -alias progman-saml-sp -keyalg RSA -keystore ./resources/security/samlKeystore.jks  -keysize 2048
Enter keystore password:
What is your first and last name?
  [Unknown]:  ProgMan Component
What is the name of your organizational unit?
  [Unknown]:  sbac
What is the name of your organization?
  [Unknown]:  SBAC
What is the name of your City or Locality?
  [Unknown]:  San Diego
What is the name of your State or Province?
  [Unknown]:  California
What is the two-letter country code for this unit?
  [Unknown]:  US
Is CN=ProgMan Component, OU=sbac, O=SBAC, L=San Diego, ST=California, C=US correct?
  [no]:  yes

Verify Keystore Contents

To view the keystore contnets, use the following command:
- sudo keytool -list -keystore [path/to/samlKeystore.jks]
  - Example: sudo keytool -list -keystore /var/lib/tomcat7/resources/security/samlKeystore.jks
- Output will be similar to the following (after providing the correct password):

Enter keystore password:

Keystore type: JKS
Keystore provider: SUN

Your keystore contains 2 entries

sbtdsorg, Apr 6, 2016, trustedCertEntry,
Certificate fingerprint (SHA1): D6:06:FA:33:AB:E4:27:26:D5:E1:B2:AB:1E:1D:FF:1E:7E:C0:21:4F
progman-saml-sp, Apr 6, 2016, PrivateKeyEntry,
Certificate fingerprint (SHA1): 8D:3A:66:1D:0C:7B:0A:40:96:B7:A6:8F:13:27:AB:E8:05:7D:8D:3A

Additional Notes

Common keystore commands can be found here

Configure Permissions in ProgMan

Log into the ProgMan web application
Select Manage Component Properties
If a record for the component already exists, click the Edit button (the pencil icon on the lefthand side of the row)
If a record for the component must be created, click the New button (above the table of records)
- When creating a new record, provide the following:
  - A meaningful name for the component
  - The name of the environment
Click the option button to view the properties in Property File Entry mode
Copy the properties shown below and paste them into the text area of the Edit Configuration Settings screen in ProgMan.
NOTE: It may be worthwhile to edit the properties and their values in another text editor prior to pasting the values into the Edit Configuration Settings screen in ProgMan. It is possible the ProgMan session could time out prior to completing the component’s configuration.
Shown below are the Permissions properties that need to be configured in ProgMan:
datasource.url=jdbc:mysql://[FQDN or IP address of the MySQL server that hosts the Permissions database]/permissions_db
datasource.username=[MySQL user account that has access to read/write in the Permissions database]
datasource.password=[Password for the MySQL user account]
datasource.driverClassName=com.mysql.jdbc.Driver
datasource.minPoolSize=5
datasource.acquireIncrement=5
datasource.maxPoolSize=20
datasource.checkoutTimeout=60000
datasource.maxConnectionAge=0
datasource.acquireRetryAttempts=5
permission.uri=http://[FQDN or IP address for the Permissions application]/rest
permission.security.profile=[The name of the environment, starting value is “Development”]
component.name=Permissions
permission.security.idp=https://[FQDN or IP address of the OpenAM server]/auth/saml2/jsp/exportmetadata.jsp?realm=/sbac
permission.webapp.saml.metadata.filename=[The name of the file that will contain the SAML for the Permissions component]
permission.security.saml.keystore.pass=[The password for accessing the samlKeystore.jks]
permission.security.dir=file:////var/lib/tomcat7/resources/security
permission.security.saml.keystore.cert=[The name of the private key that was added to the samlKeystore.jks]
permission.security.saml.alias=[The Service Provider name for the Permissions component]
oauth.tsb.client=[The OAuth client name for the TestSpecBank component; can use a “common” OAuth client name, e.g. one OAuth client for multiple components]
oauth.access.url=https://[FQDN or IP address of the OpenAM server]/auth/oauth2/access_token?realm=/sbac
oauth.tsb.client.secret=[Password for OAuth client used for TestSpecBank. Starting value is sbac12345]
permission.oauth.resource.client.secret=[Password for OAuth client used for Permissions. Starting value is sbac12345]
permission.oauth.resource.client.id=[The OAuth client name for the Permissions component; can use a “common” OAuth client name, e.g. one OAuth client for multiple components]
permission.oauth.checktoken.endpoint=https://[FQDN or IP address of the OpenAM server]/auth/oauth2/tokeninfo?realm=/sbac
Example ProgMan properties for Permissions:

datasource.url=jdbc:mysql://54.191.75.254:3306/permissions_db
datasource.username=remoteuser
datasource.password=[redacted]
datasource.driverClassName=com.mysql.jdbc.Driver
datasource.minPoolSize=5
datasource.acquireIncrement=5
datasource.maxPoolSize=20
datasource.checkoutTimeout=60000
datasource.maxConnectionAge=0
datasource.acquireRetryAttempts=5
permission.uri=http://54.213.111.234:8080/rest
permission.security.profile=Development
component.name=Permissions
permission.security.idp=https://sso-deployment.sbtds.org/auth/saml2/jsp/exportmetadata.jsp?realm=/sbac
permission.webapp.saml.metadata.filename=perm-saml-sp.xml
permission.security.saml.keystore.pass=[redacted]
permission.security.dir=file:////var/lib/tomcat7/resources/security
permission.security.saml.keystore.cert=perm-saml-sp
permission.security.saml.alias=permissions_web
oauth.tsb.client=tsb
oauth.access.url=https://sso-deployment.sbtds.org/auth/oauth2/access_token?realm=/sbac
oauth.tsb.client.secret=[redacted]
permission.oauth.resource.client.secret=[redacted]
permission.oauth.resource.client.id=pm
permission.oauth.checktoken.endpoint=https://sso-deployment.sbtds.org/auth/oauth2/tokeninfo?realm=/sbac

Deploy Permissions Components

Configure Tomcat

Stop the Tomcat service:
- sudo service tomcat7 stop
Edit the /etc/default/tomcat7 file, updating the JAVA_OPTS value to what’s shown below:

JAVA_OPTS="-Djava.awt.headless=true\
 -XX:+UseConcMarkSweepGC\
 -Xms[initial amount of memory that can be allocated to the JVM heap]\
 -Xmx[maximum amount of memory that can be allocated to the JVM heap]\
 -XX:PermSize=[initial amount of memory that can be used for PermGen]\
 -XX:MaxPermSize=[maximum amount of memory that can be used for PermGen]\
 -DSB11_CONFIG_DIR=$CATALINA_BASE/resources\
 -Dspring.profiles.active=progman.client.impl.integration,mna.client.null,server.singleinstance\
 -Dprogman.baseUri=http://[URL to the ProgMan REST component]/rest/\
 -Dprogman.locator=[name of component in ProgMan],[name of Component's environment in ProgMan]"

NOTE: If the component being set up will be load-balanced, then change the server.singleinstance (for the spring.profiles.active option) to server.loadbalanced.
Example:

JAVA_OPTS="-Djava.awt.headless=true\
 -XX:+UseConcMarkSweepGC\
 -Xms512m\
 -Xmx1024m\
 -XX:PermSize=512m\
 -XX:MaxPermSize=512m\
 -DSB11_CONFIG_DIR=$CATALINA_BASE/resources\
 -Dspring.profiles.active=progman.client.impl.integration,mna.client.null\
 -Dprogman.baseUri=http://52.34.140.123:8080/rest/\
 -Dprogman.locator=permissions,Development"</code>

Create a directory for the Permissions log files:
- sudo mkdir -p /usr/share/tomcat7/logs/permission
- sudo chown -R tomcat7:tomcat7 /usr/share/tomcat7/logs/permission
OPTIONAL: Create link in the Tomcat log directory to the Permissions component log file:
- sudo ln -s /usr/share/tomcat7/logs/permission/permission.log /var/lib/tomcat7/logs/permission.log

Install MySQL Connector in Tomcat

Get the mysql-connector-java-5.1.37 tar file:
- wget -O /tmp/mysql-connector-java-5.1.37.tar.gz http://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-java-5.1.37.tar.gz
Change to /tmp directory (where the wget command above wrote the .tar.gz file):
- cd /tmp
Extract the file(s):
- tar xvf mysql-connector-java-5.1.37.tar.gz
Change to the mysql-connector directory:
- cd mysql-connector-java-5.1.37
Copy the .jar into Tomcat’s lib directory:
- sudo cp /tmp/mysql-connector-java-5.1.37/mysql-connector-java-5.1.37-bin.jar /usr/share/tomcat7/lib
Restart Tomcat:
- sudo service tomcat7 restart

Download War File

Download the latest .war file for the Permissions Component into the Tomcat server’s webapps directory:
- sudo wget https://github.com/SmarterApp/SS_Permissions/releases/download/R01.00.38/permissions-R01.00.38.war -O /var/lib/tomcat7/webapps/ROOT.war
Create a pm-client-security.properties file in /var/lib/tomcat7/resources/progman
Copy the following into /var/lib/tomcat7/resources/progman/pm-client-security.properties:

oauth.access.url=https://[FQDN or IP address of OpenAM server]/auth/oauth2/access_token?realm=/sbac
pm.oauth.client.id=[OAuth client id from OpenAM]
pm.oauth.client.secret=[OAuth client secret from OpenAM]
pm.oauth.batch.account=[User account in OpenDJ]
pm.oauth.batch.password=[Password for OpenDJ user account]

Example:

oauth.access.url=https://sso-dev.sbtds.org/auth/oauth2/access_token?realm=/sbac
pm.oauth.client.id=pm
pm.oauth.client.secret=[redacted]
pm.oauth.batch.account=prime.user@example.com
pm.oauth.batch.password=[redacted]

Update ownership for directories and files in the /var/lib/tomcat7/resources/ directory:
- sudo chown -R tomcat7:tomcat7 /var/lib/tomcat7/resources
Start Tomcat to expand the deployed ROOT.war:
- sudo service tomcat7 start

SAML (Security Assertion Markup Language) Setup and Configuration

Configure Automatic Metadata Generation

Create SAML Metadata File For the Component

Use the following command to generate a SAML metadata file for use with the automatic generation process:
- sudo wget https://[FQDN or IP address of OpenAM server]/auth/saml2/jsp/exportmetadata.jsp?realm=/sbac -O /var/lib/tomcat7/resources/security/[Name of the saml.metadata.filename as configured in ProgMan]
  - Example: sudo wget https://sso-dev.sbtds.org/auth/saml2/jsp/exportmetadata.jsp?realm=/sbac -O /var/lib/tomcat7/resources/security/saml_metadata.xml
  - NOTE: When configuring ProgMan (and only ProgMan), the file name will be in the /var/lib/tomcat7/resources/progman/progman-bootstrap.properties file.
- Change ownership of the SAML metadata file(s) to tomcat7:
  - sudo chown tomcat7:tomcat7 /var/lib/tomcat7/resources/security/*.xml

Update the securityContext.xml File for Automatic Metadata Generation

Open securityContext.xml file in an editor for the deployed component
- NOTE: The securityContext.xml file can be found in [Tomcat web application directory]/[component]/WEB-INF/classes/security
  - Example: /var/lib/tomcat7/webapps/ROOT/WEB-INF/classes/security/securityContext.xml
- NOTE: When editing the securityContext.xml file, elevated privileges (i.e. sudo) may by required
Add the following line within a <security:http> element:
- <security:custom-filter before="FIRST" ref="metadataGeneratorFilter" />
- NOTE: Typically a <security:http> element can be found around line 31 of the securityContext.xml file
- Example:

<security:http entry-point-ref="delegatingAuthenticationEntryPoint" use-expressions="true">
    <security:custom-filter before="FIRST" ref="metadataGeneratorFilter" />
    <security:custom-filter ref="oauth2ProviderFilter" before="PRE_AUTH_FILTER" />
    <security:custom-filter after="BASIC_AUTH_FILTER" ref="samlFilter"/>
    <security:intercept-url pattern="/**" access="isFullyAuthenticated()"/>
</security:http>

Add configuration for the SAML metadata generator to securityContext.xml:
- Add the following <bean> definitions to securityContext.xml, immediately after the closing </security:http> tag:

<bean id="metadataGeneratorFilter" class="org.springframework.security.saml.metadata.MetadataGeneratorFilter">
    <constructor-arg ref="metadataGenerator"/>
</bean>

<bean id="metadataGenerator" class="org.springframework.security.saml.metadata.MetadataGenerator">
    <property name="bindingsSSO">
        <list>
            <value>redirect</value>
            <value>artifact</value>
        </list>
    </property>
    <property name="entityId" value="[name of component]"/>
</bean>

NOTE: The component name should not have spaces.

Example of a metadataGenerator configured with an entityId of progman_rest:

<bean id="metadataGeneratorFilter" class="org.springframework.security.saml.metadata.MetadataGeneratorFilter">
    <constructor-arg ref="metadataGenerator"/>
</bean>

<bean id="metadataGenerator" class="org.springframework.security.saml.metadata.MetadataGenerator">
    <property name="bindingsSSO">
        <list>
            <value>redirect</value>
            <value>artifact</value>
        </list>
    </property>
    <property name="entityId" value="progman_rest"/>
</bean>

Restart Tomcat:
- sudo service tomcat7 restart

Verify SAML Metadata Setup

Visit the /saml/metadata endpoint for the deployed component:
- Example: http://54.213.81.243:8080/rest/saml/metadata
The output should appear as XML containing:
- The X509 Certificate data
- URLs containing the domain name of the server hosting the component as the value of a Location attribute
  - Examples:
    - <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="http://54.213.81.243:8080/rest/saml/SingleLogout"/>
    - <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact" Location="http://54.213.81.243:8080/rest/saml/SSO" index="0" isDefault="true"/>

SAML Pre-Configured Metadata Configuration

Use wget to save the output of /saml/metadata endpoint to /var/lib/tomcat7/resources/security/[Name of the saml.metadata.filename as configured in ProgMan]
- Example: save the sudo wget http://54.213.81.243:8080/saml/metadata -O /var/lib/tomcat7/resources/security/saml_metadata.xml
Disable (by removing or commenting out) the <security:custom-filter before="FIRST" ref="metadataGeneratorFilter" /> from the securityContext.xml file to disable the autoamtic generation of SAML metadata
- The automatic generation of SAML metadata is only needed once to generate the metadata file. After the metadata file is generated, there is no further need for automatically generating SAML metadata.
OPTIONAL: Remove the metadataGeneratorFilter and metadataGenerator bean definitions from the securityContext.xml
Set permissions on the metadata XML file(s) so that only the tomcat7 user can read it/them:
- sudo chmod 0400 /var/lib/tomcat/resources/security/*.xml

Verify SAML Metadata Setup

Visit the /saml/metadata endpoint for the deployed component:
- Example: http://54.213.81.243:8080/rest/saml/metadata
The output should appear as XML containing:
- The X509 Certificate data
- URLs containing the domain name of the server hosting the component as the value of a Location attribute
  - Examples:
    - <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="http://54.213.81.243:8080/rest/saml/SingleLogout"/>
    - <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact" Location="http://54.213.81.243:8080/rest/saml/SSO" index="0" isDefault="true"/>

Additional Notes

Spring SAML Metadata Configuration

SAML Service Provider Registration

Launch OpenAM
Log in with appropriate credentials
Click on Register Remote Service Provider
On the Create a SAMLv2 Remote Service Provider page:
- Select the /sbac realm
- Verify the URL option button is checked/selected
- Enter the /saml/metadata endpoint for the desired component in the URL field
  - Example: enter http://54.213.81.243:8080/saml/metadata in the URL field
- Under the Circle of Trust
  - Verify the Add to existing option button is checked/selected
  - Verify sbac is the selected value for the Existing Circle of Trust dropdown list
- Click the Configure button (upper righthand corner, across from the Create a SAMLv2 Remote Service Provider header)

Verify the Service Provider is Configured

Click on the Federation tab
Observe the following:
- The Circle of Trust table contains a record that represents the component that was added
- The Entity Providers table conains a record with a Name equal to the entityId set in the component’s SAML metadata file

Update ProgMan Properties Configuration

Log into the ProgMan server
Update the /var/lib/tomcat7/resources/progman/progman-bootstrap.properties to point to the Permissions instance:
- permission.uri=http://[FQDN or IP address of Permissions application]/rest

back to Deployment Checklists