Export (0) Print
Expand All
3 out of 6 rated this helpful - Rate this topic

Configure Shibboleth for use with single sign-on

Published: June 29, 2012

Updated: January 27, 2014

Applies To: Office 365, Windows Azure, Windows Intune

This topic contains detailed instructions on how to configure Shibboleth Identity Provider to federate with Windows Azure AD to enable single sign-on access to one or more Microsoft cloud services (for example, Windows Intune and/or Office 365) using the SAML 2.0 protocol. The SAML 2.0 relying party for a Microsoft cloud service used in this scenario is Windows Azure AD.

Only a limited set of clients are supported in this single sign-on scenario, as follows:

  • Web-based clients such as Exchange Web Access and SharePoint Online

  • Email-rich clients that use basic authentication and a supported Exchange access method such as IMAP, POP, Active Sync, MAPI, etc. (the Enhanced client protocol end point is required to be deployed), including:

    • Microsoft Outlook 2007

    • Microsoft Outlook 2010

    • Thunderbird 8 and 9

    • The iPhone (various iOS versions)

    • Windows Phone 7

All other clients are not supported in this single sign-on scenario with Shibboleth Identity Provider.  For example, the Lync 2010 desktop client is not supported to login into the service with Shibboleth Identity Provider configured for single sign-on.

Before you can complete any of the steps in this topic to configure Shibboleth Identity Provider for single sign-on, you must review and follow the instructions provided in Prepare for single sign-on.

For general information about single sign-on, see Single sign-on roadmap.

In order to configure Shibboleth Identity Provider for use with single sign-on, complete the following steps:

  1. Add Windows Azure AD metadata

  2. Add Windows Azure AD as a relying party

  3. Configure the Shibboleth attribute resolver

  4. Configure the Shibboleth attribute filter

  5. Optional: Install the Shibboleth ECP Extension

  6. Restart Shibboleth and verify functionality

In the examples throughout this topic, IDP_HOME is the base directory where you installed Shibboleth Identity Provider, for example, c:\shibboleth2idp. As you follow the instructions in this topic to configure Shibboleth, make sure to replace IDP_HOME with your specific path.

Shibboleth Identity Provider needs information about the Windows Azure AD relying party. Windows Azure AD publishes metadata at https://nexus.microsoftonline-p.com/federationmetadata/saml20/federationmetadata.xml. It is recommended that you always check for the latest Windows Azure AD metadata. Here is the current value of the metadata:

<?xml version="1.0" encoding="utf-8"?>
<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" entityID="urn:federation:MicrosoftOnline">
  <SPSSODescriptor WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://login.microsoftonline.com/login.srf" index="0" isDefault="true"/>
    <AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST-SimpleSign" Location="https://login.microsoftonline.com/login.srf" index="1"/>
    <AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:PAOS" Location="https://login.microsoftonline.com/login.srf" index="2" />

To add the Windows Azure AD metadata to Shibboleth Identity Provider, you can use the The Filesystem Metadata Provider method – you can manually download and store Windows Azure AD metadata in a file in the IDP_HOME/metadata folder.

In the examples throughout this topic, IDP_HOME is the base directory where you installed Shibboleth Identity Provider, for example, c:\shibboleth2idp. As you follow the instructions in this topic to configure Shibboleth, make sure to replace IDP_HOME with your specific path.

You have to enable communication between Shibboleth Identity Provider and Windows Azure AD by defining a new RelyingParty element in the IDP_Home/conf/relying-party.xml file. Windows Azure AD requires changes to the default saml:SAML2Profile settings in the DefaultRelyingParty element.

Insert the following text after the DefaultRelyingParty element and make sure the RelyingParty id value matches the entityID value you specified in Add Windows Azure AD metadata, for example, "urn:federation:MicrosoftOnline". Also, make sure your provider value matches the EntityID of your Shibboleth Identity Provider specified in the DefaultRelyingParty element as shown in the following example:

<!-- Windows Azure AD -->
<rp:RelyingParty id="urn:federation:MicrosoftOnline" provider="https://idp.contoso.com/idp/shibboleth" defaultSigningCredentialRef="IdPCredential">
     <rp:ProfileConfiguration xsi:type="saml:SAML2SSOProfile"
encryptNameIds="never" />

You must also specify to Shibboleth Identity Provider where to find the file that contains the Windows Azure AD metadata, for example, IDP_HOME/metadata/windows-azure-ad-metadata.xml. You can do this by adding an entry to the IDP_Home/conf/relying-party.xml file in the MetadataProvider node as shown in the following example:

<!—- Windows Azure AD Metadata -->
<metadata:MetadataProvider id="OrgID" xsi:type="metadata:ResourceBackedMetadataProvider">
<metadata:MetadataResource xsi:type="resource:FilesystemResource" file="C:\opt\shibboleth-idp/metadata/WindowsAzureAD-metadata.xml"/>

