Documentation

Introduction

Use this guide to enable Multi-Factor Authentication for external user access and internal desktop Single Sign-on (SSO) via WS-Federation and WS-Trust to Microsoft Office 365 web and thick applications.

Prerequisites
SecureAuth IdP Prerequisites

1. Create a new realm for the Office 365 integration – this document refers to the realm in this step as Realm A

2. Configure the following tabs in the Web Admin before configuring the Post Authentication tab:

  • Overview – the description of the realm and SMTP connections must be defined
  • Data – an enterprise directory must be integrated with SecureAuth IdP
  • Workflow – the way in which users will access this application must be defined
  • Multi-Factor Methods – the Multi-Factor Authentication methods that will be used to access this page (if any) must be defined

Office 365 Prerequisites

1. Obtain Admin access to an Office 365 account

2. Activate Office 365 Account and Tenant – Welcome to the new Office, Office 365 Developer Site, and Office 365 Readiness Wizard

3. Register a valid domain with Office 365

 Add a domain to Office 365

A. Log on Office 365 account with the .onmicrosoft.com Admin account

B. Click Management, then Domains

C. Click Add a domain

D. Enter the Domain and click Next

E. Verify the Domain per instructions for the domain registrar

F. Select the appropriate services

G. Configure the DNS records on the domain registrar for other services

Click here for more information

Leave the .onmicrosoft.com domain as the primary domain for the account as making the new domain the default causes errors when using the Set-MsolDomainAuthentication command (PowerShell Configuration)

4. Ensure the Microsoft Active Directory Domain Controller has the same domain suffix as the one registered with Office 365

 Add UPN suffixes to a forest

A. Open Active Directory Domains and Trusts

B. Right-click Active Directory Domains and Trusts in the Tree window pane, then click Properties

C. On the UPN Suffixes tab, type the new UPN suffix you would like to add to the forest

D. Click Add, and then click OK

5. Verify the Windows Server is domain-joined for Directory Synchronization

6. Obtain access to a Windows Workstation or Server for Microsoft Online Services Module for Windows PowerShell

This is not required to be domain-joined

7. Acquire a publicly trusted SSL / signing certificate

A third-party certificate is required if using thick clients (Outlook, Lync, etc.)

SecureAuth IdP Configuration Steps

Follow these steps to configure Realm A for external end-user access

NOTE: After configuring this realm, proceed to steps for copying this realm to create Realm B

Data

 

1. In the Profile Fields section, map the userPrincipalName to a SecureAuth IdP Property (e.g. Aux ID 1)

2. Map the objectGUID to a SecureAuth IdP Property (e.g. Aux ID 2)

Click Save once the configurations have been completed and before leaving the Data page to avoid losing changes

Post Authentication

 

3. Select WS-Federation Assertion from the Authenticated User Redirect dropdown in the Post Authentication section

4. The unalterable URL, auto-populated in the Redirect To field, will append to the domain name and realm number in the address bar (Authorized/WSFedProvider.aspx)

User ID Mapping

 

5. Select the SecureAuth IdP Property corresponding to the directory field that contains the objectGUID (Aux ID 2)

6. Select urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified from the Name ID Format dropdown (default)

Select a different option if Office 365 requires it, which the Service Provider (SP) will provide

7. Select True from the Encode to Base64 dropdown

SAML Assertion / WS Federation

 

8. Set the WSFed Reply To/SAML Target URL to https://login.microsoftonline.com/login.srf

9. Set the WSFed / SAML Issuer to https://SecureAuthIdPFQDN/SecureAuthIdPRealm1/ and replace the values with the actual Fully Qualified Domain Name (FQDN) of the SecureAuth IdP server and the number of Realm A e.g. https://secureauth.company.com/secureauth1/

The WSFed / SAML Issuer must match exactly on the SecureAuth IdP side and the Office 365 side

10. Set the SAML Audience to urn:federation:MicrosoftOnline (case sensitive)

11. Set the SP Start URL to https://login.microsoftonline.com/login.srf

12. Select True from the Sign SAML Assertion dropdown

13. Select False from the Sign SAML Message dropdown

No configuration is required for the SAML Consumer URL or the SAML Recipient fields

 

14. Click Select Certificate to select the appropriate publicly trusted SSL / signing certificate

15. Provide the Domain in order to Download the Metadata File to send to Office 365 (if required)

SAML Attributes / WS Federation

 

16. Add IDPEmail as a WS-Federation Attribute in the Name field (Attribute 1)

