Introduction
In this article we explain how to set up SSO manually for your Workspace environment. We do however recommend using the automatic setup for SSO.
Step 1. Create an App Registration in Microsoft Entra ID
If there already is an App Registration for your Workspace environment present in Microsoft Entra ID (previously called Azure AD), you may skip this step and continue with step 2 "Create a new Client Secret".
If no App Registration is present in Microsoft Entra ID, you must first create one:
Go to Azure.
Log in with the Global Administrator account.
Search for and select Microsoft Entra ID.
Select App registrations.
Click New Registration.
Choose a Name (e.g. "Workspace 365 SSO").
As for Supported account types choose: "Accounts in this organizational directory only (workspace365inc only - Single tenant)".
Under Redirect URI, choose Web.
The URL should have the following format: "https://instance.workspace365.net/environment/OAuth2/HandleAuthorityResponse".
Click Register.
From the overview pane of this App Registration, note down the Client ID. You will need this value later on.
Go back to the Microsoft Entra ID overview pane. Under 'Basic information', note down the Primary domain. You will need this value later on.
Step 2. Create a new Client Secret
When the App Registration for your Workspace environment has been created, we need to create a new Client Secret.
In Azure, go to App registrations.
Select the Workspace application from the list.
Select Certificates & secrets.
Click New client secret.
Fill in a Description.
Set the expiration date.
You won't be able to sign into Workspace anymore if the client secret expires. However, you can use PowerShell to add an app secret valid for 99 years. Copy the script below to PowerShell ISE and change the following values:
Note: every client secret's password that is created ends with '='. Don't forget to copy this.
$APPObjectID: enter the Object ID of the SSO app registration here
$AppSecret: enter a name for the secret key. This will be displayed as the client secret's Description in Azure#Parameters
$APPObjectID = "xxxxxxxx"
$AppSecret ="Client Secret for Workspace"
#Connect to Microsoft Entra ID (Azure AD)
Connect-AzureAD
#Add App Secret - Valid for 99 Years
$StartDate = Get-Date
$EndDate = $StartDate.AddYears(99)
$AAdAppsecret = New-AzureADApplicationPasswordCredential -ObjectId $APPObjectID -StartDate $StartDate -EndDate $EndDate -CustomKeyIdentifier $AppSecret
#Get the Secret Set
Write-host $AAdAppsecret.Value
#See the Secret set
Read-Host $AAdAppsecret.ValueClick Add.
Copy the Value. You will need this later on.
Note: This value will be hidden once you leave this page.
Step 3. Check API permissions
In order to use applications in Workspace 365 such as Exchange, SharePoint (Microsoft Graph) and Power BI (Power BI Service), the appropriate API permissions must be assigned to the Workspace SSO App Registration.
For more information, visit our FAQ: How does Workspace 365 connect with Azure?
In Azure, go to App registrations.
Select the Workspace application from the list.
Go to API permissions.
Click Add a permission, then add the necessary Microsoft Graph (SharePoint and Exchange) and Power BI Service (Power BI) API permissions according to the image below
Important: make sure you select the permission type Delegated, otherwise Workspace cannot use them.
You may delete other API permissions from your Workspace App Registration that are not presented in the image below.
Don't forget to Grant admin consent once you're done.
Note: A green checkmark indicates that admin consent has been granted. This is very important. Without admin consent, Workspace does not have permissions to retrieve the data from Azure.
Step 4. Enable SSO manually in Workspace
To set up SSO manually for your Workspace environment, go to:
Workspace admin settings. Be sure to use the Primary Administrator account for the SSO setup.
Select Single sign-on.
Set the Single sign-on type to OAuth2.
Choose Manual setup.
Fill in the necessary information:
The Authority consists of "https://login.windows.net/" appended with the Primary domain of your tenant (e.g. "workspace365.onmicrosoft.com"). This is the value you copied in step 1.12.
For example: "https://login.windows.net/workspace365.onmicrosoft.com".The Client ID can be retrieved from the SSO App registration (Overview pane) in Microsoft Entra ID. This is the value you copied from step 1.11.
The Key can be retrieved under Client secrets. Paste the value you copied in step 2.10.
Click Verify.
You should see a green screen "verification succeeded". If so, check the checkbox "I have seen the GREEN screen telling the verification was successful".
Click Done.
"Failed to retrieve the OAuth2 authorize endpoint"
When setting up SSO manually in the workspace, you may get the following error:
"Failed to retrieve the OAuth2 authorize endpoint. Please double check the entered information."
This can be caused by either of the following:
The URL you entered in the Authority* field ends with a "/", remove this and try again
A space is included in the client secret value you entered in the Key* field
Incorrect information has been entered in one or more fields, verify you have entered the correct information in each field
If you have verified each of the points listed above but you are still getting this error after multiple attempts, you can try the following:
Close and re-open the SSO configuration page and try again
Create a new SSO app registration in Azure and try again with that one.