As part of an ongoing series, we’re helping to explain ways to configure SimpleSAMLphp as a centralized identity provider (IDP) for your organization.
Update: Looking for a secure and feature-rich enterprise SSO solution? Take a look at TozID for a complete solution that’s easy to integrate into any organization.
Last week, we modified our existing SimpleSAMLphp server to authenticate against a real source of user data using Tozny’s secure, password-free authentication platform. This week we’ll modify that same server to act as a hosted identity provider for Microsoft’s Office 365. Instead of logging in directly through Microsoft, users will be directed to our server and will authenticate there instead.
Interesting in learning more about Tonzy’s encryption solutions? Check out TozStore or TozID, Tozny’s secure identity management solution with end-to-end encryption built in. Our SDKs and toolkits are designed to simplify and expedite the deployment of solutions that address your encryption needs. |
Key Components
In order to follow along with this tutorial, you’ll need access to the following components:
SimpleSAMLphp Server – You can (and should) use the same server we setup two weeks ago. Continuing to use the Tozny-powered IDP from last week is not a requirement. The steps that follow will be roughly the same even if your server is configured to use a different authentication provider. The only real requirement is that your SimpleSAMLphp server integrate with a secure source for client credentials.
Office 365 – a hosted suite of office productivity apps produced and maintained by Microsoft. As we’ll be configuring Office 365 itself in this tutorial, you will need to have an account and have your administrator credentials.
Azure Active Directory – the cloud identity manager used by Office 365 and other Microsoft products. It can integrate with an on-premises Active Directory solution, providing single sign-on capabilities between Microsoft’s cloud and your on-premises applications. For our uses, though, we’ll set up a federated domain within Azure AD that defers authentication to SimpleSAMLphp.
The Azure AD PowerShell module – All of the configuration for Azure AD requires an administrator account with Office 365 and takes place using Windows PowerShell with the addition of the Azure AD PowerShell module.
Configuring SimpleSAMLphp
As with our previous walkthroughs, we will assume the users’ authentication domain is somesite.com and the SimpleSAMLphp server is running on a dedicated subdomain like sso.somesite.com.
Authentication Sources
After the completion of our first two tutorials, you were left with a configured authentication source called “somesite” that’s using the “toznyauth:External” module to authenticate against Tozny. We’ll be using the same configuration without any changes. For reference, the configuration block in authsources.php should still look like:
'somesite' => array(
'toznyauth:External',
'realm_key_id' => 'sid_...',
'realm_secret_key' => '49f127...fd9',
'api_url' => 'https://api.tozny.com',
'attributes' => array(
'IDPEmail' => 'urn:oasis:names:tc:SAML:2.0:attrname-format:emailAddress',
),
),
Identity Provider
As with our previous tutorial, nothing needs to change about the hosted IDP metadata configured with the server. We are using the same server with the same certificate, keys, and authentication source. For reference, /metadata/saml-20-idp-hosted.php should still contain:
$metadata['https://sso.somesite.com'] = array( // The hostname of the server this SAML entity will use. 'host' => 'sso.somesite.com', // X.509 key and certificate. Relative to the /cert directory. 'privatekey' => 'somesite.key', 'certificate' => 'somesite.crt', 'auth' => 'somesite', );
Remote Service Provider
For the purposes of this walkthrough, the only service provider we need to configure is Azure Active Directory. Microsoft publishes its federation metadata publicly in XML format to https://nexus.microsoftonline-p.com/federationmetadata/saml20/federationmetadata.xml. You can use SimpleSAMLphp to convert this XML into the proper format using the built-in metadata parser.
On your new server, this should live at https://sso.somesite.com/admin/metadata-converter.php.
Copy the converted metadata to /metadata/saml20-sp-remote.php on your server. You will also need to add the following two top-level keys to the array:
'simplesaml.nameidattribute' => 'uid', 'simplesaml.attributes' => TRUE,
This will force the NameIDAttribute sent from SimpleSAMLphp to Microsoft to match the uid provided by Tozny. It will also force any other custom attributes assigned to the user (i.e. the IDPEmail field) to be sent in the request automatically. As we mentioned last week, this attribute has the added benefit of allowing you to decouple your user’s email for configuring the identity store (i.e. where they receive setup information) from the email address used during authentication with SimpleSAMLphp.
Configuring Azure Active Directory
The first step is to install the Azure AD PowerShell module so you can manage your federated domain within Azure Active Directory.
Note: You cannot use the .Net Core version of PowerShell with this utility – you must run these commands from either a native Windows machine or a Windows VM.
Once installed, use the new PowerShell module to authenticate to Microsoft using your administrator credentials
PS C:\> Connect-MsolService
This command will open a browser window and prompt for your email address and password. Once entered, all subsequent commands will execute against your existing Azure AD account. If you lack administrative access or intend to manage a separate domain, run the command again and re-authenticate.
Adding a Domain
Creating a federated domain is a three-step process – part of which will take place in PowerShell, part of which will take place with your domain registrar. The first component requires adding the domain to Azure AD and requesting a DNS TXT record for verification:
PS C:\> New-MsolDomain -Name somesite.com -Authentication Federated PS C:\> Get-MsolDomainVerificationDns -DomainName somesite.com -Mode DnsTxtRecord
Note: Use the domain name that your users will be authenticating against – this is the domain in which their email addresses live, not the domain for your SimpleSAMLphp server.
Now set the appropriate TXT entry for your domain with your registrar. Depending on DNS propagation times, this could take anywhere from an hour to 48 hours to take effect.
Configuring Domain Federation
Conveniently, you can both confirm your domain and configure federation through the Azure AD PowerShell cmdlets. To manage both, first set some variables to identify your domain and the certificate that will be used to authenticate requests:
PS C:\> $domain = "somesite.com" PS C:\> $name = "Somesite, Inc." PS C:\> $url = "https://sso.somesite.com/saml2/idp/SSOService.php" PS C:\> $uri = "https://sso.somesite.com" PS C:\> $logouturl = "https://sso.somesite.com/module.php/core/authenticate.php?as=somesite&logout” PS C:\> $cert = "MIID7z...onBf4" # Server certificate, pem file. Remove spaces and newlines
The domain above should be the authentication domain you’re configuring, while the separate URLs and URIs references should point to SimpleSAMLphp for authentication. Likewise, the certificate used should be the one configured for your server – you can find this in the metadata exposed by your server at https://sso.somesite.com/saml2/idp/metadata.php?output=xhtml.
Note: Remember to paste the certificate without spaces or newlines.
Next, execute the domain confirmation cmdlet:
PS C:\> Confirm-MsolDomain -DomainName $domain -IssuerUri $uri -FederationBrandName $name -LogOffUri $logouturl -PassiveLogOnUri $url -SigningCertificate $cert -PreferredAuthenticationProtocol SAMLP
Once confirmed, you will also need to explicitly set the domain’s federation settings. Many of the same parameters will apply, so the variables already stored in PowerShell can be reused:
PS C:\> Set-MsolDomainAuthentication -DomainName $domain -FederationBrandName $name -Authentication Federated -PassiveLogOnUri $url -SigningCertificate $cert -IssuerUri $uri -LogOffUri $logouturl -PreferredAuthenticationProtocol SAMLP
Note: If any of this information ever needs to be changed, use the Set-MsolDomainAuthentication cmdlet to change authentication back to “Managed” for the domain, then run the full federation command again with the new values. Failing to reset to managed authentication will apparently block any updates.
Provisioning Users with Azure AD
Creating users is, unfortunately, a two-step process. The users must exist in Tozny’s system to power authentication, but they must also exist in Azure AD to control licensing for Office products. If you haven’t already created a user with Tozny, visit the admin portal and do so, setting the IDPEmail field to be equal to the email address the user will use when authenticating to Office 365 (i.e. alice.smith@somesite.com).
Make a note of the user’s ID (sid_xxxxxxxxx) as this will be used when creating the user’s account in Azure AD as well.
The user’s ID is the second sid_xxx field in the URL when viewing that user’s information.
If you’re using an authentication source besides Tozny, create your user there and set the IDPEmail appropriately. You will still need to track the unique user ID returned by your authentication provider – it should be configured to map to the uid field returned by SimpleSAMLphp.
Next, find the license SKU for your account according to Azure using PowerShell:
PS C:\> Get-MsolAccountSku
This value will look something like somesite:O365_BUSINESS and is used by Microsoft to track the license usage of your various users.
Creating a user is now a matter of telling Azure AD what user ID SimpleSAMLphp will provide after authenticating a given email address and assigning the appropriate license to that user. Assuming the Tozny-provided user ID for user1@somesite.com is sid_1234567890, the command would then be:
PS C:\> New-MsolUser -UserPrincipalName user1@somesite.com -DisplayName "User One" -FirstName "User" -LastName "One" -ImmutableId “sid_1234567890” -UsageLocation "US" -LicenseAgreement "somesite:O365_BUSINESS"
This command both creates the user and provisions the user with a license for Office 365.
Testing the Workflow
Once users are created for both the authentication source and Azure AD, you can test the user account by visiting the Office 365 portal.
Entering an email address with a domain configured for federated authentication will automatically redirect the user through SimpleSAMLphp without the need of a password.
Enter the email address. Microsoft will automatically detect the use of a federated domain and redirect you to SimpleSAMLphp to proceed with authentication.
When successful, SimpleSAMLphp will create a signed document providing the user’s ID and the IDPEmail field and pass both back to Azure AD. Microsoft will then match against known users and, if licensed, log the user into Office 365.
When unsuccessful, you’ll get an error message from Microsoft that can be used on the MSDN to identify and debug the issue.
Related Reading
There are multiple moving parts involved with configuring Office 365 to authenticate against an external identity provider, but once they’re all in place you have a powerful system at your disposal. The fully-configured server can also be used to authenticate with any other service provider that consumes SAML assertions, like as Atlassian, GitHub Enterprise, SAP, and Workplace by Facebook.
It can also be extended to authenticate against identity systems other than Tozny – you can use the steps above to integrate your Office 365 accounts with another SAML provider entirely. Other environments might necessitate turning things around to use Office 365 itself as the identity provider used to authenticate with various other sources.
Google’s G-Suite is an alternative remote service provider for email and cloud documents; come back next week to learn how to leverage SimpleSAMLphp for Google authentication.