Windows Azure AD requires two pieces of data from Shibboleth Identity Provider to locate the shadow account in the authentication platform. To inform Shibboleth of these requirements, add the following entries to the IDP_HOME/conf/attribute-resolver.xml file:

  • Windows Azure AD ImmutableID

    Windows Azure AD requires you select a unique identifier for each user in your user directory. You must also configure Shibboleth to send this attribute on each federated login to Windows Azure AD in the SAML 2.0 NameID assertion. This identifier must not change for this user over the lifetime of the user being in your system. The Windows Azure AD Service calls this attribute the “ImmutableID”. The value for the unique identifier must not contain domain information and is case-sensitive.

    For example, do not use user@contoso.com. In the recommended code below, the value used will be the Active Directory objectGUID property that is base64-encoded. When creating accounts, you must ensure the ImmutableID is processed the same way or the user will not be able to sign in to the Microsoft cloud service. The Windows Azure Active Directory Sync tool automatically uses the Active Directory objectGUID for the ImmutableID value and processes the ImmutableID the same way as in the following recommended example:

    <!-- Use AD objectGUID for ImmutableID -->
    <resolver:AttributeDefinition id="ImmutableID" xsi:type="Simple" xmlns="urn:mace:shibboleth:2.0:resolver:ad"
       <resolver:Dependency ref="myLDAP" />
       <resolver:AttributeEncoder xsi:type="SAML2StringNameID" xmlns="urn:mace:shibboleth:2.0:attribute:encoder"
       nameFormat="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" />
    Update the LDAP Data Connector in attribute-resolver.xml to specify objectGUID as a binary.

    Make sure to add this line to your LDAP Data Connector entry, this will ensure objectGUID is handled correctly and is base64-encoded.

    <LDAPProperty name="java.naming.ldap.attributes.binary" value="objectGUID"/>
    For example:

    <!-- ========================================== -->
    <!--      Data Connectors                       -->
    <!-- ========================================== -->
    <!-- Live@edu LDAP Connector -->
    <resolver:DataConnector id="myLDAP" xsi:type="LDAPDirectory" xmlns="urn:mace:shibboleth:2.0:resolver:dc"
      <LDAPProperty name="java.naming.ldap.attributes.binary" value="objectGUID"/>
  • Windows Azure AD User ID

    Windows Azure AD requires that the Windows Azure AD User ID, for example, joe@contoso.com, is sent using the custom entry as described in the example below. In this example, the value is stored in the LDAP userPrincipalName attribute.

    <!-- UserPrincipalName for Windows Azure AD User ID -->
    <resolver:AttributeDefinition id="UserId" xsi:type="ad:Simple" sourceAttributeID="userPrincipalName">
          <resolver:Dependency ref="myLDAP" />
          <resolver:AttributeEncoder xsi:type="enc:SAML2String" name="IDPEmail" friendlyName="UserId" />

Shibboleth Identity Provider must be configured to release the required attributes to Windows Azure AD. Add the following text to the IDP_HOME/conf/attribute-filter.xml file to release the attributes to Windows Azure AD.

The settings that are shown here release the required attributes only to Windows Azure AD and Windows Live services. The settings use specific AttributeFilterPolicy IDs to indicate the attributes are required by Windows Azure AD.

<!-- Attribute Filter Policy for Windows Azure AD -->
<afp:AttributeFilterPolicy id="PolicyForWindowsAzureAD">
<afp:PolicyRequirementRule xsi:type="basic:AttributeRequesterString" value="urn:federation:MicrosoftOnline" />

<!-- Release userPrincipalName as Windows Azure AD User ID -->
      <afp:AttributeRule attributeID="UserId">
            <afp:PermitValueRule xsi:type="basic:ANY"/>

<!-- Release Immutable ID to Windows Azure AD -->
      <afp:AttributeRule attributeID="ImmutableID">
          <afp:PermitValueRule xsi:type="basic:ANY"/>

<!-- Note: it is not recommended to send transientId to Windows Azure AD -->
<afp:AttributeRule attributeID="transientId">
   <afp:DenyValueRule xsi:type="basic:ANY"/>


Though optional, this is a recommended step. If you are using Shibboleth as your STS, make sure to install the Shibboleth Identity Provider ECP extension in order for single sign-on to work with a smart phone, Microsoft Outlook or other clients.

The enhanced client/proxy (ECP) extension is included in Shibboleth 2.3.3 and later. For earlier version of Shibboleth 2.x, you can download and install the ECP extension. For more information, see: https://wiki.shibboleth.net/confluence/display/SHIB2/IdP+ECP+Extension.

The Shibboleth Identity Provider ECP extension allows you to enable integration of desktop e-mail applications with Windows Azure AD. This extension implements the SAML 2.0 ECP specification. When you configure single sign-on with Windows Azure AD, you can specify the URL for the ECP extension, for example, https://idp.contoso.com/idp/profile/SAML2/SOAP/ECP. The Shibboleth ECP extension authentication is currently limited to basic authentication.

Complete the following steps if you chose to install the Shibboleth ECP extension:

  1. Add the following code to your local Windows Azure AD metadata file located in the IDP_HOME/metadata:

    <AssertionConsumerService index="2" Binding="urn:oasis:names:tc:SAML:2.0:bindings:PAOS" Location="https://login.microsoftonline.com/login.srf"/>
  2. Add the "saml:SAML2ECPProfile" entry to the Windows Azure AD RelyingParty configuration node in relying-party.xml located in IDP_HOME/config:

    <rp:RelyingParty id="urn:federation:MicrosoftOnline" provider="https://idp.contoso.edu/idp/shibboleth" defaultSigningCredentialRef="IdPCredential">  
                    <rp:ProfileConfiguration xsi:type="saml:SAML2SSOProfile" 
                                    encryptNameIds="never" />                                                      
                    <rp:ProfileConfiguration xsi:type="saml:SAML2ECPProfile"                                                           

Stop and start Apache Tomcat to restart Shibboleth Identity Provider and ensure the updated XML files are loaded. Shibboleth may fail to start if there is a problem with one or more of the configuration files. Check the Shibboleth log files after restart to ensure no errors are reported. We also recommend that you try to sign in and access a previously configured Shibboleth service provider on your network.

Verify the clock on your Shibboleth server is synchronized to an accurate time source. An inaccurate clock time can cause federated logins to fail.

See Also

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
© 2014 Microsoft. All rights reserved.