Office 365 SAML Configuration

Introduction

This article outlines the information and steps you need to take in order to configure Office 365 to use the Hypersocket SAML Identity Provider. Once configured your users will be redirected to your Hypersocket Server to authenticate. 

This article assumes you have, or will have an Office 365 domain that is configured fro DirSync with your local Active Directory. You may also use the same instructions to configure Office 365 to use local Hypersocket accounts, however further configuration of users on Office 365 and Hypersocket is required. Please see the instructions at the end of this article.

 

Step 1 - Create the Resource from the Template

Log into your server as admin and navigate to Single Sign On -> SAML. Select Search Templates and select the Office 365 SAML template and click Next.

Enter the domain you are configuring Office 365 with.

Click Next and you should be presented with this article. At this point click on the Goto Article link to open this article in a separate browser window so that you can return to the SAML list of resources where your Office 365 SAML resource should now be present.

 

Step 2 - Download SAML metadata

You will need the metadata from your server in order to configure Office 365. 

In the table of SAML resources locate the Office 365 SAML resource, and click the options icon  to activate the dropdown. Select Download Metadata; this is an XML file that contains information about the Identity Provider and its access points.

 

Before proceeding to the next step, open the XML file containing the metadata and locate the issuer, logon and logoff service URLs. These are located towards the end of the document and will look like

https://demo.hypersocket.com/hypersocket/api/sso/metadata/123456

https://demo.hypersocket.com/hypersocket/api/sso/logon/123456

https://demo.hypersocket.com/hypersocket/api/sso/logoff/123456

Also locate the X509 certificate. You should copy this information into Notepad and edit it as such that the entire certificate is present on a single line.

 

Step 3 - Configure Office 365

These instructions are based on the instructions provided at https://msdn.microsoft.com/en-us/library/azure/dn641269.aspx

You should ensure that you can access Windows PowerShell and have the Azure Active Directory Module for Windows PowerShell installed.

To configure your desired Office 365 domain to use federation with SAML 2.0 then connect to your Office 365 tenant as tenant administrator. This is typically a onmicrosoft.com account.

In PowerShell execute the command

Connect-MsolService 

And enter the credentials in the prompt.

Using the settings you obtained from the Hypersocket metadata XMl file, setup a number of variables in PowerShell for the various options required.

$domain = "mydomain.com"
$issuer = "https://demo.hypersocket.com/hypersocket/api/sso/metadata/123456"
$logon = "https://demo.hypersocket.com/hypersocket/api/sso/logon/123456"
$logoff = "https://demo.hypersocket.com/hypersocket/api/sso/logoff/123456"
$cert = "MIICxzCCAa8CAQAwgYExCzAJBgNVBAYTAkdCMRAwDgYDVQQIEwdFb...."

Then execute the Set-MsolDomainAuthentication command using these variables and some other command line switches

Set-MsolDomainAuthentication -DomainName $domain -FederationBrandName $domain -Authentication Federated -PreferredAuthenticationProtocol SAMLP -PassiveLogonUri $logon -ActiveLogOnUri $logon -LogOffUri $logoff -IssuerUri $issuer -SigningCertificate $cert

Assuming there are no errors in your commands your domain should now be federated and ready to authenticate against your Hypersocket server. 

If you are using DirSync then you need to edit the newly created SAML configuration and in the Alternative Name Value click on the ${} icon and select the ${ImmutableID} variable

If you are manually provisioning users you will need to follow Step 4 to configure your users correctly.

Step 4 - Manually Provision Users

Before users can authenticate to Office 365 the Azure AD user must exist and have an ImmutableID set. If you are using a DirSync domain this is done automatically and so you can skip this step.

To manually provision a user you will first need to create a custom attribute in Access Control->Profile Attributes. Details of how to create an attribute can be found at here.

When you create the attribute, you should ensure it has Admin scope since you do not want your users being able to change this. Take a note of the variable name you assigned to the attribute before returning back here. I recommend you call the attribute "Immutable ID" with a variable name of "ImmutableID". You should also assign the attribute to the Everyone Role.

Once you have created the profile attribute, edit the newly created SAML configuration and in the Alternative Name Value click on the ${} icon and select the ${ImmutableID} variable (or select whatever name you provided for the variable).

Now that you have the profile attribute configured you can create a user in Office 365 executing the following Powershell command. Ensure that their email address is the same as any Hypersocket user you create. In the following command you should enter a value for ImmutableId that is unique to each user, but it cannot be an email address as only alpha-numeric characters are accepted.

New-MsolUser -UserPrincipalName bob@mydomain.com -ImmutableId ABCDEFG12345 -DisplayName "Bob Sanders" -FirstName Bob -LastName Sanders -AlternativeEmailAddress "bsanders@gmail.cxm"

For any existing users in the Office 365 domain you can set an immutable id with the command

Set-MsolUser -UserPrincipalName bob@mydomain.com -ImmutableId ABCDEF12345

Once created, create or edit your Hypersocket user ensuring the email address matches, then after saving, edit the user and you should see your Immutable ID attribute in the Custom attributes view. Enter the same ImmutableID that you provided when creating the Office 365 user and save the user.

Repeat the provisioning process for all your users.

Step 5 -Final Checks

One final step before you start using your Office 365 resource, ensure that you have assigned some Roles to it so that its available for users to use. 

In addition, each user's email address must match their Office 365 logon email and you should have a DirSync domain or manually configured users in Hypersocket as per Step 4.

Once access is assigned log out of Office 365 and then access Hypersocket as a user with the rights to use the new resource. In Browser Resources section under My Resources click the launch icon  to access Office 365.

Users will also be directed to your Hypersocket server logon if they attempt to goto the Office 365 login page.

Have more questions? Submit a request

Comments