You are viewing an earlier version of the admin guide. For the latest version, please visit EmpowerID Admin Guide v7.211.0.0.

Setting up SSO with Office 365

Owned by Phillip Hanegan
Last updated: Nov 12, 2019Version comment

The EmpowerID SSO framework allows you to federate EmpowerID with Office 365 without requiring you to set up Active Directory Federation Service (ADFS) or DirSync. In this scenario, the EmpowerID Security Token Service (STS) replaces ADFS, making EmpowerID the identity provider for your organization's Office 365 services.


If Windows Azure AD Module for Windows PowerShell and Microsoft Online (MSOL) Sign-In Assistant are already installed on your EmpowerID server, you must remove them before installing the newer versions.


Prerequisites

You must have a licensed corporate Office 365 account and Connecting to Office 365.

The Account Store that you connect it with must not have any spaces in the name.

You must install the following modules in this order on the machine on which you configure the SSO Connection.

  1. Windows Management Framework 5.1 — This version provides functionality that EmpowerID uses to communicate with Office 365, including the newest version of Windows PowerShell.

  2. To verify the version, run $PSVersionTable.PSVersion in PowerShell. The version must be Major 5 Minor 0 or higher.

  3. Windows Azure AD Module for Windows PowerShell Version 1.1 — This provides you with the Office 365 cmdlets necessary for administering Office 365. To install the module run  Install-Module -Name AzureAD in PowerShell. 

  4. If you see a message stating that you're installing modules from an untrusted module, enter A to continue.

  5. After installing Windows Azure AD Module for Windows PowerShell Version 1.1, run  Import-Module -name MSOnline -MinimumVersion 1.1.166.0 -MaximumVersion 1.1.166.0 to import MSOnline. 

  6. If you see the below messages, enter Y for both.
    • PowerShellGet requires NuGet provider version '2.8.5.201' or newer
    • You are installing the modules from an untrusted repository

  7. Once finished, run  Import-Module MSOnline

  8. After importing the module, run  Get-Module MSOnline to confirm the version. The version must be 1.1.166.0.  Version 1.1.183.8 is not compatible. 


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 passwords. This ensures that their EmpowerID Person does not become locked out for a password mismatch between their EmpowerID Person password and an Office 365 password that is saved in a rich client application such as Outlook or Lync. 

You can create any number of O365 Ws-federation connections in latest versions of EmpowerID. Each O365 domain can have its own passive endpoint url and issuer. The name of the connection merely needs to include the word “office365” or “Office365”. These are examples of legitimate O365 Ws-federation connection names:
  • MyOffice365TenantA
  • TenantBOffice365
  • Office365TenantC

To create a WS-Federation Connection

  1. In the navigation sidebar, expand Admin, then SSO Connections, and click WS-Federation.
  2. Click the Actions tab, and then click the Create WS-Federation Connection button.



  3. On the General tab of the Connection Details screen that appears, under WS-Federation Connection Type, select Service Provider.



  4. In the Service Provider Details section that appears, click WS-Federation Service Provider Template and select Default SSO Connection Settings. 



  5. In the General Details section, do the following:

    1. Enter a name and description in the Name, Display Name, and Description fields.

      The name of the connection cannot contain any spaces.

    2. Leave the Reply To Address, Realm, and Relying Party initiated login? fields empty and cleared.



  6. In the ADFS-Like Token Details section, do the following:
    1. Leave Is ADFS Token and Is ADFS Email Claim Identity cleared.

    2. In the Issuer field, enter https://sso.empoweriam.com/WebIdPWSFederation/365/EDDocsOffice365
      replacing sso.empoweriam.com with the FQDN of your EmpowerID front-end server, and replacing EDDocsOffice365 with the name of your SSO Connection.

  7. In the Tile Information section, for the Tile Image URL, leave the path intact and change Genric-1.png to office-365.png. This places the Office 365 logo on the login tile for the connection.

  8. In the Initiating URL field, enter the below URL, changing empoweriam.com to your domain.

    https://login.microsoftonline.com/login.srf?wa=wsignin1.0&whr=empoweriam.com

  9. Under Single Logout Configuration, enter the following URL in the Logout URL field.

    https://login.microsoftonline.com/logout.srf

  10. In the Account Information section, click Select existing Account Directory and then select your Office 365 account store.



  11. In the Relying Party Trust section, in the Trust Identifier URI field, enter urn:federation:MicrosoftOnline.
  12. Click in the Signing Certificate field, press Enter, and select your signing certificate. 



  13. Click Save.

