Setting up SSO with Office 365

The EmpowerID SSO framework allows you to federate EmpowerID with Office 365 without requiring you to setup ADFS or DirSync. In this scenario, the EmpowerID STS replaces ADFS, making EmpowerID the identity provider for your organization's Office 365 services.

As prerequisites to federating EmpowerID with Office 365, you must have a licensed corporate Office 365 account and have connected EmpowerID to Office 365. Additionally, you must have the following modules installed on the machine in which you are configuring the SSO Connection:
EmpowerID servers that will be connecting to Office 365 that currently have Windows Azure AD Module for Windows PowerShell and MSOL Sign-in assistant installed, will need to have those modules remove before installing the newer versions.
  • Windows Management Framework 5.0 - This framework provides updated management functionality that EmpowerID uses to communicate to Office 365, to include the newest version of Windows PowerShell. You can download the Windows Management Framework 5.0 from Microsoft at: https://www.microsoft.com/en-us/download/details.aspx?id=50395. You must install the framework before installing Windows Azure AD Module for Windows PowerShell Version 1.1. Once you have installed the framework, you can verify the version by running $PSVersionTable.PSVersion in Powershell. The version returned should be Major 5 Minor 0 or higher.
  • Windows Azure AD Module for Windows PowerShell Version 1.1 - This provides you with the Office 365 cmdlets necessary for administering Office 365.
  • After installing Windows Azure AD Module for Windows PowerShell Version 1.1, run Save-Module -Name MSOnline -Path %path% in PowerShell, replacing %path% with the desired path. If you see messages stating that "PowerShellGet requires NuGet provider version'2.8.5.201' or newer" and "You are installing the modules from an untrusted repository", enter Y for both. Once completed, run Import-Module MSOnline in PowerShell. After importing the module, you can confirm you have the appropriate version by running Get-Module MSOnline. You should see version 1.1.166.0 returned.

This topic describes how to federate EmpowerID with Office 365 and is divided into the following activities:

You must first connect EmpowerID to Office 365 before you create the SSO application.
After connecting to Office 365, but before federating it with EmpowerID, it is recommended that the Office 365 users for the federated domain update their EmpowerID password. This is to ensure that their EmpowerID Person does not become locked out to a password mismatch between their EmpowerID Person password and an Office 365 password that is saved in rich client application such as Outlook or Lync.

