Office 365 With Shibboleth 2

Before you go down this route, consider all options, for example;

  • If you have ADFS and don't have Shibboleth, you could use ADFS for both Edugate and Office 365 (you'll need FEMMA.py to import federation metadata from Edugate)
  • If you have ADFS and also have Shibboleth, you could use ADFS for Office 365 (or any other Microsoft hosted app), protecting the ADFS login form with Shibboleth and using Shibboleth for Edugate access (or any SAML2 based access). This will give you a single consistent login page without compromising Office 365 functionality or your participation in Edugate.
  • If you have experience with Shibboleth and do not have an existing ADFS deployment, then read on....

While Microsoft's Office 365 service is not a member of Edugate, an Edugate identity provider that has been implemented using Shibboleth can be configured to authenticate Office 365 users. The guide below is based on Microsoft's Technet article but has been adapted for Edugate participants.

Setting up Office 365 with shibboleth can be summarised in the following steps, which will be expanded upon below;

Shibboleth.

  • Add the Office 365 entity to your circle of trust.
  • Add support for IdPEmail and ImmutableID attributes to your IdP
    • a) in your Shibboleth config.
    • b) in the resource registry. 
  • Protect Shibboleth's ECP handler with LDAP Basic Auth (required by Outlook and other mail clients)

Office 365 

  • Activate Domain Synchronisation on your Office 365 tenant.
  • Convert your domain to a federated domain using Powershell.

