PowerShell for Office 365 and Hybrid

With the move to Office 365, one of the things that can become a problem, is the ability to manage the tenant and its services successfully. The user interfaces though great, does not always allow for the types of changes and updates that are needed. One of those configuration steps is setting up Hybrid. There is not user interface within the core tenant to achieve this, so PowerShell has to be used. In my past webinar from last week on SharePoint 2016 Hybrid, we used lots of PowerShell to configured the On-Premises Environment to an Office 365 Tenant. In this post lets walk through this PowerShell, along with links to download them.

Download All PowerShell Scripts: https://1drv.ms/u/s!An6eWkVI7cMNgYwP-WaQ11helkDgjg

The download file contains the following PowerShell Scripts:

To create the infrastructure needed you will notice that two of the files were created by Microsoft, these two files are: “CreateCloudSSA.ps1“and “Onboard-CloudHybridSearch.ps1”. You don’t actually have to use the “Create Cloud Search Service Application” one if you already have one that you use. I won’t walk through all the steps to get this to work, you can head over to watch the webinars that I just gave on this here:

http://sharepointpromag.com/sharepoint-2016-hybrid

However, the logical order is:

1.Replace Default Secure Token Certificate

2.Upload Secure Token Certificate to SharePoint Online

3.Add Service Principal Name to Azure Active Directory

4.Register SharePoint Online Application Principal ID

5.Set SharePoint Authentication Realm

6.Configure On-Premises Proxy for Azure Active Directory

7.Create Cloud Search Service Application

8.Onboard Cloud Hybrid Search

The PowerShell itself can be complex, but actually for this type of configuration everything works really well. To replace the Secure Token Certificate, you of course need a new certificate, which you can then use within the PowerShell. The script requires a couple of variables that will then be used throughout the process. The key here is to use the same PowerShell Window for all scripts so that the variables are persistent and available for every other script.

The core command used here is “Set-SPSecurityTokenServiceConfig”, which is ran on the local On-Premises SharePoint Server ONLY. This will swap out the core certificate and then you will need to run an IISRESET and restart the Timer Service on all Servers in the farm.

Once done we then move to our Office 365 Tenant where we now make a connection to the tenant, then upload the exported certificate in PFX format to our Tenant, so that it is set as the trust between the On-Premises and Cloud Services.

This code using a couple of methods, the main one after importing all the core modules that are required. Note you will need to have installed the relevant Microsoft add-ons for Office 365 and Azure in order for these import statements to work. You can get the downloads here:

If you already had a PowerShell windows open, you will need to close it and launch it again also to get these to work.

Now we have it set we can use the core method here which is “Connect-MsolService” passing in credentials of the Office 365 Tenant. Once we have a connection then we populate the various variables for the core certificate, such as PFX path, password, CER path, along with all the pieces needed for the SharePoint Site. You will notice that some of these are simply populated from other variable values, such as “$sharePointOnlineContextID” which comes from a standard method that is available once the initial connection is made available.

PowerShell commands are used to generate the certificate “Package” as I call it, so it is ready to be accepted by Office 365.  Once done the main method is “New-MsolServicePrincipalCredential” that will actually cause the certificate to be passed and assigned to the tenant.

The goal of this is to ensure that the same certificate is used as the trust between the two system. Next we need to register the Service Principal Name and Register the Online Application ID and then finally set the SharePoint Realm.

Adding the Service Principal Name is done using the above PowerShell, which is the second security piece for a Hybrid Solution. First is the certificate, second is the Service Principal Name. If you do not know what a Service Principal Name is then you can read more here.

https://technet.microsoft.com/en-us/library/cc961723.aspx

https://azure.microsoft.com/en-us/documentation/articles/active-directory-application-objects/

Once this is added the SharePoint Online Application ID needs to be added. This is done by again reusing the core variables from the previous scripts and then populating some other values.

Adding the Service Principal Name is done using the above PowerShell, which is the second security piece for a Hybrid Solution. First is the certificate, second is the Service Principal Name. If you do not know what a Service Principal Name is then you can read more here.

https://technet.microsoft.com/en-us/library/cc961723.aspx

https://azure.microsoft.com/en-us/documentation/articles/active-directory-application-objects/

Once this is added the SharePoint Online Application ID needs to be added. This is done by again reusing the core variables from the previous scripts and then populating some other values.

So with all that we have most of the Hybrid pieces done and connected. Now comes the fun piece where we, finally connect the Office 365 pieces to our On-Premises SharePoint, setting it to allow the pass-through authentication and accept the tokens backwards and forwards. We also then run the scripts to create a service application and the final one of On-Boarding that validates everything to make sure everything is then good to use. 

The above code will now add a proxy that is visible within Service Applications for the On-Premises SharePoint Environment. “New-SPAzureAccessControlServiceApplicationProxy” combined with “New-SPTrustedSecurityTokenIssuer”, generate the connection needed to establish a trust between the server and the server principal.

Now we can run the PowerShell to create the cloud search service application if needed and finally complete everything with the On-boarding script. The two scripts supplied from Microsoft, I don’t call them directly, I created two smaller scripts.

Create the Cloud Search Service Application

Complete the On-boarding

That’s it we are done. You now have an On-Premises SharePoint Environment running in Hybrid mode to an Office 365 Tenant, of course you needed to have Synchronized accounts etc. previous to this, but these PowerShell scripts will get you ready to then consume what you need whether you are SharePoint 2013 or 2016.

PowerShell within Office 365 is really straight forward, for this post we looked at some of the more complex commands specifically for Hybrid configuration, but for regular things like connecting to sites, lists or libraries, users or even just regular items is just the same as On-Premises albeit the connection to Office 365 has to be made first.

The current list of all SharePoint Online cmdlets is available here: https://technet.microsoft.com/en-us/library/fp161364.aspx