NetID Login Service - Manual Configuration (General)

Manual Shibboleth SP configuration and reference.

General configuration

This goes step-by-step through the provided shibboleth2.xml configuration file. Pick the appropriate shibboleth2.xml template for your websever (ie, IIS vs Apache). Be sure to right-click and save the file as 'shibboleth2.xml'.

<ApplicationDefaults>

For more information, look here.

<ApplicationDefaults entityID="https://sp.example.org/shibboleth"
    REMOTE_USER="eppn persistent-id targeted-id">
  • entityID: Set to the entity id for your app. This is usually in the format of "https://[hostname.for.site]/shibboleth".
  • REMOTE_USER: Shibboleth can set REMOTE_USER to the value of an attribute it receives from the IdP. You can list multiple attribute names in here, separated by a space, and Shibboleth will set REMOTE_USER to the value of the first defined attribute it finds (e.g., if eppn is null and persistent-id isn't, REMOTE_USER will be set to persistent-id).
    • If you are switching from Pubcookie and were using unscoped NetIDs (ie: bbadger instead of bbadger@wisc.edu) in .htaccess files or your app, you need to set REMOTE_USER to "uid" instead of "eppn". "eppn" is the scoped username.

<Sessions>

For more information, look here.

<Sessions lifetime="28800" timeout="3600"
    checkAddress="false" relayState="ss:mem" handlerSSL="true">
  • lifetime: The number of seconds that a SP session can exist before the user is redirected back to the IdP to get a new assertion. The IdP sessions last 8 hours before the user must log in again.
  • timeout: The number of seconds a user can be idle before the SP expires, and the user will be redirected back to the IdP to get a new assertion.
  • checkAddress: The IdP will place the IP address of the user agent it authenticated into the assertions it issues. When true, the SP will check this address against the address of the client presenting an assertion before creating a session. While useful for security, NAT and proxy usage (as well as IPv6 support on only either the webserver hosting the IdP or the SP) often make this setting a source of errors, so setting to "false" is recommended.
  • relayState: Where to store the URL the user was trying to get to when they were redirected to the IdP to get an assertion. "ss:mem" stores it in the SP's internal memory, which works well.
  • handlerSSL: Defaults to true. Web requests over SSL/TLS will be processed by handlers, which is preferred for security. Leave this set to true.

<SSO>

For more information, look here.

If using a single IdP (eg, NetID Login Service):

<SSO entityID="https://login.wisc.edu/idp/shibboleth">
  SAML2 SAML1
</SSO>
  • entityID: If set, establishes an the IdP to use for authentication. For NetID Login, set this to https://login.wisc.edu/idp/shibboleth

<Logout>

<Logout>SAML2 Local</Logout>
  • You shouldn't need to change this. It allows a user to terminate their SP session by visiting the /Logout handler.

<Handler>

For more information, look here.

<Handler type="MetadataGenerator" Location="/Metadata" signing="false"/>
  • type: This is the Metadata handler, where the SP makes its self-generated metadata available.
  • Location: The metadata is available at /Metadata.
  • signing: Whether to sign the metadata with the SP's credential. Defaults to false, and it's best to keep it that way.
<Handler type="Status" Location="/Status" acl="127.0.0.1"/>
  • type: This is the Status handler, where the SP makes some details of it's internal status available.
  • Location: The status is available at /Status.
  • acl: Restricts access to specific IPs. You can have a space separated list, or use CIDR notation. If you omit this attribute, the Status handler has no access restrictions.
<Handler type="Session" Location="/Session" showAttributeValues="false"/>
  • type: This is the Session handler, where the SP makes some details of the current authenticated user's session available.
  • Location: The session info is available at /Session.
  • showAttributeValues: Whether to display the values of the authenticated user's attributes, or just the count.
  • acl: Restricts access to specific IPs. You can have a space separated list, or use CIDR notation. If you omit this attribute, the Session handler has no access restrictions.
<Handler type="DiscoveryFeed" Location="/DiscoFeed"/>
  • type: This is the DiscoveryFeed handler. It was added in version 2.4, and is used by the Embedded Discovery Service among other things.

<Errors>

This is where the Error handling is configured. For more information, look here.

<Errors supportContact="root@localhost"
  logoLocation="/shibboleth-sp/logo.jpg"
  styleSheet="/shibboleth-sp/main.css"/>
  • supportContact: This email address will be displayed by the bundled error pages when the Shibboleth SP encounters an error.
  • logoLocation: This is the image that will be displayed on the bundled error pages.
  • styleSheet: This is the stylesheet that will be used with the bundled error pages.

<MetadataProvider>

This is where the metadata is loaded. For more information, look here.

<MetadataProvider type="XML" uri="http://login.wisc.edu/metadata/wisc-metadata.xml"
      backingFilePath="login.wisc.edu-wisc-metadata.xml" reloadInterval="7200">
    <MetadataFilter type="RequireValidUntil" maxValidityInterval="20734000"/>
    <MetadataFilter type="Signature" certificate="login.wisc.edu-signing.pem"/>
</MetadataProvider>
  • type: The type of metadata provider. This commonly set to "XML". If you're loading multiple metadata sources, this is set to "Chaining" (see the advanced docs).
  • uri: The URL of the metadata file to download.
    • NetID Login metadata: https://login.wisc.edu/metadata/wisc-metadata.xml
  • backingFilePath: The filename to use when storing this file on disk (useful if the remote source is unavailable). Usually set this to "[hostname.of.remote.source]-[filename]". Example: "login.wisc.edu-wisc-metadata.xml"
  • reloadInterval: How often to check for updates to the file, in seconds. Two hours should be fine.
  • <MetadataFilter type="RequireValidUntil" maxValidityInterval="20734000"/>
    • Require that the metadata doesn't have an expiration more than maxValidityInterval seconds into the future. The Madison IdP metadata is signed for 6 months, so we set this really high.
  • <MetadataFilter type="Signature" certificate="login.wisc.edu-signing.pem"/>
    • Require that the metadata file be signed, using the define certificate file to verify.
    • The NetID Login signing pem is located at https://login.wisc.edu/metadata/login.wisc.edu-signing.pem

<AttributeExtractor>

This is where the metadata is loaded. For more information, look here.

<AttributeExtractor type="XML" validate="true" uri="https://login.wisc.edu/metadata/attribute-map.xml"
      backingFilePath="login.wisc.edu-attribute-map.xml" reloadInterval="7200"/>
  • type: The type of attribute extractor. This commonly set to "XML". If you're loading multiple attribute extractor sources, this is set to "Chaining" (see the advanced docs).
  • validate: Set to "true"
  • uri: Location to where the attribute-map.xml can be loaded from.
    • NetID Login attribute map: https://login.wisc.edu/metadata/attribute-map.xml
  • backingFilePath: The filename to use when storing this file on disk (useful if the remote source is unavailable). Usually set this to "[hostname.of.remote.source]-[filename]". Example: "login.wisc.edu-attribute-map.xml".
  • reloadInterval: Number of seconds between reloads. Two hours should be fine.

<AttributeResolver>

For more information, look here.

If using NetID Login Service:

<AttributeResolver type="Query" subjectMatch="true"/>

NetID Login service sends attributes in the "front channel", so this "back channel" attribute query is not necessary.

<AttributeFilter>

For more information, look here.

<AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/>

You shouldn't need to modify this.

<CredentialResolver>

For more information, look here.

<CredentialResolver type="File" key="sp-key.pem" certificate="sp-cert.pem"/>

The location of the key and certificate your SP uses to encrypt and decrypt SAML assertions. These files are automatically generated at install-time, and are not the same as the SSL key and cert your web server uses. These are not user facing.

  • type: Set this to 'File'.
  • key: Filename of the private key file. Omitting a path loads the file in shibboleth's main directory (where shibboleth2.xml is located).
  • certificate: Filename of the public key file. Omitting a path loads the file in shibboleth's main directory (where shibboleth2.xml is located).

<SecurityPolicyProvider>

For more information, look here.

<SecurityPolicyProvider type="XML" validate="true" path="security-policy.xml"/>

You shouldn't need to modify this.

<ProtocolProvider>

<ProtocolProvider type="XML" validate="true" reloadChanges="false" path="protocols.xml"/>

You shouldn't need to modify this. There doesn't even seem to be documentation for it.

WebISO: Apache-specific configuration

For more information, look here.

Once the installation of the Shibboleth 2 SP is complete, you can require Shibboleth authentication for accessing any directory in your site or application by adding directives to Apache's httpd.conf file. The following examples show all that is necessary to enable Shibboleth authentication.

httpd.conf

<Directory "/var/www/yoursite.wisc.edu/html/shib">
  AuthType shibboleth
  ShibRequestSetting requireSession 1
  ShibUseHeaders On
  Require valid-user
</Directory>

.htaccess

AuthType shibboleth
ShibRequestSetting requireSession 1
ShibUseHeaders On
Require valid-user
  • AuthType: Set this to 'shibboleth' to use Shibboleth authentication
  • ShibRequestSetting: Override Shibboleth settings. Some examples are below; the full list is available here.
    • applicationId: Put the Shibboleth applicationId (from shibboleth2.xml) that you want to use, enclosed in double-quotes.
    • requireSession: Set to '1' to require a session, set to '0' to not
    • forceAuthn: Set to '1' to require the user to reauthenticate at the IdP before creating an SP session, set to '0' to not
  • ShibUseHeaders: Set to 'Off' or 'On'. 'On' causes the user attributes to also be included as HTTP headers. This is useful for things like mod_proxy, which doesn't proxy the environment but will send headers.
  • Require: Set to 'valid-user' to require someone be authenticated to be able to access this resource.

WebISO: IIS-specific configuration

For more information, look here.

To require Shibboleth authentication for specific directories, you edit of the RequestMapper section of shibboleth2.xml. List each directory you want to protect as a Path within the application's Host tag in the RequestMapper. Shibboleth will put together the hostname followed by the paths you define for it to know which URLs to protect. These are not physical paths, but URLs, so you use forward slashes to separate subdirectories. Adding authType="shibboleth" requireSession="true" to the <Host> or <Path> elements is what enables Shibboleth authentication. More details here on configuring RequestMapper.

<RequestMapper>
  <RequestMap> 
    <!-- 
    The example requires a session for documents in /secure on the containing host with http and 
    https on the default ports. Note that the name and port in the <Host> elements MUST match 
    the IIS Site name in the <ISAPI> element below. 
    --> 
    <Host name="sp.example.org" applicationId="default"> 
      <Path name="secure" authType="shibboleth" requireSession="true" redirectToSSL="443"/> 
      <Path name="new_path" authType="shibboleth" requireSession="true" redirectToSSL="443"/> 
    </Host> 
 
    <Host name="newsite.wisc.edu" authType="shibboleth" requireSession="true" redirectToSSL="443"/> 
 
  </RequestMap>
</RequestMapper>

The redirectToSSL="443" setting is important, because it forces the request for the protected path to SSL, preventing user information from being sent over the internet unencrypted.

The RequestMapper is a reloadable resource, so the settings will be updated every time you save shibboleth2.xml.




Keywords:netid login service webiso iso sso saml2 shib shibboleth config configure configuration   Doc ID:22321
Owner:Ryan L.Group:Access Management Services
Created:2012-01-19 13:12 CSTUpdated:2016-09-12 16:05 CST
Sites:Access Management Services, DoIT Help Desk, Middleware
Feedback:  3   1