ITS and UVa logos for printed output

NetBadge at UVA

Information for Linux/Apache Developers

Installing & Configuring a Shibboleth Service Provider for NetBadge Single-Signon

These instructions are for Linux/Apache httpd and the Shibboleth Service Provider (SP) is installed and configured as a replacement for Pubcookie.

  1. Install Shibboleth.
    If installing on a CentOS Linux server with the security_shibboleth repo configured,
    yum install shibboleth
    If you are installing on a different distribution, you may find that one of the software repositories for your distribution has a Shibboleth package which you can install. Otherwise, see
  2. Configure your Service Provider (SP). Typically, all SP configuration files are under /etc/shibboleth.
    1. Shibboleth2.xml
      Several items need to be changed in the ApplicationDefaults element of the XML code, including the entityIDs of the service provider and identity provider, and the IdP metadata source. Locate the start of that element, which begins with:
          <ApplicationDefaults entityID=""
            REMOTE_USER="eppn persistent-id targeted-id">
      Change the entityID to reflect your SP's virtual host name, and add uid to the attributes which may be used as the source for the REMOTE_USER variable:
          <ApplicationDefaults entityID="https://Your-Virtual-Host-Name/shibboleth"
            REMOTE_USER="uid eppn persistent-id targeted-id">
      To direct browsers to use only the UVA IdP, locate the SSO block which reads:
          <SSO entityID=""
               discoveryProtocol="SAMLDS" discoveryURL="">
            SAML2 SAML1
      Change the SSO entityID to the production IdP, and eliminate the discoveryProtocol lines:
          <SSO entityID="">
            SAML2 SAML1
      Locate the block reading:
          <!-- Example of locally maintained metadata. -->
             <MetadataProvider type="XML" file="partner-metadata.xml"/>
      Insert after the "-->"
          <MetadataProvider type="XML" file="uva-idp-metadata.xml"/>
    2. Attribute-map.xml
      Before the last line of the file (</Attributes>), insert to configure the uid attribute to be used for the REMOTE_USER variable:
       <Attribute name="urn:oid:0.9.2342.19200300.100.1.1" id="uid"/>
      Add or uncomment other attribute definitions as needed.
    3. Add the combined UVA IdP metadata
      wget --no-check-certificate -O /etc/shibboleth/uva-idp-metadata.xml \
    4. Verify that the SP certificate and private key files have been generated. Unless you changed the names in the shibboleth2.xml file, these should be named /etc/shibboleth/sp-cert.pem and /etc/shibboleth/sp-key.pem. If they are not present, use /etc/shibboleth/ to generate these files.
  3. Configure Apache mod_shib as needed.
    Authentication at the document root requires that you exempt some shibboleth URLs from the authentication requirement. The best way to do this seems to be use of mod_rewrite to serve the entire site internally from a lower-level directory, where you configure the authentication required, and exclude the shibboleth URLs from the rewrite processing. For example, if your DocumentRoot is /var/www/html,
    mkdir /var/www/html/myapp
    and put the application under myapp; to authenticate and allow all users, configure:
      RewriteEngine On
      RewriteRule ^/favicon.ico - [L]
      RewriteRule ^/shibboleth.* - [L]
      RewriteRule ^/Shibboleth.* - [L]
      RewriteRule ^/(.*) /myapp/$1 [QSA,L]
      <Directory "/var/www/html/myapp">
        AuthType shibboleth
        ShibRequestSetting requireSession 1
        require valid-user
  4. Enable httpd and shibd start on boot as appropriate for your distribution.
  5. Contact ITS to configure your SP; you are required to give ITS the entityID for your SP (via this request form). ITS will download your SP metadata from
    and configure an attribute release filter for your SP which includes the attributes uid (computing id of the user) and eduPersonPrincipalName ( if your entityID is in the domain. Other attributes released by default to any UVA SP are eduPersonAffiliation and eduPersonScopedAffiliation.
  6. If you have configured SELinux enforcing, the default policies prevent the httpd from writing to the shibd.sock file which is necessary for the httpd shibboleth module to communicate with the shibboleth daemon. The Shibboleth statement on SELinux is that it is not supported; however, it appears to be fairly easy to add the SELinux policies needed without having to disable SELinux.

    Attempt a Shibboleth login, and if SELinux is blocking access to the socket, your browser will report either a Shibboleth error or a 500 Internal Error. The paths in this description are those used on CentOS; you may need to change these depending on your distribution of Linux. Check /var/log/audit/audit.log or /var/log/messages, and if you see that SELinux blocked httpd access to shibd.sock, you can create a shibboleth SELinux policy to allow access. Use
      cd /tmp
      cat /var/log/audit/audit.log | audit2allow -M shibboleth
      semodule -i shibboleth.pp
      restorecon -R /var/run/shibboleth
    Note: if auditd is not configured, use /var/log/messages instead of the audit.log in the above command. A shibboleth.pp policy file should also have been added to /etc/selinux/targeted/modules/active/modules so that it will be activated on a system reboot.

    On CentOS 6.5, with shibboleth 2.5, the policy change needed was:
    #============= httpd_t ==============
    allow httpd_t initrc_t:unix_stream_socket connectto;
    allow httpd_t var_run_t:sock_file write;

Using the test IdP

ITS has a test identity provider on which we will initially configure your service provider. It sometimes requires several changes to get the metadata and attribute filters configured correctly. Once that is completed and tested, the configuration can then be moved to the production IdP.

To test, modify your workstation's browser to assign a different IP address to the host name On Windows 10, the file is C:\Windows\System32\drivers\etc\hosts. On MacOS or Linux, the file is /etc/hosts. Administrator or root access is required to change these. Add a line to the end of the file with:

The authentication request is made by the SP redirecting your browser to the host name With this change in the hosts file, your browser will resolve that name as the IP address of the test IdP rather than the production IdP. To switch back to the production IdP after testing is completed, remove the line from your hosts file.

  Page Updated: Friday 2018-01-26 16:45:11 EST