Overview

Instructions

Create AWS MongoDB Instance

• Create server instance to host the MongoDB 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
  • 27017 - 27019
  • 28017 - 28018
• 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 packages to satisfy dependencies:
  • sudo apt-get install -y ntp
• Install MongoDB 2.4.9:
  • sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 7F0CEB10
  • echo 'deb http://downloads-distro.mongodb.org/repo/ubuntu-upstart dist 10gen' | sudo tee /etc/apt/sources.list.d/mongodb.list
  • sudo apt-get update
  • sudo apt-get install mongodb-10gen=2.4.9
• Pin the version of MongoDB so apt-get will not upgrade it:
  • echo "mongodb-10gen hold" | sudo dpkg --set-selections
• Configure MongoDB by copying the following into /etc/mongodb.conf:
• IMPORTANT: The config file below has noauth=true set. This is a temporary configuration to allow for adding MongoDB user accounts. This setting will be changed later in the checklist.

# mongodb.conf

# Where to store the data.
dbpath=/var/lib/mongodb

#where to log
logpath=/var/log/mongodb/mongodb.log

logappend=true

#bind_ip = 127.0.0.1
bind_ip = 0.0.0.0
port = 27017

# Enable journaling, http://www.mongodb.org/display/DOCS/Journaling
journal=true

# Enables periodic logging of CPU utilization and I/O wait
#cpu = true

# Turn on/off security.  Off is currently the default
noauth = true
#auth = true

# Verbose logging output.
#verbose = true

# Inspect all client data for validity on receipt (useful for
# developing drivers)
#objcheck = true

# Enable db quota management
#quota = true

# Set oplogging level where n is
#   0=off (default)
#   1=W
#   2=R
#   3=both
#   7=W+some reads
#oplog = 0

# Diagnostic/debugging option
#nocursors = true

# Ignore query hints
#nohints = true

# Disable the HTTP interface (Defaults to localhost:27018).
#nohttpinterface = true

# Turns off server-side scripting.  This will result in greatly limited
# functionality
#noscripting = true

# Turns off table scans.  Any query that would do a table scan fails.
#notablescan = true

# Disable data file preallocation.
#noprealloc = true

# Specify .ns file size for new databases.
# nssize = <size>

# Accout token for Mongo monitoring server.
#mms-token = <token>

# Server name for Mongo monitoring server.
#mms-name = <server-name>

# Ping interval for Mongo monitoring server.
#mms-interval = <seconds>

# Replication Options

# in replicated mongo databases, specify here whether this is a slave or master
#slave = true
#source = master.example.com
# Slave only: specify a single database to replicate
#only = master.example.com
# or
#master = true
#source = slave.example.com

# Address of a server to pair with.
#pairwith = <server:port>
# Address of arbiter server.
#arbiter = <server:port>
# Automatically resync if slave data is stale
#autoresync
# Custom size for replication operation log.
#oplogSize = <MB>
# Size limit for in-memory storage of op ids.
#opIdMem = <bytes>

• Restart MongoDB:
  • sudo service mongodb restart
• Add an administrative-level user to MongoDB:

$ mongo admin
db.addUser({
    user:"mongo_admin",
    pwd:"[choose a suitable password]",
    roles:["dbAdminAnyDatabase","userAdminAnyDatabase","clusterAdmin","readWrite"]
});

• Update /etc/mongodb.conf to enable authentication:
  • Comment out the noauth = true line
  • Uncomment the auth = true line
• Example:

# Turn on/off security.  Off is currently the default
#noauth = true
auth = true

• Restart MongoDB:
  • sudo service mongodb restart
• Connect to MongoDB in the admin database:
  • mongo admin -u mongo_admin -p [password for the mongo_admin user] --authenticationDatabase admin
• Add a user for the component:

use [name of database];
db.addUser({
    user:"[name of user]",
    pwd:"[password for user]",
    roles:["readWrite"]
});

• Example:

use progman;
db.addUser({
    user:"progman",
    pwd:"[redacted]",
    roles:["readWrite"]
});

Verify User Can Authenticate to MongoDB