Next, create an SSO application for Office 365.

To create an SSO application for Office 365

  1. In the navigation sidebar, expand Applications and click Manage Applications.
  2. From the Actions pane of the Applications page, click Create Application. 



    This opens the Application Details form, which contains tabs and fields for creating the application.



  3. On the General tab, configure these options for the application:
    1. Name, Display Name and Description — Enter Office 365.
    2. Icon — Leave the path intact, but change the file name from Genric-1.png to office-365.png.
      This displays EmpowerID's Office 365 image to users in their EmpowerID Personal Applications page.
    3. Full URL (Exact Match Path) — Leave this field blank as it is not used for Office 365.
    4. Base URL for HTTP Module — Leave this field blank as it is not used for Office 365.
    5. Allow Access Requests — Leave this option selected to allow users to request or claim accounts in the application in the IT Shop.
    6. Allow Claim Account — Leave this option selected to allow users to claim an account in the application from the IT Shop.
    7. Allow Request Account — Leave this option (and Allow Access Requests) selected to allow users to request an account in the application.
    8. Login Is Email Address (Receive OTP to Claim) — Select this option (required for Office 365) to pass identity assertions to the application when logging in from EmpowerID and to send a one-time password to users claiming an account.
    9. Make me the Application Owner  — Select this to own the application. Application owners can manage the application and approve or deny access requests.
    10. Configure Advanced Claim and Request Account Options  — Only select this option if you have custom pages and workflows configured for processing access requests and managing any accounts linked to the application's EmpowerID account directory. Additional fields appear when you select it.
    11. Is Fulfillment Group Centric — This option is ignored unless the application is tracking only.
    12. Fulfillment Workflow — Leave this option blank as it is only used for tracking-only applications.



  4. On the Single Sign-On tab, do the following:

    1. Click Single Sign-On Connection Type and select WS-Federation.

    2. Click in the WS-Fed Connection field, press Enter, and click the tile for the Office 365 connection created earlier.



  5. On the Users tab, click Select existing Account Directory and select your Office 365 Account Store.

    EmpowerID uses this directory to map your Office 365 users with their corresponding EmpowerID Persons. You must add this Account Store to EmpowerID to have it appear in the drop-down.




  6. Click Add to cart.
  7. Click the shopping cart icon at the top of the page, and in the Cart dialog that appears, enter a reason for creating the application and then click Submit.



To configure access for the application

  1. After EmpowerID creates the application, click the Find Applications link in the breadcrumbs at the top of the page.



  2. Search for the Office 365 application you just created and click the Display Name link for it. 



  3. 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.



  4. To add owners who can manage the application, expand the Owners accordion, and in the Enter name to add field, enter a person's name and click the tile for that person.



  5. The Added flag increments with the number of owners to add. Click Submit to add the owners to the grid.



  6. To ensure that all users with an Office 365 account can access the application, expand the Who Has Access To Application accordion and do the following:
    1. Drop down the Assignee Type and select Business Role and Location.
    2. Click the Add (+) button on the Assignee grid.



      This opens the Grant Access dialog. Use this dialog to select the Business Role and Location for which you are granting access as well as the Access Level you are granting it.



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



    6. 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 already 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

This is an optional step that is only required when the DNS for your server and the domain name you registered in Office 365 are not the same. These values must match for SSL endpoints to function correctly. By setting a DNS, you are directing the EmpowerID services to ignore the machine's FQDN and use the Public DNS in its place.

  1. In the Navigation Sidebar, expand Admin, then EmpowerID Servers and Settings and click EmpowerID Servers.
  2. From the EmpowerID Server Details page, click the EmpowerID Servers tab and search for the server whose role you want to set.
  3. Click the Edit button for that server.



  4. In the dialog that appears, enter the DNS Alias in the PublicDns field and click Save.

    The value entered here must be found in the SSL Certificate (i.e., Subject Name, SAN Cert, etc.).

  5. Restart the EmpowerID services on that server.

