Configure Shibboleth for use with single sign-on

  • Article

Updated: June 25, 2015

Applies To: Azure, Office 365, Power BI, Windows Intune

This topic contains detailed instructions on how to configure Shibboleth Identity Provider to federate with Azure AD to enable single sign-on access to one or more Microsoft cloud services (for example, Microsoft 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 Azure AD.

Important

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.

Important

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 Azure AD metadata

  2. Add 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

Important

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.

Add Azure AD metadata

Shibboleth Identity Provider needs information about the Azure AD relying party. Azure AD publishes metadata at https://nexus.microsoftonline-p.com/federationmetadata/saml20/federationmetadata.xml. It is recommended that you always check for the latest 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" />
    <NameIDFormat>
      urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
    </NameIDFormat>
    <NameIDFormat>
      urn:mace:shibboleth:1.0:nameIdentifier
    </NameIDFormat>
    <NameIDFormat>
      urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
    </NameIDFormat>
    <NameIDFormat>
      urn:oasis:names:tc:SAML:2.0:nameid-format:transient
    </NameIDFormat>
    <NameIDFormat>
      urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
    </NameIDFormat>
  </SPSSODescriptor>
</EntityDescriptor>

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

Important

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.

Add Azure AD as a relying party

You have to enable communication between Shibboleth Identity Provider and Azure AD by defining a new RelyingParty element in the IDP_Home/conf/relying-party.xml file. 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 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:

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

You must also specify to Shibboleth Identity Provider where to find the file that contains the 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:

<!—- 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"/>

Configure the Shibboleth attribute resolver

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:

  • Azure AD ImmutableID

    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 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 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 Microsoft 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"
          sourceAttributeID="objectGUID">
   <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" />
  </resolver:AttributeDefinition>

    Important

    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"
                   ldapURL="ldap://MyADServer:389"
                   baseDN="CN=Users,DC=MyDomain,DC=ORG"
                   principal="CN=Administrator,CN=Users,DC=MyDomain,DC=ORG"
                   principalCredential="A.useful.p!w.d">
  <FilterTemplate>
    <![CDATA[
                (uid=$requestContext.principalName)
            ]]>
  </FilterTemplate>

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

</resolver:DataConnector>

  • Azure AD User ID

    Azure AD requires that the 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 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" />
</resolver:AttributeDefinition>

Configure the Shibboleth attribute filter

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

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

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

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

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

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

</afp:AttributeFilterPolicy>

Optional: Install the Shibboleth ECP Extension

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 Azure AD. This extension implements the SAML 2.0 ECP specification. When you configure single sign-on with 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 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 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" 
                                signAssertions="conditional" 
                                encryptAssertions="never"                          
                                encryptNameIds="never" />                                                      
                <rp:ProfileConfiguration xsi:type="saml:SAML2ECPProfile"                                                           
                                signAssertions="always"                  
                                encryptAssertions="never"                  
                                encryptNameIds="never"/>                                                             
</rp:RelyingParty>

Restart Shibboleth and verify functionality

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.

Note

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

Concepts

Use Shibboleth Identity Provider to implement single sign-on