• On the AWS instance hosting MongoDB, run the following commands:
  • mongo admin -u mongo_admin -p '[The password for the mongo_admin user]' --authenticationDatabase admin
  • mongo [component database name] -u [Component user] -p '[The password for the component user]'
• If successful, the prompt should appear as follows:

MongoDB shell version: 2.4.9
connecting to: admin
>

Create AWS Web Application Instance

• Create server instance to host the Administration and Registration Tools (ART) 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

ART 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

Set up RabbitMQ

Get and Install Package

• Get the RabbitMQ installation package:
  • sudo wget http://www.rabbitmq.com/releases/rabbitmq-server/v3.5.6/rabbitmq-server_3.5.6-1_all.deb
• Install the RabbitMQ package:
  • sudo dpkg -i rabbitmq-server_3.5.6-1_all.deb
  • NOTE: If dependency errors are encountered during the dpkg execution, run the following command (which installs the RabbitMQ package and all its dependencies):
    • sudo apt-get install -y -f

Configure RabbitMQ Installation

• Enable the RabbitMQ Management plugin:
  • sudo rabbitmq-plugins enable rabbitmq_management
• Create an administrative user:
  • sudo rabbitmqctl add_user rmq_admin [choose a password]
  • sudo rabbitmqctl set_user_tags rmq_admin administrator
  • sudo rabbitmqctl set_permissions -p / rmq_admin ".*" ".*" ".*"
• Create an ART user:
  • sudo rabbitmqctl add_user art_user [choose a password]
  • sudo rabbitmqctl set_permissions -p / art_user ".*" ".*" ".*"
• Remove the guest user:
  • sudo rabbitmqctl delete_user guest
• Create a directory for the RabbitMQ configuration file:
  • sudo mkdir -p /etc/rabbitmq/rabbitmq.conf.d
• Create a hostname configuration file for RabbitMQ:
  • echo "NODENAME=rabbit@localhost" | sudo tee /etc/rabbitmq/rabbitmq.conf.d/hostname.conf > /dev/null
• Restart the RabbitMQ service:
  • sudo service rabbitmq-server restart

Set up Data Warehouse Integration Passphrase

• Install rng-tools:
  • sudo apt-get install -y rng-tools
• Seed the random number generator:
  • sudo rngd -r /dev/urnandom
• Generate a GPG key:
  • sudo gpg --gen-key
• Follow the prompts provided by the gpg program (default values are in parentheses):

gpg (GnuPG) 1.4.16; Copyright (C) 2013 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Please select what kind of key you want:
   (1) RSA and RSA (default)
   (2) DSA and Elgamal
   (3) DSA (sign only)
   (4) RSA (sign only)
Your selection? 1
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048)
Requested keysize is 2048 bits
Please specify how long the key should be valid.
         0 = key does not expire
      <n> = key expires in n days
      <n>w = key expires in n weeks
      <n>m = key expires in n months
      <n>y = key expires in n years
Key is valid for? (0) [choose when the key should expire]
Key expires at Fri 21 Apr 2017 01:24:53 AM UTC
Is this correct? (y/N) [y if you are satisfied with your input; otherwise n]

You need a user ID to identify your key; the software constructs the user ID
from the Real Name, Comment and Email Address in this form:
    "Heinrich Heine (Der Dichter) <heinrichh@duesseldorf.de>"

Real name: [Provide a name]
Email address: [Provide an email address]
Comment: [Provide a description/comment]
You selected this USER-ID:
    "[Real name value] ([Comment value]) <[email address value]>"

Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
You need a Passphrase to protect your secret key.

gpg: gpg-agent is not available in this session
You don't want a passphrase - this is probably a *bad* idea!
I will do it anyway.  You can change your passphrase at any time,
using this program with the option "--edit-key".

We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
.+++++
.....+++++
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
......+++++
...+++++
gpg: /home/ubuntu/.gnupg/trustdb.gpg: trustdb created
gpg: key B777B118 marked as ultimately trusted
public and secret key created and signed.

gpg: checking the trustdb
gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
gpg: next trustdb check due at 2017-04-21
pub   2048R/B777B118 [expiration date based on input above] [expires: [expiration date based on input above]]
      Key fingerprint = 5B1A 565C 7E19 CDF0 E8A0  31C7 699B 1179 B777 B118