To create an SSO application for Office 365

  1. From the Navigation Sidebar, navigate to the find protected application resource page by expanding Applications and clicking Manage Applications.
  2. From the Actions pane of Application Manager, click the Create Application action.
  3. This opens the Application Details form, which contains various tabs and fields for creating the application.

  4. From the General tab of the Application Details form, do the following:
    1. Type an appropriate name, display name and description for the application in the Name, Display Name and Description fields, respectively.
    2. Icon - Type ~/Images/AppLogos/office-365.png in this field. This is the path to the Office 365 image provided by EmpowerID. Users with access to the application will see this image representing Office 365 in their Personal Applications page of the EmpowerID Web application.
    3. Full URL (Exact Match Path) - Leave this field blank as it is not used for Office 365.
    4. Allow Access Requests - Specify whether to allow access requests. When this option is selected, the application appears in the IT Shop, allowing users to request or claim an account in the application.
    5. Allow Claim Account - Specify whether to allow users to claim an account in the application from the IT Shop.
    6. Allow Request Account - Specify whether to allow users to request an account in the application. When this option is selected and Allow Access Requests is selected, users can request an account in the application.
    7. Login Is Email Address (Receive OTP to Claim) - Select this option. This setting is necessary for passing the appropriate identity assertion to the application when logging in from EmpowerID and is used by EmpowerID to send a one-time password to users claiming an account.
    8. Make me the Application Owner - Specify whether you are the owner of the application. Application owners have the ability to manage the application and approve or deny access requests.
    9. Configure Advanced Claim and Request Account Options - If you have custom pages and workflows configured in EmpowerID for processing access requests as well as for managing any accounts linked the application's (internal to EmpowerID) account directory, then select this option and provide the appropriate information.
  5. Click the Single Sign-On tab of the form, select WS-Federation from the Single Sign-On Connection Type drop-down and then tick Create a New WS-Fed Connection.
  6. In the WS-Federation Connection Information section that appears, do the following:
    1. Select Default SSO Connection Settings from the WSFederation Application Template drop-down.
    2. Type Office365 in the Display Name field.
    3. Type a description for the connection in the Description field.
    4. In the Issuer field, type the value that best represents the issuer of your Office 365 WS-Fed connection, such as empowerid:mydomain.office365, substituting mydomain with your domain.
    5. The value you place in the Issuer field is the same value that you will pass to Office 365 via PowerShell as the IssuerUri parameter. This value does not need to be a resolvable DNS; it just needs to be a value that you and Office 365 agree upon. Additionally, it needs to be unique in Office 365 as an IssuerUri cannot be used for more than one connection/tenant.
    6. Type https://sso.empoweriam.com/EmpowerIDWebIdPWSFederation/Go365/Office365 in the Initiating URL field, where sso.empoweriam.com is the FQDN or DNS alias of your EmpowerID Web server and Office365 is the display name of the WS-Fed connection.
    7. Type your domain in the Home Realm field.
  7. In the Relying Party Trust section of the form, do the following:
    1. Type urn:federation:MicrosoftOnline in the Absolute Uri field.
    2. Select the certificate used to sign assertions from the Signing Certificate drop-down.
  8. Click the Users tab and select the Office 365 account store you configured for your environment from the Select existing Account Directory drop-down. EmpowerID uses this directory to map your Office 365 users with their corresponding EmpowerID Persons. Please note that you must add this account store to EmpowerID before it will appear in the drop-down.
  9. Click Add to cart.
  10. Click the shopping cart located at the top of the page and in the Cart dialog that appears, type a reason for creating the application and then click Submit.
  11. After EmpowerID creates the application, click the Find Application link in the breadcrumbs at the top of the page.
  12. Search for the Office 365 application you just created and then click the Display Name link for it .
  13. This directs you to the View One page for the application. View One pages allow you to view and manage information about a particular resource object.

  14. Expand the Owners accordion and do the following as needed to make someone an owner of the application. Owners have the ability to manage the application.
    1. Type the name of the person who is to be the owner in the Enter name to add field and then click the tile for that person.
    2. Click Submit.
  15. Expand the Who Has Access To Application accordion and do the following to ensure all users with an Office 365 account can access the application:
    1. Select Business Role and Location from the Assignee Type drop-down.
    2. Click the Add (+) button on the Assignee grid.
    3. This opens the Grant Access dialog. You use this dialog to select the specific Business Role and Location for which you are granting access as well as the Access Level you are granting it.

    4. In the Business Role pane of the Grant Access dialog, search for and select Any Role.
    5. In the Location pane of the Grant Access dialog, search for and select Anywhere.
    6. Select Viewer from the Access Level drop-down.
    7. Click Save.

    Next, set the Public DNS for your server to match the domain name you are federating in Office 365 as described below. If the two match you can skip ahead to Configuring a Trusted Endpoint for the SSL certificate used in your EmpowerID deployment.

To configure an EmpowerID server with a DNS Alias

  1. Log in to the EmpowerID Management Console as an administrator.
  2. From the EmpowerID Management Console, click the EmpowerID logo and select Configuration Manager from the menu.
  3. In Configuration Manager, expand the EmpowerID Servers and Roles node in the application navigation tree and then click EmpowerID Servers.
  4. From the Configuration Manager grid, search for the EmpowerID server for which you wish to add the public DNS alias.
  5. Double-click the record for the target server.
  6. In the EmpowerID Server Details screen that appears, type the DNS alias in the Public Dns field and click Save.
  7. The value entered here must be found in the SSL Certificate (i.e., Subject Name, SAN Cert, etc.).
  8. Restart the EmpowerID services on that server.

To export the EmpowerID Certificate in base64-encoding format

  1. From the server with your certificate, open the console root with the certificates snap-in (usually named Console 1). If you do not have the console configured with the certificates snap-in, open MMC and add the snap-in.
  2. From Console 1, expand the Certificates (Local Computer) > Personal nodes and then click Certificates.
  3. From the Personal certificates store, right-click the certificate you are using in your EmpowerID deployment and select All Tasks > Export from the context menu.
  4. In the Certificate Export Wizard that appears, click Next.
  5. Select No, do not export the private key and click Next.
  6. Select Base-64 encoded X.509 (.CER) and click Next.
  7. Select an export location, naming the exported certificate accordingly and click Next.
  8. Click Finish to complete the export.
  9. Open the exported certificate in a text editor and remove the first and last lines (----BEGIN CERTIFICATE---- and ----END CERTIFICATE----).
  10. Remove all spaces and line breaks so that the certificate appears on one line.

Next, establish trust between Office 365 and EmpowerID as described below.