17. Set the Namespace to http://schemas.xmlsoap.org/claims/UPN

18. Select Aux ID 1 (or the field that contains the userPrincipalName) from the Value dropdown

19. Add ImmutableID in the Name field (Attribute 2)

20. Set the Namespace to http://schemas.microsoft.com/LiveID/Federation/2008/05/ImmutableID

21. Select Base64 Encoded from the Format dropdown

22. Select Aux ID 2 (or the field that contains the objectGUID) from the Value dropdown

Click Save once the configurations have been completed and before leaving the Post Authentication page to avoid losing changes

WS-Trust Endpoint Configuration

 

23. Click View and Configure WS-Trust endpoints

WS-Trust Host Name

 

24. Provide the Fully Qualified Domain Name (FQDN) of the SecureAuth IdP appliance in the Host Name field – e.g. secureauth.company.com

WS-Trust Endpoint Configuration

 

25. Under Endpoint Paths, check to enable /2005/usernamemixed and /2005/windowstransport

Click Save once the configurations have been completed and before leaving the WS-Trust Endpoints page to avoid losing changes

After configuring and testing the configuration, optionally the WS-Trust request blocking feature can be configured to prevent Denial of Service (DoS) attacks on WS-Trust in the Office 365 environment

See WS-Trust Request Blocking Configuration Guide to configure and implement this feature

Forms Auth / SSO Token

 

26. (OPTIONAL) Click View and Configure FormsAuth keys / SSO token to configure the token / cookie settings and to configure this realm for SSO

 To configure this realm's token / cookie settings, follow these steps...
Forms Authentication

 

1. If SSL is required to view the token, select True from the Require SSL dropdown

2. Choose whether SecureAuth IdP will deliver the token in a cookie to the user's browser or device:

  • UseCookies enables SecureAuth IdP to always deliver a cookie
  • UseUri disables SecureAuth IdP to deliver a cookie, and instead deliver the token in a query string
  • AutoDetect enables SecureAuth IdP to deliver a cookie if the user's settings allow it
  • UseDeviceProfile enables SecureAuth IdP to deliver a cookie if the browser's settings allow it, no matter the user's settings

3. Set the Sliding Expiration to True if the cookie remains valid as long as the user is interacting with the page

4. Set the Timeout length to determine for how many minutes a cookie is valid

NOTE: No configuration is required for the Name, Login URL, or Domain fields

Machine Key

 

5. No changes are required in the Validation field, unless the default value does not match the company's requirement

If a different value is required, select it from the dropdown

6. No changes are required in the Decryption field, unless the default value does not match the company's requirement

If a different value is required, select it from the dropdown

NOTE: No configuration is required for the Validation Key or Decryption Key fields

Authentication Cookies

 

7. Enable the cookie to be Persistent by selecting True - Expires after Timeout from the dropdown

Selecting False - Session Cookie enables the cookie to be valid as long as the session is open, and will expire once the browser is closed or the session expires

NOTE: No configuration is required for the Pre-Auth Cookie, Post-Auth Cookie, or the Clean Up Pre-Auth Cookie fields

 To configure a secure portal for SSO...

Click Save once the configurations have been completed and before leaving the Forms Auth / SSO Token page to avoid losing changes

Follow these steps to configure Realm B for internal end-user access via Windows SSO

 

27. Create a New Realm from Existing and select the SecureAuth IdP realm number that corresponds to Realm A in this guide

This action duplicates Realm A to create Realm B

Realm B should be identical to Realm A, with the configuration steps below included

Workflow

 

 

28. In the Workflow section, under Login Screen Options, select Username only from the Default Workflow dropdown

29. Select Public Mode Only from the Public / Private Mode dropdown

Custom Identity Consumer

 

30. Select Token from the Receive Token dropdown

31. Select True from the Require Begin Site dropdown

32. Select Windows SSO from the Begin Site dropdown

33. WindowsSSO.aspx auto-populates the Begin Site URL field

34. Select True from the User Impersonation dropdown

35. Select True from the Windows Authentication dropdown

The User Impersonation and Windows Authentication fields appear only after Windows SSO is selected in step 32

Click Save once the configurations have been completed and before leaving the Workflow page to avoid losing changes

Additional Configuration Steps

Required Configuration for Specific Use Case

If the user's Office 365 user ID is not the same as the sAMAccountName value in the directory, then the following configuration steps are required in Realm B

If the user ID is the same as the sAMAccountName value in the directory, then skip to Office 365 Configuration Steps below

