Carnegie Mellon University
Office of the CIO  ›  Computing Services  ›  Services  ›  Security Services  ›  Identity and Access Management  ›  Authentication Services  ›  How to Use 2fa Authentication  ›  Configure Web Login

Configure Web Login

After you set up and install Web Login, use this page to configure your service.

Step 1: Create Service Provider Certificate

Follow the steps below for your system type to create your service provider's self-signed certificate:

  • RPM-based system or Compile from Source, enter the following:
    cd /etc/shibboleth
    mv sp-cert.pem sp-cert.pem.old
    mv sp-key.pem sp-key.pem.old
    sh keygen.sh -u shibd -g shibd -h hostname     -y 10
  • Windows systems, enter the following:
    cd c:/opt/shibboleth-sp/etc/shibboleth
    ren sp-cert.pem sp-cert.old
    ren sp-key.pem sp-key.old
    keygen.bat -h hostname     -y 10

Note: In both examples, sp-cert.pem and sp-key.pem are the default certificates. Backup each, then replace them with the certificates you generate above. Your hostname typically reflects your service's actual hostname (CNAME or ANAME). The -y 10 specifies the lifetime of the certificate to be created.

Resources

Step 2: Configure the Shibboleth Service

Use the /etc/shibboleth/shibboleth2.xml file to configure your service.

Linux systems:

  • Copy the cmu-shibboleth2-linux.xml file you downloaded in Set Up and Install: Step 2 to the new location and filename /etc/shibboleth/shibboleth2.xml

Windows systems:

  • Copy the cmu-shibboleth2-windows.xml file that you downloaded in Set Up and Install: Step 2 to the new location and filename C:/opt/shibboleth-sp/etc/shibboleth/shibboleth2.xml

Note: Only complete this step if you are using Windows OS. If you are using Linux, move to Step C: Update the EntityID to Reflect Your Hostname.

Use the same hostname that you used to generate your certificate.

<Site id="1" name="sp.example.org"/> and <Host name="sp.example.org">

Note: Ensure the Site id matches the Site id specified in IIS.

Remember to use the same hostname that you used to generate your certificate.

<ApplicationDefaults entityID="https://sp.example.org/shibboleth" REMOTE_USER="eppn persistent-id targeted-id">

The email address provided will be used when displaying error message pages or the logout page.

<Errors supportContact="root@localhost" logoLocation="/shibboleth-sp/logo.jpg" styleSheet="/shibboleth-sp/main.css"/>

Metadata is the information used to locate and establish trust between service and identity providers that use Shibboleth. CMU providers are part of the InCommon Federation, which facilitates secure, federated access to shared resources by maintaining trusted relationships and distributing metadata among participating institutions and service providers.

Beginning January 20, 2025, providers must implement the InCommon Per-Entity Metadata Distribution Service (MDQ) configuration. Below you will find examples of what your configuration may look like before implementing dynamic MDQ configuration and what it should look like after.

E1. Static Metadata Configuration (Standard Configuration)

Your shibboleth2.xml file may currently include a static metadata configuration like one of the following:

<MetadataProvider type="XML" uri="http://md.incommon.org/InCommon/InCommon-metadata.xml" backingFilePath="incommon-metadata.xml" reloadInterval="7200">
     <MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/>
     <MetadataFilter type="Signature" certificate="incommon.pem"/>
</MetadataProvider>

OR

<MetadataProvider type="XML" validate="true" url="https://mdq.incommon.org/entities/https%3A%2F%2Flogin.cmu.edu%2Fidp%2Fshibboleth" backingFilePath="login.cmu.edu-idp.xml" maxRefreshDelay="3600">
     <MetadataFilter type="RequireValidUntil" maxValidityInterval="1209600"/>
     <MetadataFilter type="Signature" certificate="inc-md-cert-mdq.pem" verifyBackup="false"/>=
</MetadataProvider>

E2. Verify Your Shibboleth SP Version

We offer configurations for Shibboleth SP v3 and v2 below. To check your version:

