2 - Shibboleth IdP Installation

Embed Size (px)

Citation preview

  • Shibboleth 2.0 IdP Training:Basics and InstallationJanuary, 2009

  • IdP Basics: Terms SAMLSecurity Access Markup LanguageXML-based standard for authentication and authorization data interchangeIdentity Provider producer of assertionsService Provider consumer of assertionsCurrent Version: 2.0Shibboleth 2.0 implements SAML 2.0

  • IdP Basics: Terms Entity IDA unique URI for a Shibboleth Identity Provider (IdP) or Service Provider (SP)The recommended format is a URLhttps://idp.colostate.edu/idp/shibbolethInCommon Federation uses URNs:urn:mace:incommon:colostate.edu

  • IdP Basics: Terms Relying PartyThe SAML peer to which the IdP is communicating withThe peer in most cases for an IdP is an SP

  • IdP Basics: Terms ProfileA description of how to use SAML to accomplish a specific taskProfiles define the interface for SAML peers

  • IdP Basics: Terms MetadataA description of the SAML features supported by a SAML entityThis includes the URLs for communicating with the entityShibboleth also uses this information to build technical trust between entities

  • IdP Installation PrerequisitesThree basic prerequisites for installation:Java Virtual MachineJava Servlet ContainerHTTP ListenerYou should be comfortable installing software on your platform

  • IdP Installation Prerequisites

    PrerequisiteWhat were usingJava Virtual MachineSun Java SE 6Java Servlet ContainerApache Tomcat 6HTTP ListenerApache HTTPD 2.2 + mod_proxy_ajp

  • Apache Tomcat Shibboleth PrerequisitesSet in TOMCAT_HOME/conf/server.xmlTurn off Apache Tomcat authentication (optional)Set AJP listener to accept connections from localhost only

  • Lab: Shibboleth InstallationUnzip the distribution archiveRun an install scriptAnswer questionsDeploy a WAR fileRestart Tomcat and verify the installation on port 8080

  • Shibboleth Home (SHIB_HOME)/opt/shibboleth-idp should contain

    The Shibboleth documentation refers to this directory as SHIB_HOME

    binlogsconfmetadatacredentialswarlib

  • SHIB_HOME/binContains command line toolsaacli: attribute authority command line interfaceversion: returns the IdP version

  • SHIB_HOME/confContains the IdPs configuration files:

    We will cover most of these today

    attribute-filter.xmllogging.xmlattribute-resolver.xmllogin.confighandler.xmlrelying-party.xmlinternal.xmlservice.xml

  • SHIB_HOME/credentialsCredentials used by the IdPThe installer creates these:idp.key (IdP key)idp.crt (certificate)idp.jks (keystore)You can use this directory to store Federation certificates

  • SHIB_HOME/libCopies of libraries in the WAR file that make up the IdPUsed by the command line tools

  • SHIB_HOME/logsContains the IdP log filesidp-process.log*idp-access.logidp-audit.log

    * Often referred to when troubleshooting

  • SHIB_HOME/metadataContains metadata filesFiles placed in this directory are not automatically loaded

  • SHIB_HOME/warContains the IdP WAR file created by the installerNote that we configured Apache Tomcat to run the IdP directly from the WAR file

  • HTTP ListenerApache Tomcat has a built-in HTTP listener and can be used as a standaloneApache HTTPD is a web server often implemented as a HTTP listener for TomcatUsing both can offer flexibilityAnd interface well with legacy components

  • Apache HTTPD and TomcatUse mod_proxy_ajpDefine VirtualHosts for the Shibboleth SAML profiles, which listen on ports 443 and optionally 8443mod_proxy directive to connect to TomcatCertificate settingsOthers as required (logging, etc.)

  • Lab: Apache HTTPDConfigure Apache HTTPD as the HTTP listener for Apache Tomcatmod_proxy_ajp has already been installedModify /etc/httpd/conf/httpd.confAdd the ProxyPass for /idpRestart Apache HTTPD

  • LoggingConfigured using the logging.xml file5 Logging levelsERRORWARNINFODEBUGTRACE

  • Lab: LoggingChange the logging level of the edu.internet2.middleware.shibboleth logger and evaluate the difference in the logging messages

  • Metadata: GeneralDescribes SAML features supported by the IdP and SPIncludes the URLs for communicating with the IdP and SPCertificates for IdPs and SPs to trust each otherFederations will typically control and publish metadata

  • Metadata: ConfigurationMetadata can be stored and loaded locally (use SHIB_HOME/metadata)Metadata can also be loaded from a remote sourceWe will discuss both configurations

  • Metadata: ConfigurationMetadata is loaded into the IdP by metadata providersMetadata providers are defined in the relying-party.xml fileA single metadata container provider is defined where you will define within it your metadata providers

  • Metadata: Defining a ProviderMetadata providers are defined using the elementEvery metadata provider must have a:Unique ID using the id attributeType using the xsi:type attributeEach type of metadata provider has its own set of configuration attributes

  • Metadata: Filesystem ProviderThe Filesystem metadata provider loads a metadata file from the local filesystem.Use type definition:xsi:type="FilesystemMetadataProvider"Configuration attributemetadataFile

  • Metadata: File-backed HTTP ProviderLoads metadata via HTTP and backs it up to local fileType definition:xsi:type="FileBackedHTTPMetadataProvider"Configuration attributes:metadataURLbackingFile

  • Lab: Metadata ProvidersDefine a file-backed HTTP metadata provider

  • Multiple Metadata ProvidersThe chaining metadata provider processes children metadata providers in the order they are definedIf the same entity is defined in more than one metadata provider, only the first definition found will be used

  • Metadata RegistrationMetadata must be shared between relying partiesFederations typically have a centralized registration process and systemsRegister certificates and profiles

  • Lab: Metadata RegistrationRegister your IdP so it can interact with the SP/DS in the lab

  • ReferencesMore information on IdP basics and installation can be found at:

    https://spaces.internet2.edu/display/SHIB2/Installation

    The Security Access Markup Language, or SAML, is an XML-based standard for the exchange of authentication and authorization data between peers. There are two types of peers: an Identity Provider, which is a producer of authentication and authorization assertions, and a Service Provider which is a consumer of the assertions.

    SAML assertions are statements from an Identity Provider that provide information to Service Providers to make access control decisions. There are three types of SAML assertion statements:

    Authentication statementsAttribute statementsAuthorization Decision statements

    SAML is from OASIS and the current version is 2.0. Shibboleth 2.0 implements SAML 2.0.An Entity ID is a unique URI for Shibboleth identity and service providers. In Shibboleth 2 the recommended format for an Entity ID is a URL, such as https://idp-mlml.calstate.edu/idp/shibboleth.

    The InCommon Federation uses URNs urn:mace:incommon:mlml.calstate.edu. This was a decision the InCommon Federation made in the past and is not due to any technical reasons or limitations.

    Federations typically assign Entity IDs to ensure uniqueness, and the InCommon Federation is no exception.A relying party is the SAML peer an Identity Provider is communicating with. In almost every case this is a Service Provider. There is the ability for an Identity Providers relying party to be another Identity Provider, but that only occurs in advanced cases, which will not be covered in this class.A profile is a description of how to use SAML to accomplish a specific task. For example, the Single Sign On profile defines handling authentication requests over HTTP. Profiles define the interface for SAML peers to communicate with each other.

    SAML 2 - and thus Shibboleth 2 - introduces new profiles that were not available in Shibboleth 1.3. Shibboleth 2.0 can use SAML 1 profiles and is backward compatible with Shibboleth 1.3.Metadata is a description of the SAML features supported by a SAML entity (contains profiles). Most importantly, this includes the URLs for communicating with the entity.

    Shibboleth also uses this information to build technical trust between entities (certificates). This is accomplished by both entities using the same metadata if users from an IdP needs to use a service protected by a SP, both the IdP and SP must load metadata about each other.The Shibboleth Identity Provider has three basic prerequisites for installation:

    Java Virtual Machine: The Shibboleth Identity Provider is implemented as a Java Servlet application and requires Java.Java Servlet Container: Java Servlets require a Java Servlet Container. Apache Tomcat is a common Java Servlet Container.HTTP Listener: This is available with servlet containers, such as Tomcat, or as separate dedicated listener, such as Apache HTTPD.

    You should be comfortable with installing software on your platform to install Shibboleth (if youre not, were here to help you).For the class, we will be using the following for each prerequisite:

    For the Java Virtual Machine, we will use Sun Java Platform Standard Edition 6. Please note that some Linux distributions, such as Red Hat, come with the GNU Java compiler and runtime (GCJ). GCJ is not supported by Shibboleth and cannot be used.

    For the Java Servlet Container, we will use Apache Tomcat 6. Version 5.5 is the minimum supported version. There are also three configuration settings that must be changed to use Apache Tomcat with Shibboleth which we will discuss shortly.

    For the HTTP Listener, we will use Apache HTTPD 2.2. To allow Apache HTTPD to act as a listener for Apache Tomcat, the mod_proxy_ajp Apache module must also be installed.As mentioned previously, there are three configuration settings that must be changed to use Apache Tomcat with Shibboleth.

    Apache Tomcat will attempt to automatically unpack, deploy and cache WAR file contents by default. The Shibboleth development team has indicated that there have been some problems with Tomcat caching old versions of WAR file contents and recommends turning off this feature. This is by modifying the element in server.xml - set both the unpackWARs and autoDeploy attributes to false:

    Apache Tomcat has its own built-in authentication mechanism which we need to turn off, and for security reasons we are going to allow only AJP connections from Apache HTTPD running locally on the same server as Apache Tomcat. To turn off Apache Tomcats built-in authentication mechanism, add a request.tomcatAuthentication attribute to the element listening on port 8009 and set it to false. To allow local AJP connections only add an address attribute to the same element and set it to 127.0.0.1:

    Time to install Shibboleth. Well review what got installed later.After installing the Shibboleth 2.0 IdP, you should see 7 directories in /opt/shibboleth-idp, called SHIB_HOME in the documentation:

    binconfcredentialsliblogsmetadatawar

    We will discuss each one of these.The SHIB_HOME/bin directory contains two command line tools:

    aacli version

    aacli is the attribute authority command line interface utility. This allows you to simulate submitting an attribute query to the IdP and to evaluate the attributes released.

    version returns the version number of the IdP (major.minor).SHIB_HOME/conf contains the IdPs configuration files. These are:

    attribute-filter.xmlattribute-resolver.xmlhandler.xmlinternal.xmllogging.xmllogin.configrelying-party.xmlservice.xml

    We will cover all of these files except for service.xml and internal.xml, as these control advanced features.The SHIB_HOME/credentials directory stores credentials used by the IdP. The Shibboleth IdP installer creates and stores the IdPs generated key (idp.key), certificate (idp.cert), and keystore (idp.jks) in this directory.

    You can also use this directory to store Federation certificates.SHIB_HOME/lib contains copies of the library files (JAR) that make up the IdP. These copies are used by the command line tools only, as the IdP uses a set of JARs in the WAR file.The SHIB_HOME/logs directory contains the Shibboleth IdPs log files:

    idp-process.log provides detailed description of the IdPs processing requests.idp-access.log provides a record of all client that connect to the IdPidp-audit.log provides a record of all information sent out from the IdP

    The process log (idp-process.log) is often examined during troubleshooting.The SHIB_HOME/metadata directory is the default location where metadata files should be stored. The IdP does not automatically load any metadata, so just placing files in this directory has no effect you need to configure the IdP to specifically load each metadata file.

    As we will cover later in the class, an IdP can load metadata remotely, but backup copies of remote metadata should be stored in this directory.The SHIB_HOME/war directory contains the Web Application Archive (WAR) file created by the installer, named idp.war. You can either copy and deploy the idp.war file or configure Apache Tomcat to run the IdP from the WAR file directly.Though Apache Tomcat has a built-in HTTP listener, many implementations use Apache HTTPD as the HTTP listener for Apache Tomcat. Historically this was done for performance reasons, as Apache Tomcats HTTP engine was found in many instances to be significantly slower than Apache HTTPD.

    That argument may not hold true today, but using Apache HTTPD and Tomcat together can offer additional flexibility and in some instances performance advantages (see http://wiki.apache.org/tomcat/FAQ/Connectors#Q3).

    Because the Apache HTTPD-Apache Tomcat configuration is common, we will cover how to use both together in this course.You can use mod_proxy_ajp to connect Apache HTTPD to Apache Tomcat to handle Servlet/JSP requests. You can also use mod_jk, but we will cover using mod_proxy_ajp for its simplicity. Both solutions are mature and stable.

    You have may have to install mod_proxy_ajp, depending on your Apache HTTPD configuration. On Red Hat Linux, you can use yum to install it.

    Define SSL-based VirtualHosts in Apache HTTPD (in /etc/httpd/conf.d/ssl.conf) for the Shibboleth SAML profiles, which use ports 443 and 8443 by default. Each VirtualHost should contain a mod_proxy directive to connect each to Apache Tomcat, certificate settings and any other settings as required, such as logging levels and paths (in /etc/httpd/conf.d/ssl.conf):

    # ProxyPass connects Apache HTTPD to the Tomcat ajp listener on port 8009 ProxyPass /idp/ ajp://localhost:8009/idp/ SSLEngine on SSLCertificateFile /opt/shibboleth-idp/credentials/idp.crt SSLCertificateKeyFile /opt/shibboleth-idp/credentials/idp.key . . .

    # ProxyPass connects Apache HTTPD to the Tomcat ajp listener on port 8009 ProxyPass /idp/ ajp://localhost:8009/idp/ SSLEngine on SSLCertificateFile /opt/shibboleth-idp/credentials/idp.crt SSLCertificateKeyFile /opt/shibboleth-idp/credentials/idp.key SSLVerifyClient optional_no_ca . . .

    Remember to restart Apache after changing the settings.Logging is controlled by settings in the logging.xml configuration file (SHIB_HOME/conf/logging.xml). Messages are organized based on a hierarchy corresponding to Java package names.

    Example: edu.vt.middleware.ldap

    There are 5 logging levels (in increasing detail order): ERROR, WARN, INFO, DEBUG, TRACE. You will get a lot of stuff if you set the level to TRACE. Each logging level also logs all messages for the levels above it. For example, if you set the logging level to INFO, ERROR and WARN messages will also be logged.

    By default several loggers are defined with logging levels of INFO and WARN.

    The IdP will check for and process changes to the logging configuration every 5 minutes. For immediate processing, you must restart the IdP.Metadata in Shibboleth describes the SAML features supported by IdP and SP. It includes the URLs for communicating with each, as well as certificates to allow trust between IdPs and SPs.

    Federations will typically control what goes into metadata files and publish it for federation members. Metadata should be signed and verified.Shibboleth metadata can be stored and loaded from the local file system (should use SHIB_HOME/metadata) or loaded remotely from an external source. We will discuss both configurations.

    Also, more than one metadata file can be used by Shibboleth simultaneously in a processes called chaining.Metadata is loaded into the IdP by defining metadata providers in the SHIB_HOME/conf/relying-party.xml file.

    The relying-party.xml file allows for a single top-level metadata provider container, called a chaining metadata provider that can have many children metadata providers. They are processed in the order defined in relying-party.xml.Metadata providers are defined by using the element in the relying-party.xml file. Each metadata provider must have a unique ID and a type. Unique IDs are set using the id attribute and types are set using the xsi:type attribute.

    Each type of metadata provider has its own set of configuration attributes. For example, a metadata provider for metadata to be loaded locally will have a configuration attribute to define the local file system path to the metadata file. Similarly, a remote metadata provider will have an attribute to define the URL to the remote metadata file.The Filesystem metadata provider loads a metadata file from the IdPs local filesystem. It uses a type definition of FilesystemMetadataProvider and has a configuration attribute, metadataFile, that indicates the path to the local metadata file.

    For example:

    The File-backed HTTP metadata provider loads metadata via HTTP and stores a cached copy. It uses a type definition of FileBackedHTTPMetadataProvider and has two required configuration attributes:

    metadataURL HTTP URL to the metadata filebackingFile path of the local backup file

    The cached copy (backing file) is used automatically when the remote file cannot be accessed.

    Heres an example File-backed HTTP Provider definition:

    The chaining metadata provider looks up relying-party information in its children in the order they are defined. If two child providers load different metadata for the same entity (e.g., an SP) only the first definition will ever be used by the IdP. The second definition is ignored.Before Shibboleth services can work with each other, metadata about each must be shared between them. In addition to metadata about itself, an IdP needs metadata for all of the SPs accessed by its users. Similarly, each SP needs the metadata for every IdP.

    To simplify this, Federations typically have a centralized registration system and process to allow all federation participants to publish metadata information. The requirements for publishing may vary between federations, but all will involve registering certificates and SAML profile URLs.

    The Shibboleth IdP installer generates a self-signed certificate and creates a metadata file about itself with SAML 1 and 2 profiles (SHIB_HOME/metadata/idp-metadata.xml).References for material covered in this module:

    IdP basics and installationhttps://spaces.internet2.edu/display/SHIB2/Installation

    IdP prerequisites and installationhttps://spaces.internet2.edu/display/SHIB2/IdPInstall

    Logginghttps://spaces.internet2.edu/display/SHIB2/IdPLogging

    Metadatahttps://spaces.internet2.edu/display/SHIB2/IdPMetadataProvider