Data

 

1. In the Membership Connection Settings section, modify the searchFilter field to set upn=%v

Click Save once the configurations have been completed and before leaving the Data page to avoid losing changes

System Info

 

2. In the Links section, click Click to edit Web Config file

Web Config Editor

 

3. Locate <add key="WSTrustValidateWithSamAccountName" value="True" /> and set it to False

Click Save once the configurations have been completed and before leaving the Web Config Editor page to avoid losing changes

Office 365 Configuration Steps

This guide should be used for general configuration, though the proposed configuration may not fit every Office 365 environment

SecureAuth is not responsible for configuring the Office 365 application; however, these steps are included to assist customers in preparing their Office 365 environment for the SecureAuth IdP integration

Windows Azure AD for SSO

Office 365 utilizes Microsoft Windows Azure AD in the cloud to store user identities and can be used as a directory store for MS CRM Online, Windows Intune, and Windows Azure

Follow Microsoft's Single Sign-on Roadmap to configure Office 365 for SSO

Read Prepare for Single Sign-on to learn the benefits of SSO and what end-users will experience when they connect from different locations

Ensure the environment meets the requirements to enable SSO and verify the Active Directory is compatible with the SSO requirements

1. Prepare Active Directory by running the Microsoft Office 365 for Enterprises Deployment Readiness Tool

2. Set up and manage Active Directory Synchronization

Follow Configure Filtering for Directory Synchronization to limit the synchronization to a specific organizational unit

3. Install the Microsoft Online Services Sign-in Assistant for IT Professionals

2003-2008 or 2012 only

Windows PowerShell
Install Microsoft Online Services Module for Windows PowerShell

1. Refer to Install Windows PowerShell for Single Sign-on with ADFS

Modules: 64-bit or 32-bit

2. Start Microsoft Online Services Module for Windows PowerShell

Configure Office 365 Domain Federation via PowerShell

Execute PowerShell Commands

Follow the steps in the table below to enter the PowerShell commands

  • Run the commands exactly in the order specified
  • Replace the "DomainName" placeholder with the SecureAuth IdP Domain Name
  • Replace the "SecureAuthIdPFQDN" placeholders with the actual SecureAuth IdP Hostname
  • Replace the "SecureAuthIdPRealm1" and "SecureAuthIdPRealm2" placeholders with the actual SecureAuth IdP realms used for Realm A (SecureAuthIdPRealm1) and Realm B (SecureAuthIdPRealm2)
  • Place quotation marks around the links used, e.g. if the command requires $dom="DomainName", then enter the domain name in quotes ($dom="secureauthdev.com")

NOTE: The entries for DomainName, SecureAuthIdPFQDN, SecureAuthIdPRealm1, and SecureAuthRealm2 are unique to each configuration

1

Connect-MsolService

Function: The Connect-MsolService cmdlet initiates a connection to the online service

2

$dom="DomainName"

Function: The domain name registered with Office 365 (see Prerequisites)

3

$ura="https://SecureAuthIdPFQDN/SecureAuthIdPRealm2/webservice/wstrust.svc/2005/usernamemixed"

Function: The variable containing the SecureAuth IdP FQDN and Office 365 Realm B, followed by /webservice/wstrust.svc/2005/usernamemixed

This URL specifies the endpoint used by active clients when authenticating with domains set up for SSO (identity federation) in Office 365

Example: "https://secureauth.company.com/secureauth2/webservice/wstrust.svc/2005/usernamemixed"

SecureAuthIdPFQDN and SecureAuthIdPRealm2 are unique for every appliance

4

$url="https://SecureAuthIdPFQDN/SecureAuthIdPRealm1/"

Function: The variable containing the SecureAuth IdP FQDN and Office 365 Realm A

This URL is to where web-based clients are directed when signing into Office 365

Example: "https://secureauth.company.com/secureauth1/"

5

$uri="https://SecureAuthIdPFQDN/SecureAuthIdPRealm1/"

Function: The variable containing the SecureAuth IdP FQDN and Office 365 Realm A

This is the unique identifier of the domain in the Office 365 platform that is derived from the federation server

Example: "https://secureauth.company.com/secureauth1/"

The uri command and the WSFed/SAML Issuer in the SecureAuth IdP Web Admin must match exactly, including the trailing forward slash "/"

6

$logouturl="https://SecureAuthIdPFQDN/SecureAuthIdPRealm1/wsfedsignout.aspx"