Establishing trust between your Shibboleth IdP and Office 365 using the Resource Registry.

  1. Log on the the Edugate Resource Registry at https://edugate.heanet.ie/rr3 (Select 'Login via Edugate' and select your institution i.e. Kilkenny College).
  2. Once logged in, select the Identity Provider menu, and then select  the List submenu. Type your institutions name in the Filter field or scroll down the list until you find your institution.
  3. Click on your institution, and scroll down to the Federations section of the page, you will see what federations your institution is a member of (for example, 'Edugate' and 'Kilkenny College Campus Federation' are the federations that Kilkenny College particiapte within.
  4. Select your institutions campus federation (Kilkenny College Campus Federation will be used in this example).
  5. Scroll down to the 'Membership management' section and click on the arrow beside 'Add new Service Providers to the federation without invitation'.
  6. Find 'Microsoft Office 365'  in the list and tick the checkbox beside it and click 'Submit' (you will see a confirmation message that the service was added to the federation).

The above steps will result in your institutions identity provider receiving a copy of the Offie 365 metadata when it refreshes its metadata. However, this is only part of the process, there is another  step to be completed later to provide your Identity Providers metadata to Office 365 using Powershell.

Your Identity Provider must share two user attributes with Office 365, first we will declare that your IdP supports those attributes, then we will configure a policy to release these attributes and lastlty configure your Identity Provider to extract the attributes from Active Directory.

  1. From the Resource Registry, select the Identity Provider menu, and then select  the List submenu.
  2. Type your institutions name in the Filter field or scroll down the list until you find your institution.
  3. Click on your institution and scroll down to the 'Supported Attibutes' section and click on the edit icon.
  4. Find IdPEmail and ImmutableID from the list and tick the checkbox and then cick 'Save'.
  5. The list of attributes will be presented again, at the top of the click on the arrow beside 'Attribute Release Policies'.

It is good practice to always set a default policy for newly supported attributes, so we will set a policy to deny the release of these attribute by default and then set a specific policy to allow the attributes to be provided to Office 365.

  1. Click on the 'Set defaut policy for new supported attributes' button and configure both ImmutableID and IdPEmail to be 'never' released (click on the 'Add default policy' button).
  2. Enter the words 'Office 365' in the 'Select Service Provider' drop down box (at the top of the page), select Microsoft Office 365 from the list that appears and then click on the Go button.
  3. Configure ImmutableId and IdPEmail to be 'released only when required' and then click on Modify to save your policy.

Now that the policy has been set, we must configure Shibboleth to extract the attributes from Active Directory (it is assumed that your identity provider is already configured to extract most user attributes from Active Directory). Edit your Shibboleth identity provider's attribute-resolver.xml file (locted in /opt/shibboleth-idp/conf/ or c:\Program Files (x86)\Internet2\Shib2IdP\conf\ for default deployments).

Add the following stanza's

<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" nameQualifier="https://hostname/idp/shibboleth" nameFormat="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" />
</resolver:AttributeDefinition>
and
<resolver:AttributeDefinition id="UserId" xsi:type="ad:Simple" sourceAttributeID="mail">
<resolver:Dependency ref="myLDAP" />
<resolver:AttributeEncoder xsi:type="enc:SAML2String" name="IDPEmail" friendlyName="UserId" />
</resolver:AttributeDefinition>

Where myLDAP references your connection to Active Directory as defined at the bottom of attribute-resolver.xml and nameQualifier is the entityID of your Identity Provider. The Active Directory 'mail' attribute is expected to contain the Office365 email address of the user.

(Note: the objectGUID attribute should be declared as a binary attribute if it is not already within the myLDAP confiugration at the bottom of attribute-resolver.xml, see the example on Microsoft's Technet article).

Restarting Tomcat will apply changes to attribute-resolver.xml

Establishing trust between Office 365 and Shibboleth using Powershell.

Shibboleth is ready to trust Office 365, but Office 365 is not configured to trust your identity provider. We will return to Shibboleth later to configure Basic Auth for Shibboleth ECP handler (to support mail clients). 

Download Microsoft's 'Windows Azure Active Directory Module for Windows Powershell' to a Windows host that meets the requirements. TheMicrosoft Online Services Sign-In Assistant should also be installed. Once installed, right-click the Windows Azure Active Directory Module for Windows PowerShell shortcut to open a Windows PowerShell workspace and enter the following command;

$msolcred = get-credential

This will present a dialogue box where you enter administrator credentials for your Office 365 tenant. Enter your credentials and then enter the following command;

connect-msolservice -credential $msolcred

You should now be connected to your tenant and the following commands should be run;

$dom = "<your 365 domain>”
$url = "https://<youridphost>/idp/profile/SAML2/POST/SSO"
$ecpUrl = "https://<youridphost>/idp/profile/SAML2/SOAP/ECP"
$uri = "https://<youridphost>/idp/shibboleth"
$logouturl = "https://<youridphost>/idp/logout.jsp"
$cert = "<your IdP's certificate"

Where your IdP's certificate is the text of your IdP's certificate (your IdP's certificate will be in /opt/shibboleth-idp/credentails/idp.crt or C:\Program Files (x86)\Internet2\Shib2IdP\credentials\idp.crt for default deployments). Once the Powershell variables have be set, you can convert your domain from a standard domain to a federated domain with the following command

Set-MsolDomainAuthentication –DomainName $dom -FederationBrandName $dom -Authentication Federated  -PassiveLogOnUri $url -SigningCertificate $cert -IssuerUri $uri -ActiveLogOnUri $ecpUrl -LogOffUri $logouturl -PreferredAuthenticationProtocol SAMLP

You can check these settings at any time with the command;

Get-FederationInformation -DomainName <yourdomain> -verbose.

Trust is now established in both directions between Office 365 and your identity provider.  The next step is to synchronise your domain with Office365.

Synchronising user accounts between Active Directory and Office 365.

This guide assumes you have activated 'Active Directory Synchronisation' (a process that takes approximately 24hrs). Microsoft recommend running the 'Microsoft Deployment Readiness Tool' before running the 'Directory Sync Tool' (this recommendation is not followed here).

The Directory Sync Tool will require the administrator credentials of your Office 365 tenant as well as an account on Active Directory that has read access over all user objects. Run the Directory Sync Tool Configuration Wizard (tick the checkbox 'Start Configuration Wizard Now' when prompted) and enter the credentials descibed above when prompted. Select 'Synchronise directories now' and click finish. Allow a few minutes to pass  and then check the Office 365 administration portal for newly synchronised user accounts.

Advanced synchronisation allowing the selection of attributes other than objectGUID or mail can be achieved with Forefront Identity Manager (the Directory Sync Tool is a version of FIM).

Testing SSO with federated accounts.

Select a federated user from Office 365 admnistration portal and in a diffrent browser (or private browsing session) attempt to access the Office 365 administration portal, entering the username@domainname (not @onmicrosoft.com) into the username field. Office 365 will check the username and identify it as a federated user and redirect you to your institutions identity provider. Enter the username/password of the user (without the domain name), upon sucessfull authentiaiton at you identity provider, you should be redirected back to the Office 365 administration portal where you should be authenticated as a non-administrator user.

You can now allocate Office 365 licences to federated users, and when those user attempt to access the licensed services the same login process will occur (try http://outlook.com/owa/<yourdomain>)

Support for desktop mail clients (i.e. Outlook, Thunderbird etc.)

If you are availaing of Office 365's email service, the you will need to configure your IdP to work with desktop mail clients such as Thunderbird (8/9) or Outlook (2010 or later). To achive this we will configure the identity provider to support the SOAP based SAML ECP profile by enabling authentication on the web-server for the ECP endpoint. The mail client collects the username/password, passes it securly to Office 365 (over imap/pop3) which in turn will generate a SOAP based Authentication Request to the the identity provider. The identity provider web-server performs authentication and sets a REMOTE_USER web server variable, this value of the variable is taken by the identity provider and used with the attribute-resolver.xml to construct a SOAP reply to the Office 365 PAOS endpoint, this will return a successfullly authenticated session to the mail client.

Protect Shibboleth's ECP endpoint with HTTP Basic Auth.

This step can be configured in Tomcat if it is configured as a standalone web-server, or within IIS (if it is placed in front of a Tomcat instance). This guide assumes a unix Apache webserver is placed in front of a Tomcat instance.

Edit the Apache configuration for the relavent virtual host configuration file (which should already contain proxy references to  /idp) and add the following stanza;

<Location /idp/profile/SAML2/SOAP/ECP>
AuthType Basic
AuthName "Username/Password"
AuthBasicProvider ldap
AuthLDAPUrl "ldap://yourhost:yourport/DC=<your>,DC=<base>,DC=<dn>,DC=local?sAMAccountName?sub?(objectClass=*)" NONE
AuthLDAPBindDN "CN=<your AD service account>,DC=<your>DC=<base>,DC=<dn>,DC=local"
AuthLDAPBindPassword "<password>"
AuthzLDAPAuthoritative OFF
Require valid-user
</Location>

Restart Apache to apply these changes.

Before you can test this change with a mail client, you wil need to determine the IMAP and SMTP hosts/ports for your federated users, the easiest way to find this information is to log into the https://outlook.com/owa/<yourdomain> and select Settings menu under your account (top right) there will be a link to 'Settings for POP or IMAP Access'

Mail clients differ, but you will need three piece of information for your client

  • Mailbox type: IMAP/POP3
  • Username: username@yourdomain (e.g. ffinlay@your.edu.ie)
  • servername:  e.g. pod5100N.outlook.com or outlook.office365.com 
  • passsword: the users Active Directory password.

(Office365 uses SSL on port 993 for IMAP  / port 995 for POP / TLS port 587 for SMTP)

OpenSSL can be used to connect and test, using the following example;

[root@localhost] openssl s_client -crlf -connect pod51002.outlook.com
[CONNECTED]
USER ffinlay@your.edu.ie 
PASS: PasswordIsGod
[Authentication succeeded]

Note: There are subtle relying-party.xml diferrences between versions of Shibobleth.  It is recommended to add explicit relying party entries for Office 365 to ensure messages are signed/encrypted in the format expected by Office 365. The following can be used as a template and should be added after the closing DefaultRelyingParty tag.

<rp:RelyingParty id="urn:federation:MicrosoftOnline" provider="https://<yourhost>/idp/shibboleth" defaultSigningCredentialRef="IdPCredential">
<rp:ProfileConfiguration xsi:type="saml:SAML2SSOProfile" signAssertions="conditional" encryptAssertions="never" encryptNameIds="never" />
<rp:ProfileConfiguration xsi:type="saml:SAML2ECPProfile" includeAttributeStatement="true" assertionLifetime="PT5M" assertionProxyCount="0" signResponses="never" signAssertions="always" encryptAssertions="never" encryptNameIds="never"/>
</rp:RelyingParty>

Support for OneDrive for Business (formerly SkyDrive) and Skype for Business (formerly Lync) on Desktop or Mobile.

Federated login to Office desktop applications others than Outlook require a feature called ADAL to be enabled. 

  • Office for Windows 2016 (in preview) supports federated login to OneDrive, Office for Mac 2016 supports federated login (available now)
  • Office 2013 for Windows supports federated login with a the registry key update outlined in this Microsoft article, this feature is in public preview.
  • Further details on current versions of Office prodducts that support federated login are outlined in this Microsoft article