Prerequisites:
Before you get started you should ensure that you have the following prerequisites:
- An administrator account for Office 365
- AppsCo Business
- A domain name that you own
- Windows PowerShell with the Azure AD PowerShell module installed
1. Add Office 365 SSO application on AppsCo
First, you will need to add the Office 365 SSO application to your company resources on AppsCo. If you have already done this, skip to step 2.
Go to Resources, click Add and choose SSO Application from the drop down.
Search for Office365 and click on the card when it shows up to select an application.
Click Add to add the application to company resources. You are now only adding the application but it will need to be setup in order to work.
When Office 365 SAML card is added, click Edit to go to resource settings where you will find information needed to set single sign-on for this application with AppsCo as IdP.
You will find the settings you need for setup on Manage resource page http://appsco.com/manage-resource/<application-id>
2. Connect to Windows Azure AD using Windows PowerShell
Open Windows PowerShell 4.0 (if you have Windows 10, you will automatically have PoweShell 5.0) and
make sure the module Windows Azure Active Directory has been installed (see the prerequisites listed above). Run the following command to connect to Windows Azure AD using your Office 365 administrator account.
PS C:\> Connect-MsolService
After that, you will be prompted for email and password in order to login. Remember, that you need to have
an administrator account for setup.
3. Setting up domain for federation
Setting up your domain is a one time task. It consists of three steps:
- Adding a domain
- Verifying the domain
- Setting up federation
Unless you plan to use a different domain in Azure AD, you will not need to perform this again in most situations. For the purposes of this guide, we will assume you own the domain “companydomain.com”.
3.1 Adding domain
To add the domain, run the following command in PowerShell:
PS C:\> New-MsolDomain -Name companydomain.com -Authentication Federated
3.2 Verifying the domain
In order to confirm the ownership, Microsoft requires the domain owner to add a custom TXT DNS record for the domain to the domain server. This command is used to retrieve details of the DNS record that must be set.
PS C:\> Get-MsolDomainVerificationDns -DomainName companydomain.com -Mode DnsTxtRecord
When you run the command above, you will get a response similar to the one below:
Label : companydomain.com
Text : MS=ms79844278
TTL : 3600
Now, you should add Text value (in this case, MS=ms79844278) as a DNS TXT record in your domain admin server.
Once the DNS record has been added to the domain server, you need to execute the Confirm-MsolDomain command, along with its mandatory parameters, in order to confirm ownership of the domain, as well as set up the federated domain.
Your managed domain:
PS C:\> $domainname = "companydomain.com"
Sign out URL, that can be found on http://appsco.com/manage-resource/<application-id> on Appsco IdP Information card:
PS C:\> $logoffuri = "https://appsco.com/logout"
Sign in URL, that can be found on http://appsco.com/manage-resource/<application-id> on Appsco IdP Information card:
PS C:\> $passivelogonuri = “http://appsco.loc/idp/saml/company/<company-id>”
Certificate, that can be downloaded on http://appsco.com/manage-resource/<application-id> on Appsco IdP Information card.
NOTE: You should remove following from certificate content:
- new-line characters
- -----BEGIN CERTIFICATE----
- -----END CERTIFICATE-----
PS C:\> $cert = “CERTIFICATE CONTENT”
Issuer URI should be https://appsco.com:
PS C:\> $issueruri = “https://appsco.com”
Protocol should be also set, to ensure that domain uses SAML SSO:
PS C:\> $protocol = "SAMLP" # To ensure domain uses SAML SSO
Next step is to run the following command:
PS C:\> Confirm-MsolDomain -DomainName $domainname -IssuerUri $issueruri -FederationBrandName $domainname -LogOffUri $logoffuri -PassiveLogOnUri $passivelogonuri -SigningCertificate $cert -PreferredAuthenticationProtocol $protocol
Your domain should now be successfully set for federation.
3.3 Setting up federation
When domain is set up and verified, the next step is to set SSO for verified domain. You might notice in following commands, that the parameters are the similar to ones in previous step.
Your managed domain:
PS C:\> $domainname = "companydomain.com"
Sign out URL, that can be found on http://appsco.com/manage-resource/<application-id> on Appsco IdP Information card:
PS C:\> $logoffuri = "https://appsco.com/logout/"
Sign in URL, that can be found on http://appsco.com/manage-resource/<application-id> on Appsco IdP Information card:
PS C:\> $passivelogonuri = “http://appsco.loc/idp/saml/company/<company-id>”
Certificate, that can be downloaded on http://appsco.com/manage-resource/<application-id> on Appsco IdP Information card.
NOTE: You should remove following from certificate content:
- new-line characters
- -----BEGIN CERTIFICATE----
- -----END CERTIFICATE-----
PS C:\> $cert = “CERTIFICATE CONTENT”
Issuer URI should be https://appsco.com:
PS C:\> $issueruri = “https://appsco.com”
Protocol should be also set, to ensure that domain uses SAML SSO:
PS C:\> $protocol = "SAMLP" # To ensure domain uses SAML SSO
Next step is to run the following command:
PS C:\> Set-MsolDomainAuthentication -DomainName $domainname -FederationBrandName $domainname -Authentication Federated -IssuerUri $issueruri -LogOffUri $logoffuri -PassiveLogOnUri $passivelogonuri -SigningCertificate $cert -PreferredAuthenticationProtocol $protocol
Setup for SSO on your domain should now be successfully completed.
4. Users
4.1 Creating user
If order to successfully setup SAML SSO, we would need to create user in Office365 that will correspond to an user in AppsCo.
- It is important that user’s principal name is on the same domain as the one that we have set up before (and to match email of corresponding AppsCo account).
- It is also important that the users have ImmutableId attribute set. ImmutableId represents unique value that identifies user. In order to setup Office365 SAML SSO with AppsCo as IdP, we would need to set AppsCo’s account id as ImmutableId in related Office365 account.
ImmutableId can be obtained on AppsCo My Account page in the left sided resource section:
To create user, following command should be used:
PS C:\> New-MsolUser -UserPrincipalName john.doe@companydomain.com -ImmutableId 2e28f6ce-4e3b-4538-b284-1461f9379b48 -DisplayName "John Doe" -FirstName John -LastName Doe -AlternateEmailAddresses "john.doe@company.com"
4.2 Set ImmutableId to existing user
For existing users, you will need to set ImmutableId in order to make possible for them to log in via SAML SSO.
As we said before, ImmutableId (that we need to set for corresponding account in Office365) can be obtained on AppsCo account page in the left sided resource section.
To set/update ImmutableId for an existing user, first, you have to change its UserPrincipalName to a dev.companydomain.onmicrosoft.com domain, then to set their ImmutableId, and, after that, switch back UserPrincipalName to a companydomain.com.
Defining new ImmutableId value:
PS C:\> $id=”2e2e2ead-4e3b-4538-b284-123llkl1ll19”
UserPrincipalName for user we wish to set ImmutableId for
PS C:\> $upn=”john.doe@companydomain.com”
UserPrincipalName on microsoft
PS C:\> $upnNew=”john.doe@companydomain.onmicrosoft.com”
Setting UserPrincipalName to onmicrosoft.com domain (so we can perform update)
PS C:\> Set-MsolUserPrincipalName -UserPrincipalName $upn -NewUserPrincipalName $upnNew
Updating ImmutableId
PS C:\> Set-MSOLUser –UserPrincipalName $upn1 –ImmutableID $id
Returning user to their original UserPrincipalName
PS C:\> Set-MsolUserPrincipalName -UserPrincipalName $upnNew -NewUserPrincipalName $upn
5. Add information from the service provider to AppsCo
As a final step, you need to enter information from the service provider - in this case Office 365 to application settings on AppsCo.
5.1 Add domain and ACS URL
On Office 365 SSO application you are setting up, go to manage resource page and then to Settings.
Write in your domain under ''Domain registered at SP'' - this is the domain your company has registered on Office 365.
Under ''ACS URL'' write in the URL provided by Office 365 - in this case: https://login.microsoftonline.com/login.srf
Click Save, to save your settings.
Your Office 365 SSO Application is now set up and you can share it with your employees.
If you have any questions, please send us an email to support@appsco.com
0 Comments