Function: The variable containing the SecureAuth IdP FQDN and Office 365 Realm A, followed by /wsfedsignout.aspx

This is the URL to where users are redirected to sign out of Office 365

If both IdP-initiated and SSO are used and issues are encountered when logging in, then contact Support

Example: "https://secureauth.company.com/secureauth1/wsfedsignout.aspx"

7

$metadata="https://SecureAuthIdPFQDN/SecureAuthIdPRealm2/webservice/wstrust.svc/mex"

Function: The variable containing the SecureAuth IdP FQDN and Office 365 Realm B, followed by the metadata location /webservice/wstrust.svc/mex

This URL specifies the metadata exchange endpoint used for authentication from rich client applications, such as Lync Online

Example: https://secureauth.company.com/secureauth2/webservice/wstrust.svc/mex"

8

$cert="<CERT VALUE>"

Function: The variable containing the Certificate Value of the certificate used to sign tokens passed to the Office 365 identity platform

Replace <CERT VALUE> with the actual value

Export the certificate used in the SecureAuth IdP Web Admin for signing the WS-Federation Assertion

1. Export the SSL certificate in Base64 format

2. Open the exported certificate in a text editor (Windows Notepad or Notepad++)

3. Remove the Begin Certificate and End Certificate lines from the file

4. Remove all returns (CR-LF) so that the certificate value is one line of text with no formatting

9

Set-MsolDomainAuthentication -DomainName $dom -FederationBrandName $dom -Authentication Federated -PassiveLogOnUri $url -ActiveLogonUri $ura -MetadataExchangeUri $metadata -SigningCertificate $cert -IssuerUri $uri -LogOffUri $logouturl -PreferredAuthenticationProtocol WsFed

Function: This command configures Office 365 with the variables set in previous lines (above)

Verify Office 365 Account Configuration

Verify the Office 365 account is configured correctly by entering this code into Azure PowerShell: Get-MsolDomainFederationSettings -DomainName <DomainName> and replacing "<DomainName>" with the actual domain name, e.g. Get-MsolDomainFederationSettings -DomainName secureauthdev.com

Review all information and confirm the configuration is correct

Correct Errors

If an error appears, then run this command to modify any incorrectly configured variable: Set-MsolDomainFederationSettings

For example, changing the $ura variable and then running the Set-MsolDomainFederationSettings -ActiveLogOnUri $ura changes the ActiveLogOnUri value to the new $ura variable

 

PowerShell Issues and Federation Settings

  • If the Set-MsolDomainAuthentication command is not working in PowerShell, run PowerShell without the DomainName $dom and Authentication Federated variables; PowerShell then prompts for the domain name and Federated domain
  • Verify the Federation settings on the domain by running the command Get-MsolDomainFederationSettings -DomainName <DomainName>
  • A certificate issued from a trusted source may be required; if a certificate from a trusted source is added, use the certificate console to modify the permissions on the new certificate and add Network Service read permissions to the Private Key
Additional Configuration Option

Office 365 Tenant - Multi-domain Support

If the Office 365 tenant contains multiple domains to be federated for authentication, then Microsoft requires the domain to be created with the SupportMultiDomains flag set to True

If the domains were created without the flag, then the domain must be updated

Refer to Microsoft's Documentation for information on how to create, update, and remove domains in an Office 365 tenant

When federating for authentication, each domain in a Office 365 tenant must have a unique Issuer

SecureAuth IdP supports the ability to dynamically send an Issuer from one realm using the authenticating user's userPrincipalName to pull an Issuer from a configuration setting

For each federated domain in Office 365 for authentication, note the Issuer used in the configuration steps above

To enable the dynamic Issuer feature of SecureAuth, contact SecureAuth support by opening a ticket at https://support.secureauth.com/ or visit support.secureauth.com

Troubleshooting
Resolve Authentication Issues Using Firefox

If authentication issues appear after being passed through SecureAuth IdP, then use Firefox with SAML Tracer to view the POST to Office 365. Within the POST, identify the UPN, ImmutableID, and NameID in the Parameters tab. Use the Microsoft Online PowerShell to log in and check these values against the user by running Get-MsolUser -UserPrincipalName user@company.com | fl *

Update Federated Domain Properties after Federation

If the Federated Domain Properties (LogOutUri, MetadataExchangeUri, etc.) need to be updated, then update each of them using Set-MsolDomainFederationSettings (MSDN Technet Details). Additionally, verify the current Federated Domain settings by using Get-MsolDomainFederationSettings.