Mountain Lion Server install

From cosign wiki

Current revision

[edit] Build and Install the cosign Filter

Building and Installing on Mac OS X

NOTE: Instructions below have been updated for Mac OS X 10.10 (Yosemite) Server and 10.11 (El Capitan) where necessary!

NOTE: 10.8 Server and above does not use /etc/apache2/httpd.conf -- which is what the cosign installer (up through 3.2.0 so far) modifies.

For 10.8 through 10.10 server, you need to add the following line:

LoadModule cosign_module libexec/apache2/mod_cosign.so

NOTE: FOR 10.11 and above -- with System Integrity Protection enabled -- you will modify this line to indicate where you have relocated the mod_cosign.so file. For example, if you put the file in /usr/local/cosign, the line would read:

LoadModule cosign_module /usr/local/cosign/mod_cosign.so

to the following two files:

/Library/Server/Web/Config/apache2/httpd_server_app.conf

/Library/Server/Web/Config/apache2/httpd_server_app.conf.default

[edit] Generate Certificate Signing Request

DO NOT USE THE APPLE TOOLS FOR GENERATING A CERTIFICATE SIGNING REQUEST (CSR) -- these will generate a CSR with a random passphrase for added security. Cosign can not handle passphrase-protected key files.

To generate the key file and CSR file, you must use openssl. As an example (credit to Mark Montague for these steps):

Using Terminal.app, change to the /etc/certificates directory

FIRST: Generate the key file:

openssl genrsa -out EXAMPLE.key 2048
Generating RSA private key, 2048 bit long modulus
.+++
...................................+++
e is 65537 (0x10001)
)

NEXT: Generate the CSR file:

openssl req -new -key EXAMPLE.key -out EXAMPLE.csr
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:Michigan
Locality Name (eg, city) []:Ann Arbor
Organization Name (eg, company) [Internet Widgits Pty Ltd]:University of Michigan
Organizational Unit Name (eg, section) []:Department of EXAMPLE
Common Name (eg, YOUR name) []:www.example.umich.edu
Email Address []:example.webmasters@umich.edu

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

Some points that are important:

The name of the state must be spelled out, not abbreviated.

The Organization Name MUST be EXACTLY "University of Michigan" (no "The")

Despite what you may be prompted for, the Common Name is NOT your name, it is the name that users will use to access the server.

You almost certainly do not want a challenge password or passphrase on the certificate -- if you do put one, the web server will not start without a human to type the password each time the server boots.

NEXT: submit your CSR to your certificate provider:

▪ UMich web admins should use WASUP (https://webservices.itcs.umich.edu/) to request a certificate. Copy/paste the contents of the CSR you generated to the Certificate Signing Request field. Your certificate signer will be umwebCA unless you receive a commercial certificate.

When you get the signed certificate back from your provider, move the file to /etc/certificates.

FINALLY: import the certificate:

FOR MOUNTAIN LION (10.8) SERVER: Go to Server.app, click on the server listed under the "Hardware" section, click the "Settings" tab, click the "Edit" button next to "SSL Certificate", then in the "SSL Certificates" window, click the "Gear" box and select "Manage Certificates". Click the "+" and select "Import a Certificate Identity". In the "Add files containing private key and certificate information" box, drag your /etc/certificates/EXAMPLE.key file and the .cert file you received from your provider and click "Import".

FOR YOSEMITE (10.10) SERVER AND BEYOND: Go to Server.app and click on "Certificates" under the "Server" section. Now click the "+" icon and select "Import a Certificate Identity" and drag your /etc/certificates/EXAMPLE.key file and the .cert file you received from your provider and click "Import".

Note that 4 new *.pem files will be created in /etc/certificates related to what you imported. These will be used by the OS when setting up your certificate for any service you want to put behind SSL, but will *not* be used when setting up cosign in the next steps. Be sure to take not of which certificates were newly created by this import as Server.app may create default certificates with the same timestamp.

[edit] Create and Edit the Cosign Configuration

In the Terminal, create a folder for your cosign configuration.

bash$ sudo mkdir /etc/apache2/cosign

In a good editor, like vi or BBEdit, both of which can be used to edit files owned by root, open /etc/apache2/cosign/site_conf, copying and pasting the configuration lines below. Your weblogin administrators will be able to provide you with the actual values you should use. Have those values in hand as you edit the site_conf file.

CosignHostname weblogin.example.edu
CosignRedirect https://weblogin.example.edu/
CosignPostErrorRedirect http://weblogin.example.edu/post_error.html
CosignService some-service.example.edu
CosignCrypto /etc/certificates/some-service.example.edu.crtkey /etc/certificates/some-service.example.edu.crtkey   /etc/certificates/CAcerts
# for cosign 3:
CosignValidReference              ^https?:\/\/.*\.example\.edu(\/.*)?
CosignValidationErrorRedirect      http://weblogin.example.edu/cosign/validation_error.html
<Location /cosign/valid>
     SetHandler          cosign
     CosignProtected     Off
     Allow from all
     Satisfy any
</Location>

# uncomment this line if your site allows access over HTTP.
# note: CosignHttpOnly means that anyone can sniff and
# steal your service cookie, making it trivial to pose as
# different users of your service.
#
#CosignHttpOnly on
<Location />
CosignProtected on
</Location>
<Location /unprotected>
CosignProtected off
</Location>

An example of what a UM site_conf file would be:

CosignHostname weblogin.umich.edu
CosignValidReference              ^https?:\/\/.*\.umich\.edu(\/.*)?
CosignValidationErrorRedirect      http://weblogin.umich.edu/cosign/validation_error.html
<Location /cosign/valid>
     SetHandler          cosign
     CosignProtected     Off
</Location>
CosignRedirect https://weblogin.umich.edu/
CosignPostErrorRedirect https://weblogin.umich.edu/post_error.html
CosignService hostnamewithoutumichedu
CosignCrypto /etc/certificates/EXAMPLE.key /etc/certificates/EXAMPLE.cert   /etc/apache2/cosign/CAcerts
CosignCheckIP never
CosignProtected on
<Location /unprotected>
CosignProtected off
</Location>

NOTES on the example above:

"CosignCheckIP never" is necessary if users connecting to your cosigned server are coming from private (10.x.y.z) network spaces (like the UM Hospital networks). If that’s not applicable to you, then you can comment that line out.

In the UM-specific example above, use the self-generated .key file and the .cert file provided by to you. Do not use any of the 4 .pem files created when you imported the certificate.

ALSO FOR UM-SPECIFIC SITES: download the umwebCA.pem certificate and put in in CAcerts:

Download the latest umwebCA.pem file (http://www.umich.edu/~umweb/umwebCA.pem).

Create the directory: /etc/apache2/cosign/CAcerts

Copy the downloaded umwebCA.pem file to this CAcerts directory.

As root (not via "sudo"), run: c_rehash /etc/apache2/cosign/CAcerts

[edit] Configure your Virtual Hosts

As mentioned above, 10.8 Server and later changes the file locations you need to modify because it does not use /etc/apache2/httpd.conf

If you want *all sites* you create to be cosign-protected, then add the following line to the following two files:

/Library/Server/Web/Config/apache2/httpd_server_app.conf

/Library/Server/Web/Config/apache2/httpd_server_app.conf.default

Include "/etc/apache2/cosign/site_conf"

If you want a *single site* to be cosign-protected, then first create the site in Server.app. Then you must use the "webappctl" command/configuration to modify that site. Here are the steps from Apple with example file names for doing this (refer to the man pages for webappctl and webapp.plist):

1. Create a server.example.com virtual website in Server.app.  NOTE:  If your site is the DNS name of the server, you do not need to do this.

2. Create a file /etc/apache2/custom_config.conf with some Apache directives in it.   

NOTE:   this file would be where you would put this line:
Include "/etc/apache2/cosign/site_conf"


3. Create the file  /Library/Server/Web/Config/apache2/webapps/com.example.server.includer.plist with these contents:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">

<!-- This is an example of how to add custom includes in a site using a "webapp". -->
<!-- See man pages for webapp.plist(5) and webappctl(8) for information about this example webapp.plist -->

<plist version="1.0">
<dict> 
	<key>includeFiles</key>
	<array>		<!-- Include files are activated in virtual host when webapp is started -->
		<string>/etc/apache2/custom_config.conf</string>
	</array>
	<key>launchKeys</key>
	<array/>		<!-- Launchd plists in /System/Library/LaunchDaemons are loaded when webapp is started -->
	<key>name</key>
	<string>com.example.server.includer</string>
	<key>proxies</key>		<!-- ProxyPass/ProxyPassReverse directives are activated when webapp is started -->
	<dict/>
	<key>requiredModuleNames</key>
	<array/>		<!-- Apache plugin modules are enabled when webapp is started -->
        <key>requiredWebAppNames</key>
        <array/>         <!-- Required web apps are started when this webapp is started -->

	<key>sslPolicy</key>	<!-- Determines webapp SSL behavior -->
	<integer>0</integer>	<!-- 0: default, UseSSLWhenEnabled -->
			<!-- 1:	UseSSLAlways -->
			<!-- 2:	UseSSLOnlyWhenCertificateIsTrustable -->
			<!-- 3:	UseSSLNever -->
			<!-- 4:	UseSSLAndNonSSL -->
        <key>displayName</key>  <!-- Name shown in Server app -->
        <string>Example</string>
	<key>installationIndicatorFilePath</key>	<!-- The presence of this file indicates web app is installed -->
	<string>/etc/apache2/custom_config.conf</string>
</dict>
</plist>

4. Start the webapp:

	sudo webappctl start com.apple.server.includer server.example.com

  or
  
       Go to Server.app -> Web --> Your Site --> Edit Advance Settings and check the box next to the name of your custom site as listed above in the displayName key ("Example")


The act of running "webappctl start…" -- will add the "Include /etc/apache2/custom_config.conf" line to the end of your site file and it will stay there unless you remove it.

To *remove* the line, you must run "webappctl stop …"

Then start your web service in Server.app. Your site page(s) should be protected by cosign at this point.