To export the EmpowerID Certificate in base64-encoding format

  1. From the server with your federation certificate, browse to the C:\Program Files\TheDotNetFactory\EmpowerID\Programs\System Certificates folder and locate your federation certificate.



  2. Next, right-click the certificate and select Install PFX.


     
  3. Select Local Machine and click Next.



  4. Click Next.
  5. Enter the password for the private key, select Mark this key as exportable and click Next.



  6. Select the Automatically select the certificate store based on the type of certificate option then click Next.



  7. Click Finish.
  8. From MMC, open the Certificates snap-in for the Local Computer and locate the federation certificate in the Personal Store.



  9. Right-click the certificate and select All Tasks, then Export from the context menu.



  10. In the Certificate Export Wizard that appears, click Next.
  11. Select No, do not export the private key and click Next.



  12. Select Base-64 encoded X.509 (.CER) and click Next.



  13. Select an export location, naming the exported certificate and click Next.
  14. Click Finish to complete the export.
  15. Open the exported certificate in a text editor and remove the first and last lines:
    ----BEGIN CERTIFICATE---- 
    ----END CERTIFICATE----



  16. 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. To connect to Microsoft Online, run the following command in PowerShell.
  2. In the Sign in to your account window that appears, enter the email address of a global administrator of your Office 365 account and click Next, then enter the password and click Sign In.



  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 the domain name that you own, e.g. mydomain.com.

    You cannot federate the default domain, e.g., domain.onmicrosoft.com, Microsoft created for your organization when you registered for an Office 365 account. You must add one or more other domains to your Office 365 account, such as mydomain.com, and allow Microsoft to verify that you own those domains. After Microsoft verifies your ownership, you can federate it with EmpowerID.

    This command is only necessary if the account was created in Office 365. Do not run the command if you are using DirSync.

    To get all licensed users and their immutable IDs, run 

  4. 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.

    Replace the values with those specific to your environment. For example, the name of our domain is "mydomain.com," so the value of $dom and $FederationBrandName is "mydomain.com," and the name of our connection in EmpowerID is Office365k.

    Run each line of code separately in PowerShell.

    The values for the IssuerUri, LogOffUri, and PassiveLogOnUri are the same and point to the Issuer you set up when you created the WS-Fed connection above:

    https://<FQDN-Of-Your-EmpowerID-Font-End-Server>/WebIdPWSFederation/365/<Name-Of-Your-SSO-Connection>

    The value set for the IssuerURI does not need to be a resolvable DNS; however, it does need to be unique in Office 365. An IssuerURI cannot be used for more than one connection or tenant.

    The values for the ActiveLogOnUri and mex variables contain the name of your SSO Connection followed by ActiveSTS.svc and ActiveSTS.svc/mex, respectively.

     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 need to run the cmdlet each time you add a tenant to set the default domain for those tenants. Be sure to replace "mydomain.com" with the fully qualified domain name your Office 365 account was given by Microsoft when first created.

  5. Use the cmdlet below to set the Federation Authentication Mode to WS-Fed for the Office 365 domain. Enter the cmdlet as one line.

    If necessary, you can revert the domain from federated to managed by using the following PowerShell cmdlet.

  6. Use the following cmdlet to update your Office 365 Domain with the federation settings. Enter the cmdlet as one line.

  7. Run the following cmdlet to verify your settings.


    You should see the federation settings you entered above reflected in the output.



  8. Close your session by running the following cmdlet.

If you are using Skype for Business, please see the Configuring Skype for Business Online topic for instructions. If you are using Exchange Online, please see Configuring Exchange Online Modern Authentication for Federation.

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 Next. A message should 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 is the same as that used for accessing Office 365.

    If you have yet to claim an account, EmpowerID will direct you to register the account to your person.

  4. EmpowerID verifies your identity and redirects you back to Office 365.




In this article