Azure AD Enterprise Application integration (SSO/Office365)
If the users and/or resources are both available within Azure AD it’s highly recommended to include GoBright as an Enterprise Application. There are a few reasons to do this:
Why you should consider adding GoBright in Azure AD
- The application can be used to set up the Office 365 integration
- The application can be used to synchronize users from Azure AD when Automatic User Creation is setup
- Managing users who can log in to the GoBright platform with Microsoft Single Sign-On
- No additional configuration or scripting is required
Using this enterprise application will easily set up a connection, including SSO, while still giving you control over who is allowed to use the application.
Connecting to Office 365 with PowerShell is the easiest way to execute several configuration commands.
For connecting to Office 365 with MFA support, Microsoft provides the EXO V3 module, published through the PowerShell gallery, which can be installed with the following steps:
- Start PowerShell as Administrator
- Install the PowerShell gallery PowerShell module:
- Execute the following commands in PowerShell (running as administrator)
- Install the NuGet PackageProvider:
Install-PackageProvider -Name NuGet -MinimumVersion 126.96.36.199 -Force
- Configure PowerShellGallery as a trusted source:
Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
- Install the PowerShellGet module:
Import-Module -Name PowerShellGet
- Install the EXO V3 (ExchangeOnlineManagement) module:
Install-Module -Name ExchangeOnlineManagement -Force
The ‘-Force‘ command makes sure that the latest version of the module is installed even when a previous installation exists. When the module was already installed, the PowerShell session will need to be restarted.
Now we can use the installed EXO V3 module to connect to Office 365:
- Start PowerShell as Administrator (make sure this is a new PowerShell session)
- Start connecting by logging in, use an account with the required permissions to manage your Office 365 environment:
Connect-ExchangeOnline -UserPrincipalName firstname.lastname@example.org -ShowProgress $true
- When logged in, we are ready to proceed with the further configuration!
Service account creation:
GoBright needs a service account to link the GoBright Environment to the right Azure AD tentant.
Execute the following commands via the PowerShell session.
Now execute the following command to create the service account, please change the MicrosoftOnlineServicesID to your own name/domain and YourPasswordHere for the password you want to use for the service account:
New-Mailbox -MicrosoftOnlineServicesID email@example.com -Alias 'GoBright' -Name GoBright -Password (ConvertTo-SecureString -String YourPasswordHere -AsPlainText -Force) -FirstName 'GoBright' -DisplayName 'GoBright' -ResetPasswordOnNextLogon $false
Note: now assign a regular license to the service account in the Office 365 portal, otherwise the service account will not work correctly. An ‘Exchange Online (Plan 1)’ license or higher is needed for the service account.
Now check if the service account is created correctly by executing the following command. The result of the command should show the mailbox of the newly created service account, if no mailbox shows up, you probably should link a license to the mailbox in the Office Admin Center. Execute the following command, replace the Identity parameter to the email address of the service account:
Get-Mailbox -Identity firstname.lastname@example.org
The service account will need to authenticate with the GoBright platform. This is done through modern authentication within the integration. Depending on which is configured we’ll discuss how it must be configured within Office 365.
Now set the service account to have a never-expiring password:
Install-Module MSOnline -Force
Set-MsolUser -UserPrincipalName email@example.com -PasswordNeverExpires $true
Set the service account to have a password and enable modern authentication.
Check the authentication status:
Get-OrganizationConfig | ft OAuth*
Change the setting:
Set-OrganizationConfig -OAuth2ClientProfileEnabled $True
Verify the change:
Get-OrganizationConfig | ft OAuth*
Now add and configure GoBright as an Enterprise application to the AzureAD of your organization. In this way, you can easily connect and manage access to GoBright.
Add GoBright as an Enterprise application:
- Login to your AzureAD via portal.azure.com
- Open ‘Enterprise applications’:
- Choose ‘New application’:
- Search for ‘GoBright’, click the ‘GoBright’ card, and click ‘Sign up for GoBright’:
- You will now be redirected, please login with the ‘Sign in with Microsoft’ button and use your Azure Admin account to sign in:
- You will be presented with the Microsoft federated login page.
Login once, and accept, this will add the ‘GoBright’ app to the AzureAD of your organization, still with no permissions.
Please note: the GoBright portal will not recognize you as a user, so the login in will fail, this is correct at this stage.
You can check if the admin consent is granted. At the left click on permissions:
If it’s not granted, then you need to give admin consent. After clicking on ‘Grant admin consent for..’ you need to login with your Microsoft Azure AD admin account to give permission.
Last step is to assign groups/users to the GoBright Enterprise application:
- Click on Users and Groups at the left part of the Enterprise Application
- Use the ‘Add user’ button to add groups or users to access GoBright
Integrations are configured in the Admin center. Login to GoBright with your admin account and click on the switch button on the top right corner.
Within the Admin center you can click on the ‘Integrations’ at the top.
Here you can ‘Add’ a new integration. Enter a name and set the ‘External system’ to Office 365. For the link you need to use the GoBright service account you’ve setup earlier on.
For a name you can set any name. Set the ‘Authentication type’ to ‘Modern authentication’. Click on ‘Link Office365’. You will be redirected to Microsoft to login with your service account.
This is part of the new login experience. Please click on this article to read more about it.
If you already have users in your portal which are also present in Azure AD, you need to modify the integration that is selected for those users.
Also you can create one user for testing the Azure AD login flow.
Users are managed in the Admin center. Login to GoBright with your admin account and click on the switch button on the top right corner.
Within the Admin center you can click on the ‘Users’ at the top.
Click on ‘Users’ at the left. Here you can ‘Add’ new users, import Users and modify existing users.
Please make sure that for such user:
- The email address of the user in the portal needs to be the same as in Azure AD
- Make sure the user has the correct integration selected
Once the user is properly configured, you can test login, e.g. by starting an incognito browser session and login to the portal with the properly configured user.
To enable automatic user creations, there are two steps involved:
- Configure the Office 365 integration with modern authentication and automatic user creation enabled, and choose the default role for automatically created users.
- The platform needs to know which company domains are related to your environment, for example, ‘@company.com’.
Please provide these domains to GoBright via the request form.
Supply the following in your request: your organization, the domains you want to use for automatic user creation.
Please request this via this form.
When provided GoBright will configure this, and provide you with feedback.
It is also possible to synchronize users upfront, which might be desirable to do active user management. Please see this article for more information about synchronizing users.