uid                  [Real name value] ([Comment value]) <[email address value]>
sub   2048R/C4C16F48 [expiration date based on input above] [expires: [expiration date based on input above]]

• Example:

gpg (GnuPG) 1.4.16; Copyright (C) 2013 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Please select what kind of key you want:
   (1) RSA and RSA (default)
   (2) DSA and Elgamal
   (3) DSA (sign only)
   (4) RSA (sign only)
Your selection? 1
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048)
Requested keysize is 2048 bits
Please specify how long the key should be valid.
         0 = key does not expire
      <n>  = key expires in n days
      <n>w = key expires in n weeks
      <n>m = key expires in n months
      <n>y = key expires in n years
Key is valid for? (0) 1y
Key expires at Fri 21 Apr 2017 01:24:53 AM UTC
Is this correct? (y/N) y

You need a user ID to identify your key; the software constructs the user ID
from the Real Name, Comment and Email Address in this form:
    "Heinrich Heine (Der Dichter) <heinrichh@duesseldorf.de>"

Real name: SBAC Administrator
Email address: deploy-admin@example.com
Comment: ART Data Warehouse integration
You selected this USER-ID:
    "SBAC Administrator (ART Data Warehouse integration) <deploy-admin@example.com>"

Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
You need a Passphrase to protect your secret key.

gpg: gpg-agent is not available in this session
You don't want a passphrase - this is probably a *bad* idea!
I will do it anyway.  You can change your passphrase at any time,
using this program with the option "--edit-key".

We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
.+++++
.....+++++
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
......+++++
...+++++
gpg: /home/ubuntu/.gnupg/trustdb.gpg: trustdb created
gpg: key B777B118 marked as ultimately trusted
public and secret key created and signed.

gpg: checking the trustdb
gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
gpg: next trustdb check due at 2017-04-21
pub   2048R/B777B118 2016-04-21 [expires: 2017-04-21]
      Key fingerprint = 5B1A 565C 7E19 CDF0 E8A0  31C7 699B 1179 B777 B118
uid                  SBAC Administrator (ART Data Warehouse integration) <deploy-admin@example.com>
sub   2048R/C4C16F48 2016-04-21 [expires: 2017-04-21]

• OPTIONAL: Stop the rng-tools daemon after the gpg key has been generated:
  • sudo service rng-tools stop

Generate SFTP Server Passphrase File

• Generate a testreg.secret.passphrase file:
  • echo "testreg.secret.passphrase=[choose a password]" | sudo tee /var/lib/tomcat7/resources/security/testreg.secret.passphrase > /dev/null
  • Example:
    • echo "testreg.secret.passphrase=password123" | sudo tee /var/lib/tomcat7/resources/security/testreg.secret.passphrase > /dev/null

Configure ART 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 ART properties that need to be configured in ProgMan:

• testreg.tds.proctorUrl=http://localhost:8080/
• user.timezone=[Timezone ART should use when dealing with dates and times]
• tsb.tsbUrl=http://[FQDN or IP address for the TestSpecBank component]/rest/
• testreg.user.export.frequency.milliseconds=[Frequency that ART will export user data]
• testreg.sftp.port=[SFTP server port]
• testreg.sftp.dir=[SFTP directory where ART will put user files for OpenDJ to consume]
• testreg.sftp.pass=[SFTP user password]
• testreg.sftp.user=[SFTP server user account]
• testreg.sftp.host=[FQDN or IP address of SFTP server where ART puts user files for OpenDJ]
• testreg.sso.filename.suffix=[File extension for user data files produced by ART]
• gpgKeyring.public.location=
• gpgKeyring.secret.location=
• testreg.secret.key.userid=
• landingzone.public.key.userid=
• dw.export.callback.url=
• dw.host=
• dw.private.key.loc=
• dw.port=
• dw.user=
• dw.remote.dir=
• dw.gpgfile.prefix=
• testreg.mna.description=ART
• mna.mnaUrl=
• mna.oauth.batch.account=
• mna.oauth.batch.password=
• rabbitmq.vhost=[The RabbitMQ host path. Following this guide, the value will be “/”]
• rabbitmq.password=[RabbitMQ user password]
• rabbitmq.username=[RabbitMQ user account. Following this guide, the value will be “art_user”]
• rabbitmq.host=[RabbitMQ host name or address. Following this guide, the value will be “127.0.0.1”]
• testreg.security.idp=https://[FQDN or IP address of OpenAM server]/auth/saml2/jsp/exportmetadata.jsp?realm=/sbac
• testreg.security.profile=[Environment name for ART component in ProgMan]
• component.name=Assessment and Registration Tools
• permission.uri=http://[FQDN or IP address of the Permissions component]/rest
• testreg.mongo.hostname=[FQDN or IP address of MongoDB server that hosts the ART database]
• testreg.mongo.port=[Port that MongoDB listens on. MongoDB’s default port is 27017]
• testreg.mongo.username=[MongoDB user account with readWrite access to ART’s MongoDB database]
• testreg.mongo.password=[Password for MongoDB user account with readWrite access to ART’s MongoDB database]
• testreg.mongo.dbname=[Name of ART’s database in MongoDB]
• client=
• language.codes=[Language code for ART to use. Starting value is “en”]
• testreg.minJs=[Flag to minify ART JavaScript files. Starting value is “false”]
• testreg.rest.context.root=/rest/
• testreg.userguid.location=http://test.com
• testreg.security.dir=[Path to where security-related files are stored. Following this guide, the value should be “/var/lib/tomcat7/resources/security”]
• testreg.webapp.saml.metadata.filename=[Name of file that stores SAML data for ART Web Application.]
• testreg.security.saml.keystore.cert=[Name of private key for ART in samlKeystore.jks]
• testreg.security.saml.keystore.pass=[Password to access the content of the samlKeystore.jks]
• dw.sbac.port=22
• dw.local.port=22
• student.identity.share=false
• testreg.rest.saml.metadata.filename=[Name of file that stores SAML data for ART REST Application]
• clientId=[Client ID for the CLIENT-level Tenant that should have Assessments/Students etc. managed by ART. Can be found in ProgMan under Manage Tenants]
• clientName=[Client Name for the CLIENT-level Tenant that should have Assessments/Students etc. managed by ART. Can be found in ProgMan under Manage Tenants]
• systemId=33ce4370-b9c0-44a8-9adb-abf1d02a8ceb
• testreg.oauth.resource.client.id=[The OAuth client name for the ART component; can use a “common” OAuth client name, e.g. one OAuth client for multiple components]
• testreg.oauth.resource.client.secret=[Password for OAuth client used for ART. Starting value is sbac12345]
• dw.local.import.types=
• oauth.access.url=https://[FQDN or IP address of the OpenAM server]/auth/oauth2/access_token?realm=/sbac
• testreg.oauth.checktoken.endpoint=https://[FQDN or IP address of the OpenAM server]/auth/oauth2/tokeninfo?realm=/sbac
• 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.tsb.client.secret=[Password for OAuth client used for TestSpecBank. Starting value is sbac12345]

• Example ProgMan properties for ART:

testreg.tds.proctorUrl=http://54.213.81.243:8080/
user.timezone=PST
tsb.tsbUrl=http://54.149.254.189:8080/rest/
testreg.user.export.frequency.milliseconds=10000
testreg.sftp.port=22
testreg.sftp.dir=sso
testreg.sftp.pass=[redacted]
testreg.sftp.user=art
testreg.sftp.host=54.149.142.124
testreg.sso.filename.suffix=art
gpgKeyring.public.location=
gpgKeyring.secret.location=
testreg.secret.key.userid=
landingzone.public.key.userid=
dw.export.callback.url=
dw.host=
dw.private.key.loc=
dw.port=
dw.user=
dw.remote.dir=
dw.gpgfile.prefix=
testreg.mna.description=ART
mna.mnaUrl=
mna.oauth.batch.account=
mna.oauth.batch.password=
rabbitmq.vhost=/
rabbitmq.password=[redacted]
rabbitmq.username=art_user
rabbitmq.host=127.0.0.1
testreg.security.idp=https://sso-deployment.sbtds.org/auth/saml2/jsp/exportmetadata.jsp?realm=/sbac
testreg.security.profile=Development
component.name=Assessment and Registration Tools
permission.uri=http://54.213.111.234:8080/rest
testreg.mongo.hostname=54.186.65.111
testreg.mongo.port=27017
testreg.mongo.username=art
testreg.mongo.password=[redacted]
testreg.mongo.dbname=art
client=
language.codes=en
testreg.minJs=false
testreg.rest.context.root=/rest/
testreg.userguid.location=http://test.com
testreg.security.dir=/var/lib/tomcat7/resources/security
testreg.webapp.saml.metadata.filename=art_local_sp.xml
testreg.security.saml.keystore.cert=art-saml-sp
testreg.security.saml.keystore.pass=[redacted]
dw.sbac.port=22
dw.local.port=22
student.identity.share=false
testreg.rest.saml.metadata.filename=art_rest_local_sp.xml
clientId=98765
clientName=CA98765
systemId=33ce4370-b9c0-44a8-9adb-abf1d02a8ceb
testreg.oauth.resource.client.id=pm
testreg.oauth.resource.client.secret=[redacted]
dw.local.import.types=
oauth.access.url=https://sso-deployment.sbtds.org/auth/oauth2/access_token?realm=/sbac
testreg.oauth.checktoken.endpoint=https://sso-deployment.sbtds.org/auth/oauth2/tokeninfo?realm=/sbac
oauth.tsb.client=pm
oauth.tsb.client.secret=[redacted]

Deploy ART Components

Configure Tomcat

• Stop the Tomcat server:
  • 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.

• NOTE: The JAVA_OPTS for ART has an additional flag:

  • -Dtestreg.secret.passphrase.file=$CATALINA_BASE/resources/security/testreg.secret.passphrase\

• NOTE: The spring.profiles.active option for ART has some additional profiles included:

  • -Dspring.profiles.active=mna.client.null,progman.client.impl.integration,rabbit,test-write-dw-gen-data,server.singleinstance\

• Example of JAVA_OPTS for ART, including the addtional flag and additional Spring profiles:

JAVA_OPTS="-Djava.awt.headless=true\
 -XX:+UseConcMarkSweepGC\
 -Xms512m\
 -Xmx1024m\
 -XX:PermSize=512m\
 -XX:MaxPermSize=1512m\
 -DSB11_CONFIG_DIR=$CATALINA_BASE/resources\
 -Dprogman.baseUri=http://54.213.81.243:8080/rest/\
 -Dtestreg.secret.passphrase.file=$CATALINA_BASE/resources/security/testreg.secret.passphrase\
 -Dspring.profiles.active=mna.client.null,progman.client.impl.integration,rabbit,test-write-dw-gen-data,server.singleinstance\
 -Dprogman.locator=testreg,Development"

Create ART Log File Directories

• Create directories for ART log files:
  • sudo mkdir -p /usr/share/tomcat7/logs/{testreg.webapp,testreg.rest}
  • sudo chown -R tomcat7:tomcat7 /usr/share/tomcat7/logs

Download War Files

• Download the latest .war file for the ART REST Component into the Tomcat server’s webapps directory:
  • sudo wget https://github.com/SmarterApp/TDS_AdministrationAndRegistrationTools/releases/download/2.1.1/testreg.rest-2.1.1.war -O /var/lib/tomcat7/webapps/rest.war
• Download the latest .war file for the ART Web Application Component into the Tomcat server’s webapps directory:
  • sudo wget https://github.com/SmarterApp/TDS_AdministrationAndRegistrationTools/releases/download/2.1.1/testreg.webapp-2.1.1.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 .war files:
  • sudo service tomcat7 start

IMPORTANT: Conduct the SAML Setup and Configuration for the REST component and Web Application Component. After completing the SAML Setup and Configuration steps, there should be two metadata files:

• A SAML XML metadata file for the REST component, located where-ever the file name/path is configured for testreg.security.dir and testreg.rest.saml.metadata.filename (e.g. /var/lib/tomcat7/resources/security/art_rest_local_sp.xml)
• A SAML XML metadata file for the web application component located where-ever the file name/path is configured for testreg.security.dir and testreg.webapp.saml.metadata.filename (e.g. /var/lib/tomcat7/resources/security/art_local_sp.xml)

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

back to Deployment Checklists