This article is an explanation of how to install a Shibboleth Service Provider and configure it for use with Clearlogin. This process has been tested on Linux Mint 18 (64-bit) within a VirtualBox virtual machine (VM).
A few recommendations before starting:
- Install gedit (terminal command: sudo apt-get install gedit), or replace gedit below with your favorite text editor.
- Enable "Shared Clipboard" for your VM.
* More detailed instructions are available below in the Additional Information section.
- First we’ll go ahead and install Apache:
A. From a terminal (CTRL + ALT + T) run the following commands (without the quotes) and say yes ("Y) to all of the prompts unless otherwise specified: "sudo apt-get install apache2"
B. Next type: "sudo service apache2 start".
C. Open your browser and navigate to http://localhost to make sure that Apache is running.
2. Next we'll enable SSL for Apache:
A. From your terminal type: "sudo a2enmod ssl".
B. Next type: "sudo a2ensite default-ssl".
C. And finally type: "sudo service apache2 restart"
D. Open your browser and navigate to https://localhost to make sure SSL is enabled.
Note: You may get a warning stating that Your connection is not secure, just continue through if you do.
3. Now we're going to install the Shibboleth module for Apache:
A. From your terminal type: "sudo apt-get install libapache2-mod-shib2"
B. Next type: "sudo shib-keygen"
C. Open your browser and navigate to https://localhost/Shibboleth.sso/Status and confirm that Shibboleth is working.
4. Configure Apache to require authentication for location /secure and use Shibboleth to authenticate.
A. From the terminal type: "sudo gedit /etc/apache2/apache2.conf" and insert the following:
B. Save your changes and close gedit.
C. Use "sudo service apache2 restart" to restart Apache.
D. Open your browser to https://localhost/secure and you should see the No MetadataProvider available error.
5. Let’s configure Shibboleth to use the Clearlogin Shibboleth test account. If you would like to setup your own app on Clearlogin please see Configuring a Clearlogin App for Shibboleth in the Additional Information section below.
A. Run "sudo gedit /etc/shibboleth/shibboleth2.xml" and replace the ApplicationDefaults, SSO, and MetadataProvider attributes with the following:
I. <ApplicationDefaults entityID="https://localhost/shibboleth" REMOTE_USER="eppn persistent-id targeted-id">
II. <SSO entityID="https://shibboleth.clearlogin-stage.com/">SAML2 SAML1</SSO>
III. <MetadataProvider type="XML" reloadInterval="180000"
IV. Save and close gedit
B. Type, "sudo service shibd restart".
C. Open your browser to https://localhost/secure
D. If you see the Unable to locate metadata for identity provider error, try refreshing the page a few times. It should load the metadata and continue.
E. Go through the login process with the following credentials:
F. Look over debug mode’s Request and Response information if you’d like, then click on Submit SAML Response. Note: Debug mode will not normally show.
G. If you now see a Not Found page, then congratulations! You’ve succeeded! I know it’s counterintuitive and anticlimactic, but the only reason Apache is even allowing you to try to get to /secure is because Shibboleth successfully authenticated you.
H. Open your browser to https://localhost/Shibboleth.sso/Session and confirm that a valid session is there.
6. Now let’s configure Shibboleth to allow the name attribute that is in the Shibboleth Test App to be allowed through.
A. Type "sudo gedit /etc/shibboleth/attribute-map.xml" and add then "name" Attribute:
<Attribute name="name" id="name"/>
Save your changes and close the file.
B. Use "sudo service shibd restart" to restart Shibboleth.
C. Open your browser to https://localhost/secure and go through the login process again.
D. Open your browser to https://localhost/Shibboleth.sso/Session and confirm name is listed under "Attributes."
E. If you’re curious as to what that 1 value(s) is holding you can do the following:
I. Type "sudo gedit /etc/shibboleth/shibboleth2.xml" and change showAttributeValues within the Session Handler to "true" and then save your changes.
II. Use "sudo service shibd restart".
III. Open your browser and navigate to https://localhost/secure and go through the login process again.
IV. Open your browser to https://localhost/Shibboleth.sso/Session and confirm that the values are now showing.
So here's what happened:
- You tried accessing a section of the website that is secure. This means that Shibboleth will check to see if you’re authenticated whenever you try to access it.
- Shibboleth noticed that you were not authenticated, so it redirected your browser to the URL specified within the Metadata file that you set in shibboleth2.xml.
- You log in (or were already logged in and it was seamless) and Clearlogin redirects you back to Shibboleth.
- Shibboleth receives the response from Clearlogin and accepts that you are now authenticated, allowing you access /secure.
- Note: Log out by going to https://localhost/Shibboleth.sso/Logout if you want to repeat the process.
Configuring a Clearlogin App for Shibboleth
1. Create a new custom SAML app.
2. Save the SAML app.
3. Edit the app that we just created:
A. Modify the Key Value Pairs at the bottom of the Edit page by changing the email key to urn:mace:dir:attribute-def:eduPersonPrincipalName. This sets the email key to one that Shibboleth accepts for eppn.
B. Save your changes.
4. Enable Expose SAML Public Metadata in Advanced Settings (https://admin.clearlogin.com/settings/advanced_settings) so that Shibboleth can access metadata for this app.
5. Note: The SAML Public Metadata URL on the app page. You will need to use this address for the MetadataProvider URL within the "shibboleth2.xml" configuration file. You’ll also need to use this domain (In the example below: ‘https://shibboleth.clearlogin-stage.com/’) for the SSO entityID within shibboleth2.xml.)
Adding More Attributes
If you want to pass more attributes to Shibboleth, follow the below example. We will be adding the email attribute:
1. First we'll need to add the email attribute to the Clearlogin app connector's settings.
2. Next, run the following from your terminal "sudo gedit /etc/shibboleth/attribute-map.xml" and add the following: <Attribute name="email" id="email"/>
Save your changes.
3. As usual, run "sudo service shibd restart".
4. Open your browser and navigate to https://localhost/secure and go through the login process again. (On the debug page click Submit SAML Response.)
5. Navigate your browser to https://localhost/Shibboleth.sso/Session and confirm that email is there.
Installations and Configurations
1. From your terminal (CTRL + ALT + T), run "sudo apt-get install gedit".
Type "Y" and then press enter.
Enabling Shared Clipboard in VirtualBox
1. Right-click on your virtual machine and click on "Settings".
2. Click on the Advanced tab from within the General section.
3. Select Bidirectional under Shared Clipboard and then click on OK.
Resources and Paths
- Message was signed, but signature could not be verified.
Solution: Run "sudo service shibd restart" from a terminal.
- No peer endpoint available to which to send SAML response.
Solution: Grab your metadata file from: https://localhost/Shibboleth.sso/Metadata and upload it to your IdP.
Shibboleth Commands (links to visit from within your browser):
Config File Locations