Office 365

# Setting up MIRACL Trust SSO as an Identity Provider Within Office 365

These instructions are up-to-date at the time of writing, but you should refer back to the ViewDS guidance on making Office 365 work with an external SAML IdP to check for any changes. We cannot guarantee the accuracy of our SP-specific guidance.

For single sign-on, MIRACL Trust SSO is the identity provider and allows Office 365 to trust the MIRACL Trust SSO service for authentication to Office 365 apps. To use single sign-on to access all Office 365 applications, the Office 365 domain must be changed from managed to federated, and the Office 365 domain parameters settings changed to authenticate through the service.

Create an Office 365 for Business account. To do this:
- Go to the Office 365 Select a plan page.
- Choose Office 365 Business Premium (can be free trial).
- Follow the steps in the setup wizard.
Add your domain. To do this:
- Log into Office 365 and go to the ‘Admin’ page.
- Under ‘Setup’ tab, click on the Guided Setup button.
- Follow the steps in the setup wizard to add domain.
When complete, ensure that the newly added domain is not set as the default domain, because default domains cannot be used for federated sign on.
Add new users. To do this:
- Under ‘Users > Active Users’, select the ‘+’ sign to add a new user.
- Configure the new user with the newly added domain.
Note that, in Office365, federated users must have an ImmutableID set (this is an arbitrary value which could perhaps be a staff number, user ID or another unique number) . The MIRACL Trust SSO IdP server must pass an attribute which matches the ImmutableID which is stored for each user in Office365. Please see the note on user config at the end of this page for instructions on doing this.
Configure MIRACL Trust SSO as an Identity provider for the Office 365 Account. To do this:
- Run the Windows PowerShell app with elevated privileges (Run as Administrator).
- Install the Microsoft Online Services Sign-In Assistant PowerShell module by Install-Module -Name MSOnline
- Connect to your main Office 365 profile with Connect-MsolService. A popup window is displayed requesting your Office 365 credentials. Enter these and click on the OK button.
- Define the required variables as [name]=[value] pairs:
  - $domainName – your registered Office365 domain name (as set in the Offic365 Admin console), e.g. yourcompany.com
  - $issuerUri – https://idp.yourcompany.com/metadata - idp.yourcompany.com should be replaced by the public url which your IdP server is available on.
  - $logoffUri – https://www.office.com/ (the standard Office365 logoff Uri)
  - $passiveLogonUri – your MIRACL Trust SSO endpoint, i.e. https://idp.yourcompany.com/sso
  - $cert – your MIRACL Trust SSO X.509 certificate (without the comment lines, i.e. without the —–BEGIN CERTIFICATE—– and —–END CERTIFICATE—– lines). This can be output in the terminal in the correct format with a command such as echo $(cat idp.crt | tr -d '\n' | sed -E 's/-----[^-]+-----//g') You should have already generated this certificate and your private key with a command such as:
```
openssl req \
    -x509 \
    -nodes \
    -newkey rsa:2048 \
    -keyout idp.key \
    -out idp.crt \
    -days 1000 \
    -subj /C=UK/ST=London/L=London/O=Development/CN=example.com
```
- Run the following command:
```
Set-MsolDomainAuthentication -DomainName $domainName -FederationBrandName
$domainName -Authentication Federated -PassiveLogOnUri $passiveLogonUri -SigningCertificate
$cert -IssuerUri $issuerUri -LogOffUri $logoffUri -PreferredAuthenticationProtocol SAMLP
```
  A full list of MSOnline commands can be retrieved with Get-Command –Module MSOnline.
  
  If you need to change settings, first switch back to managed mode with Set-MsolDomainAuthentication -DomainName $domainName -Authentication Managed
(Optional) Verify your settings are correct. To do this, run the following command:
```
Get-MsolDomainFederationSettings -DomainName $domainName
```

# Configuring Your Office 365 Service Provider Profile With MIRACL Trust SSO

Edit /etc/miracl-sso/service_providers/office365.yaml:

profile:
  nameid:
    office365: <NameID NameQualifier="{{.MetadataEntityID}}" SPNameQualifier="{{.SPEntityID}}" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient">{{.SessionUserName}}</NameID>
  attribute:
    office365: >-
    <AttributeStatement>
      <Attribute Name="IDPEmail">
        <AttributeValue>{{.SessionUserEmail}}</AttributeValue>
      </Attribute>
    </AttributeStatement>
sp:
  office365:
    description: Office 365 subscription plans to access Microsoft Office applications plus other productivity services
    name: My Office365
    relay_state: /
    login_url: https://login.microsoftonline.com
    logout_url: https://login.microsoftonline.com/logout.srf
    metadata: >-
      <!-- insert downloaded SP metatadata here -->
    sign_response: true
    sign_assertion: true
    encrypt_assertion: false
    authorize:
    - - email: ^[^@]+@example.com$
    profile:
      nameid: office365
      attribute: office365