Windows
  1. Open a command prompt.
  2. Navigate to the directory that contains shibd.exe (typically C:\Program Files\Shibboleth, and run shibd.exe -version. 

Linux
  1. Open a terminal window.
  2. Run the following command: Run the following command: shibd -v

E3. Dynamic MDQ Configuration (New Configuration)

Update your shibboleth2.xml file to use the new MDQ configuration. This enables dynamic metadata queries and caching for improved performance and flexibility.

For Shibboleth SP v3 Users

Replace the old static configuration with:

<!-- InCommon Per-Entity Metadata Distribution Service -->
<MetadataProvider type="MDQ" id="incommon" ignoreTransport="true" cacheDirectory="inc-mdq-cache" 
     maxCacheDuration="86400" minCacheDuration="60"
     baseUrl="https://mdq.incommon.org/">
     <MetadataFilter type="Signature" certificate="inc-md-cert-mdq.pem"/>
     <MetadataFilter type="RequireValidUntil" maxValidityInterval="1209600"/>
</MetadataProvider>

For Shibboleth SP v2 Users

If you are still using Shibboleth SP v2, update the file as follows:

<!-- InCommon Per-Entity Metadata Distribution Service -->
<MetadataProvider type="Dynamic" ignoreTransport="true" maxCacheDuration="86400" minCacheDuration="60">
      <Subst>https://mdq.incommon.org/entities/https%3A%2F%2Flogin.cmu.edu%2Fidp%2Fshibboleth</Subst>
     <MetadataFilter type="RequireValidUntil" maxValidityInterval="1209600"/>
     <MetadataFilter type="Signature" certificate="inc-md-cert-mdq.pem"/>
</MetadataProvider>

For more information about the new MDQ configuration, including recommended cache durations, visit the InCommon Metadata Service Wiki.

E4. Where to Place Metadata Providers

If your configuration includes multiple metadata providers, place the new MDQ provider after static metadata providers to avoid unnecessary lookups.

E5. Download the Signing Certificate

In both v3 and v2, you must download the updated signing certificate for MDQ:

  1. Visit the InCommon Metadata Distribution site.
  2. Download the production signing key (inc-md-cert-mdq.pem).
  3. Save it in the credentials folder of your SP:
    1. Linux: /etc/shibboleth/
    2. Windows: C:/opt/shibboleth-sp/etc/shibboleth/credentials/

E6. Move the Following Proxy Line (Windows users in an SII network only)

If the Service Provider is running Windows and is in an SII network, please make sure the following proxy line is moved to the bottom of the Shibboleth2.xml file, directly above the </SPConfig> directive:

<TransportOption provider="CURL" option="10004">proxy.andrew.cmu.edu:3128</TransportOption>

See cmu-shibboleth2-windows.xml for an example of how this change should look.

E7. Restart the Shibboleth Process

If this is your first time setting up your service provider to use the MDQ configuration, you must restart the Shibboleth process. to allow the service provider to re-read the metadata configuration in shibboleth2.xml.

Shibboleth allows the use of a discovery service, which permits a user to select which identity provider they will use for authentication. Alternatively, the service provider may configure one static identity provider to use. Do one of the following:

  • To use only the Carnegie Mellon identity provider:
    • Uncomment the following block: <SSO entityID="https://login.cmu.edu/idp/shibboleth"<https://login.cmu.edu/idp/shibboleth>> SAML2 SAML1 </SSO>
    • InCommon registration will allow individuals from other institutions to authenticate to your service. If you want to limit your web server to only Carnegie Mellon, you must configure your web server/application to verify that the userid is @andrew.cmu.edu. See step 3 for detailed instructions.
  • To use the InCommon Discovery Service:
    • Uncomment the following block: <SSOdiscoveryProtocol="SAMLDS" discoveryURL="https://wayf.incommonfederation.org/DS/WAYF"<https://wayf.incommonfederation.org/DS/WAYF>> SAML2 SAML1 </SSO>

Step 3: Restrict Access to andrew.cmu.edu

  1. In your .htaccess file or shib.conf configuration file, do the following:
    replace require valid-user with require eppn ~ .*@andrew.cmu.edu$

  2. Edit shibboleth2.xml

  3. Add an additional MetadataFilter tag below
    <MetadataProvider>:

    <MetadataFilter type="Whitelist">
    <Include>https://login.cmu.edu/idp/shibboleth</Include>
    </MetadataFilter>

  1. Edit shibboleth2.xml, under <RequestMap> <Host.../> or under <RequestMap> <Path .../> include: <AccessControlProvider path="C:\opt\shibboleth-sp\etc\shibboleth\shibboleth2_ACL.xml" type="XML"/>
  2. Contents of shibboleth2_ACL.xml:
    <?xml version="1.0" encoding="UTF-8"?>
    <AccessControl xmlns="urn:mace:shibboleth:target:config:1.0"/>
    <RuleRegex require="eppn">@andrew.cmu.edu$</RuleRegex>

  3. Add an additional MetadataFilter tag below
    <MetadataProvider>:

    <MetadataFilter type="Whitelist">
    <Include>https://login.cmu.edu/idp/shibboleth</Include>
    </MetadataFilter>

Step 4: Register Your Service Provider with Web Login

At this point your system should have a properly configured Shibboleth; however, it will NOT work until you Request Web Login Authentication for your server to be formally registered with Web Login.

You will be contacted once the registration is complete; you should allow two business days.

Step 5: Test Your Service Providers Configuration

  1. Using a web browser on your service provider, visit: https://HOSTNAME/Shibboleth.sso/Status. Information about your service provider should be displayed.
  2. Test the MDQ provider:
After you complete your configuration, continue to the Protect Your Web Pages instructions.