To establish trust between Office 365 and EmpowerID

  1. From the Start menu, open the Windows Azure AD Module for Windows PowerShell command window and type Connect-MsolService in the command window to connect to Microsoft Online.
  2. In the Enter Credentials window that appears, type the username and password for a global administrator and click OK.
  3. Once you have connected, run the following command to set the ImmutableID on all Office 365 accounts that have the domain specified in the command. Be sure to replace YourDomainName with your domain name.
  4. This command is only necessary if the account was created in Office 365.
    Do not run this command if you are using DirSync.

    Get-MsolUser -DomainName YourDomainName | where {$_.ImmutableId -eq $null -OR $_.ImmutableId -eq ''} | Set-MsolUser -ImmutableId {[guid]::NewGuid().ToString()}

    You can run the following command to return all licensed users and their immutable IDs.

    Get-MsolUser -all | where {$_.isLicensed -eq $true} | select-object userprincipalname, immutableid

  5. Next, set the following variables at the PowerShell prompt for your domain, the federation endpoints and the signing certificate. The following example shows what the values for the variables looked like for our configuration. You need to replace the values with those specific to your environment. For example, the name of our domain is "myempowerid.com," so the value of $dom and $FederationBrandName is "myempowerid.com."
  6. $dom = "myempowerid.com"
        $FederationBrandName = "myempowerid.com"
        $IssuerUri = "https://sso.empowerid.com/EmpowerIDWebIdPWSFederation/365/Office365"
        $ActiveLogOnUri = "https://sso.empowerid.com/EmpowerIDWebServices/Office365ActiveSTS.svc"
        $mex = "https://sso.empowerid.com/EmpowerIDWebServices/Office365ActiveSTS.svc/mex"
        $LogOffUri = "https://sso.empowerid.com/EmpowerIDWebIdPWSFederation/365/Office365"
        $PassiveLogOnUri = "https://sso.empowerid.com/EmpowerIDWebIdPWSFederation/365/Office365"
        $cert = "MIIFYjCCAdagAw..............QKgUSV0rciLpDOYiqAwbP6D"
        
    The values for the ActiveLogOnUri, LogOffUri, and PassiveLogOnUri are the same and point to the Issuer you set up when you created the WS-Fed connection above. The value set for the IssuerURI does not need to be a resolvable DNS; however, it does need to be unique in Office 365 as an IssuerURI cannot be used for more than one connection/tenant . Also, when setting the value for the certificate, be sure to pass in the string without any line breaks, using Base-64 encoding.
    If you received a DefaultDomainUnsetException error when running the above PowerShell cmdlet, you need to specify the domain as the default domain. To fix the error run the below cmdlet. Additionally, you will need to run the cmdlet each time you add a tenant to set the default domain for those tenants. Be sure to replace "empowerid.onmicrosoft.com" with the fully qualified domain name your Office 365 account was given by Microsoft when first created.
    set-msoldomain -name empowerid.onmicrosoft.com -IsDefault
  7. Use the below cmdlet to set the Federation Authentication Mode to WS-Fed for the Office 365 domain. The cmdlet should be entered as one line.
  8. Set-MsolDomainAuthentication -DomainName $dom -FederationBrandName $dom -Authentication Federated -PassiveLogOnUri $PassiveLogOnUri -SigningCertificate $cert -IssuerUri $IssuerUri -ActiveLogOnUri $ActiveLogOnUri -MetadataExchangeUri $mex -LogOffUri $LogOffUri

    If needed, you can revert the domain from federated to managed by using the following powershell cmdlet:

    Set-MsolDomainAuthentication -DomainName $dom -Authentication Managed
  9. Use the following cmdlet to update the Office 365 Domain with the federation settings. The cmdlet should be entered as one line.
  10. Set-MsolDomainFederationSettings -DomainName $dom -FederationBrandName $dom -IssuerUri $IssuerUri -LogOffUri $LogOffUri -PassiveLogOnUri $PassiveLogOnUri -ActiveLogOnUri $ActiveLogOnUri -MetadataExchangeUri $mex -SigningCertificate $cert

  11. Run the following cmdlet to verify your settings:
  12. MSOnlineExtended\Get-MsolDomainFederationSettings
  13. Run the following cmdlet to retrieve the Open Authorization (OAuth) configuration settings currently in use in your organization:
  14. Get-CsOAuthConfiguration
  15. Run the following cmdlet to enable Modern Authentication:
  16. Set-CsOAuthConfiguration -ClientAdalAuthOverride Allowed
  17. When finished run the following cmdlet to close your session:
  18. Get-PSSession|Remove-PSSession
If you are using Skype for Business, please see the Configuring Skype for Business Online topic for instructions.

To test the Office 365 SSO Connection

  1. From your Web browser navigate to the login for Office 365 and enter your username.
  2. click the Password field. You should see a message appear stating that Office 365 is redirecting you to your organization’s sign-in page.
  3. Log in to the EmpowerID Web application as you normally would. The username entered should be the same as that used for accessing Office 365.
  4. EmpowerID verifies your identity and redirects you back to Office 365.