Office365 requires specific SAML attributes to be passed in the SAML response which requires using the profile section. In this configuration we assume that the user email (used as SessionUserEmail in this example) is setup as an ImmutableID in the Azure AD and pass its value in the required from O365 format. Read note on user config to understand how to retrieve other user data values from an ldap if another value is used as an ImmutableID.
Note that the name under which the SP is registered in the sp section is used to create your IdP-initiated login url, i.e. https://<yourssoip>/login/office365.
login_url and logout_url are the standard SP URLs which Office 365 makes available for SAML IdPs to use.
The standard Office 365 SP metadata can be obtained from https://nexus.microsoftonline-p.com/federationmetadata/saml20/federationmetadata.xml (Note that this url may be subject to change. It is currently what the Microsoft documentation points to at https://docs.microsoft.com/en-us/previous-versions/azure/azure-services/dn641269(v=azure.100)).

If you are using JSON format for your config file, the " characters need to be escaped with \ to meet the json structure requirements. This can be achieved by running the following command on the downloaded metadata.xml file:
```
echo -e "\n"$(cat metadata.xml | tr -d '\n' | sed -E 's/"/\\"/g')"\n"
```
The contents are output in the terminal in a format that can be pasted into the JSON metadata field.
In the authorize subsection, you can control what users are allowed to attempt login by following one or both of the below steps:
- Call up an LDAP setup from an ldap.yaml file stored in /etc/miracl-sso/integrations.
- Configure a regex list of email addresses/domains.
Note that if this is not set correctly, you receive ‘unauthorized user’ messages.

For more detailed info on using LDAP, API and/or regex to control authorized users, please see the authorization menu section but please read on for instructions specific to Office365.
Once finished, save and close the file.
In your /etc/miracl-sso/config.yaml file make sure you add office365.yaml to the list of ‘includes’:
```
includes:
  - core.yaml

# service providers
  - service_providers/office365.yaml
```
As always after config changes, restart the server.
Now your service is configured, you can visit https://<yourssoip>/login/office365 or https://<yourssoip>/services to log in to the service using IdP-initiated login, or visit the Office 365 login page and SP-initiated login are triggered automatically.
You are able to login using the in-browser PIN pad or with the MIRACL Trust app. When logging in to your SSO service for the first time you are asked to register an email address so as to confirm your identity and register you as a user.

# Note on User Configuration

In Office365 federated users must have an ImmutableID set (this is an arbitrary value of the user in the ldap active directory which could perhaps be a staff number, user ID or another unique data). The MIRACL Trust SSO IdP server must pass the attribute which matches the ImmutableID of the user to authenticate to Office365.

Assuming that the attribute field userPrincipalName (for the example below) is set to be the ImmutableID for the AD users, it should be extracted from the LDAP query when an authorize request is made. The following ldap configuration returns the userPrincipalName for every user found in the ldap AD for the specified search query so it could be passed as an ImmutableID in the profile.nameid configuration of Office365 later.

ldap:
  server:
    azure:
      method: tls
      serverName: yourdomain.com
      address: ldaps.yourdomain.com:636
      user: user@yourdomain.com
      password: P@ssw0rd1!
      certificate: |-
        -----BEGIN CERTIFICATE-----
        MIIDNTCCAh2gAwIBAgIQJKSil+H2jr1C8Vcjj0/IuDANBgkqhkiG9w0BAQsFADAZ
        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        hra/m3+yJOnT
        -----END CERTIFICATE-----
      certificateKey: |-
        -----BEGIN PRIVATE KEY-----
        MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCfT8ix0KE/TT53
        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        o6JwYpsCxtykTYnIUFcDyRCu
        -----END PRIVATE KEY-----
  query:
    azure_profile:
      server: azure
      search:
      - dn: dc=yourdomain,dc=com
        filter: "(mail={{.UserID}})"
        attributes:
        - userPrincipalName

When the ldap query is ready, it should be specified in the office365 authorize subsection of the sp section:

authorize:
- - ldap: azure_profile

Office365 requires some attributes in the SAML response. The NameID must be the user’s ImmutableID as the IDPEmail could be the value held by the .SessionUserEmail property:

profile:
  nameid:
    office365: <NameID NameQualifier="{{.MetadataEntityID}}" SPNameQualifier="{{.SPEntityID}}" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient">{{AttrVal "userPrincipalName" 0 "" .Attributes}}</NameID>
  attribute:
    office365: >-
      <AttributeStatement>
        <Attribute Name="IDPEmail">
          <AttributeValue>{{.SessionUserEmail}}</AttributeValue>
        </Attribute>
      </AttributeStatement>

The office365 attribute and nameid profiles need to be invoked in the following sp subsection:

profile:
  nameid: office365
  attribute: office365