> For AI agents: [llms.txt](https://docs.trustedauth.com/llms.txt) provides a Markdown index of this documentation.

# Office 365

You must configure Microsoft Office 365 for Entrust Identity as a Service (Entrust IDaaS) before configuring mobile Microsoft Office 365 applications for single sign-on.

note

- User attributes received through Active Directory (AD) synchronization are retrieved as strings. Byte array attributes are base64 encoded before being used in the SAML response.
- When integrated with Entrust IDaaS, Microsoft Office 365 accounts are configured for single logout (SLO). Signing out of Office 365 signs the user out of Entrust IDaaS, but not from other SAML applications.
- This procedure was tested with previous versions of Entrust IDaaS and Microsoft Office 365. For newer versions, use this as a starting point and contact <support@entrust.com> if issues occur.

To integrate Microsoft Office 365 with Entrust IDaaS, complete the following steps.

## Step 1: Complete prerequisites

### Create custom user attributes in Entrust IDaaS

1. Log in to your Entrust IDaaS account.
2. Click Menu icon **>** **Members > Attributes** to open the **User Attributes List** page.
3. Under **Custom User Attributes**, click **Plus icon**.
4. Enter a **User Attribute Name** (for example, `O365 ImmutableID`).
5. (Optional) Select **Required** to make the attribute mandatory.
6. Click **Add** to create the attribute.

### Map the Immutable ID attribute (optional)

If you use AD sync, map the Immutable ID attribute to **ObjectGUID** (Active Directory) or **onPremisesImmutableId** (Entra ID Directory) so the value auto-populates. See [Map ImmutableID attribute to a directory attribute](/docs/directories-and-provisioning/manage-directories/map-immutableid-attribute-to-the-directory-attribute.md) for instructions.

### Confirm Office 365 plan support

Confirm that your Office 365 account supports single sign-on (SSO) and federation. Review [Microsoft's Plan Comparisons](https://products.office.com/en-us/business/compare-more-office-365-for-business-plans).

## Step 2: Prepare Microsoft Office 365 for configuration

1. Install PowerShell. You must use PowerShell to set up and federate the Office 365 domain with Entrust IDaaS. See <https://learn.microsoft.com/en-us/powershell/entra-powershell/installation>.

2. Install the Microsoft Graph module and confirm installation:

   ```powershell
   Install-Module Microsoft.Graph
   Get-InstalledModule
   ```

3. Connect to Microsoft Graph and authenticate as an administrator:

   ```powershell
   Connect-MgGraph -Scopes "User.ReadWrite.All", "Domain.ReadWrite.All", "Directory.ReadWrite.All", "Directory.AccessAsUser.All", "LicenseAssignment.ReadWrite.All" -UseDeviceAuthentication
   ```

note
Use a web browser to complete device authentication with the supplied URL and code.

4. Sign in to your Office 365 admin account and open the **Admin Center**.

5. Go to **Setup > Get your custom domain setup > Manage**.

6. If you do not have a domain, add one to federate through Office 365. See [Add a domain to Microsoft 365](https://docs.microsoft.com/en-us/microsoft-365/admin/setup/add-domain?view=o365-worldwide).

7. If the domain you want to federate is set to default, federate another domain instead. Note the domain name for use later.

## Step 3: Add Microsoft Office 365 to Entrust IDaaS

1. Log in to your Entrust IDaaS administrator account.

2. Click Menu icon **>** **Security > Applications** to open the **Applications List** page.

3. Click **Add** and, under **SAML Cloud Integrations**, select **Microsoft Office 365**.

4. Enter an **Application Name** and **Application Description**.

5. (Optional) Click Plus icon next to **Application Logo** and upload a logo.

6. Select the **Authentication Flow** users see during sign-in and click **Next** to open the **General** page.

7. If you have a metadata file, click Upload icon to **Upload Metadata XML**, then (optional) click **Merge with existing values**. Click **Save**.

8. If you do not have metadata, enter the following values manually:

   - **Default Assertion Consumer Service URL**: `https://login.microsoftonline.com/login.srf`
   - **Service Provider Entity ID (Issuer)**: `urn:federation:MicrosoftOnline`
   - **Single Logout Service URL**: `https://login.microsoftonline.com/login.srf`

9. From **SAML Name ID Attribute**, select the attribute that represents the Immutable ID (for example, `O365 ImmutableID`).

10. (Optional) Enter **SAML Username Parameter Name** (for example, `Username`).

11. Enter **SAML Session Timeout** (maximum 720 minutes).

12. Enter **Max Authentication Age (seconds)** or `-1` to disable.

13. (Optional) Select **Sign complete SAML response**.

14. (Optional) Deselect **Enable Go Back Button** if you do not want users to return to the Microsoft Office login page.

15. Select **Show Default Assertion Consumer URL Service in the My Profile** if you want the URL displayed in user profiles.

16. (Optional) Add **SAML Domains**: click **Add**, enter the **SAML Domain**, and click **OK**. Repeat for additional domains.

17. (Optional) Select **ActiveSync** to allow access to other Microsoft Office 365 applications. Copy the **Active Logon URI** for later use.

18. (Optional) Add **Alternative Assertion Consumer Service URLs**: click **Add**, enter a **Name** and **Value**, and select **Show in My Profile** if desired.

19. (Optional) Add a **Relay State**: click **Add**, enter a **Name** and **Value**, and select **Show in My Profile** if desired. You can enable or disable relay states on the Add/Edit application page.

20. (Optional) Add a **Relay State Logo**: click Plus icon next to **Relay State Logo**, upload an image, resize if needed, and click **OK**.

21. From **Microsoft Office 365 SAML2 Attribute Value**, select **User Principal Name**. You will enter the User Principal Name in _Step 6_.

22. Click **Submit**.

note

- If you have multiple Office 365 domains to federate, add a SAML domain entry for each one. If only one domain exists, a domain entry is not required.
- If you regenerate the **Account Logon URI**, reconfigure the Office 365 account in PowerShell with the new partner secret. Update each federated domain accordingly.

## Step 4: Add a resource rule

Create the required resource rule. See [Create resource rules](/docs/authentication-and-security/create-and-manage-resource-rules.md).

## Step 5: Download the metadata file from Entrust IDaaS

1. In Entrust IDaaS, click Menu icon **>** **Security > Applications** to open the **Applications List** page.
2. Do one of the following:
   - Click Cloud Download icon next to the application.
   - Click Ellipsis Vertical icon next to the application and select **SAML IDP Metadata**.
3. In the **SAML Application Metadata** dialog box, choose **Select the certificate to include in the SAML IDP Metadata file**.
4. If applicable, choose **Select the domain to include in the SAML IDP Metadata file**.
5. Enter the **Lifetime, in days, for the SAML IDP Metadata file** (between 2 and 730).
6. Copy the **Public Endpoint** if needed for your SAML application, or click **Download**.

note

If you are using multiple domains, download a metadata file for each domain because values differ per domain.

## Step 6: Prepare users for Microsoft Office 365 access

Ensure users exist in both Microsoft Office 365 and Entrust IDaaS so SSO attempts succeed.

### Add users individually

See [Add users and assign licenses at the same time](https://docs.microsoft.com/en-us/microsoft-365/admin/add-users/add-users?redirectSourcePath=/en-us/article/Add-users-individually-or-in-bulk-to-Office-365-Admin-Help-1970f7d6-03b5-442f-b385-5880b9c256ec&view=o365-worldwide).

### Add users through external directory synchronization

If you use external directory synchronization (for example, AD Connect), the on-premises **objectGUID** synchronizes as the Microsoft Office 365 Immutable ID. You can then skip to _Step 3: Add Microsoft Office 365 to Entrust IDaaS_.

note

If a user moves directory forests, the Object ID changes but the Immutable ID does not. Manually modify the Immutable ID as described in [Reconnecting Cloud Users with Old/Previous/Moved AD User Objects](https://msryanph.wordpress.com/category/office-365/dirsync/).

### Add users using PowerShell

You can create users manually or import them in bulk with a CSV file.

**Manually creating users in PowerShell**

1. Connect to Microsoft Graph and get license information:

   ```powershell
   Get-MgSubscribedSku | Select SkuPartNumber, SkuId
   ```

2. Create a new user:

   ```powershell
   $PasswordProfile = @{ Password = '<initial password>' }
   New-MgUser -DisplayName "<Name>" -GivenName "<First name>" -SurName "<LastName>" -UserPrincipalName <name>@<domain> -OnPremisesImmutableID <character string> -MailNickname "<Mail Nickname>" -UsageLocation <Location initials> -AccountEnabled -PasswordProfile $PasswordProfile
   ```

3. Assign a license:

   ```powershell
   Set-MgUserLicense -UserId <name>@<domain> -AddLicenses @{ SkuId = '<license-sku-id>' } -RemoveLicenses @()
   ```

note

If a user requires an update to their `OnPremisesImmutableId`, set the domain back to managed, update the user, and re-federate the domain.

**Bulk importing user profiles using a CSV file**

Follow [Create user accounts with Microsoft Office 365 PowerShell](https://docs.microsoft.com/en-us/office365/enterprise/powershell/create-user-accounts-with-office-365-powershell) and include the `OnPremisesImmutableID` parameter.

After creating users, verify them in the Microsoft Office 365 UI.

To view User Principal Name (UPN) and Immutable ID values, run:

```powershell
Get-MgUser -All -Property DisplayName,OnPremisesImmutableId,UserPrincipalName,AssignedLicenses |
  Select DisplayName,OnPremisesImmutableId,UserPrincipalName,AssignedLicenses
```

Create an Immutable ID for any user missing one:

```powershell
Update-MgUser -UserId <name>@<domain> -OnPremisesImmutableID <character string>
```

If you synchronized with on-premises AD, replace `-OnPremisesImmutableID <character string>` with the Entrust IDaaS user profile Immutable ID (for example, `-OnPremisesImmutableID +FELF0aANBcvfWMLSD=`).

To find a user's Immutable ID in Entrust IDaaS:

1. Click Menu icon **>** **Members > Users** to open the **Users List** page.
2. Click the **User ID** for the profile to edit.
3. Under **Attributes**, enter the values for the O365 Immutable ID and O365 UPN attributes.
4. Click **Save**.

## Step 7: Configure Microsoft Office 365 for Entrust IDaaS using PowerShell

1. Open PowerShell and connect to Microsoft Graph.

2. For each domain to federate, ensure it is not the default domain in Microsoft Office. The default domain cannot be federated through SAML authentication.

3. If the domain was previously federated with another Identity Provider (including Entrust IDaaS or AD FS), break the existing federation first. If you are not using AD FS, you can skip steps specific to AD FS.

4. Verify federated domains:

   ```powershell
   Get-MgDomain
   ```

5. Set authentication to be managed by Microsoft Office 365 and convert the domain to managed authentication:

   ```powershell
   Update-MgDomain -DomainId <domain to convert> -AuthenticationType Managed
   Convert-MsolDomainToStandard -DomainName <domain to convert> -SkipUserConversion:$true -PasswordFile C:\userpasswords.txt
   Set-MsolDomainAuthentication -Authentication Managed -DomainName <domain to convert>
   ```

6. Define the federation variables for each domain:

   ```powershell
   $domain = "<Microsoft Office 365 domain>"
   $issuer = "<EntityID>"
   $logon = "https://<Entrust IDaaS domain>/api/saml/SAML2/SSO"
   $logoff = "https://<Entrust IDaaS domain>/logout.html"
   $cert = "<ds:X509Certificate>"
   ```

   - Open the metadata file downloaded in _Step 5: Download the metadata file from Entrust IDaaS_ to find `EntityID` and `ds:X509Certificate` values.

   - If ActiveSync was enabled in _Step 3_, set:

     ```powershell
     $activeLogOnUri = "<Active Logon URI>"
     ```

     Otherwise, set:

     ```powershell
     $activeLogOnUri = $logon
     ```

   - If multiple domains will be federated, append the domain value (for example, `?domain=<domainname>`) to `$logon`, `$activeLogOnUri`, and `$issuer`.

7. Create the federation configuration:

   ```powershell
   New-MgDomainFederationConfiguration -DomainId $domain -DisplayName $domain -PassiveSignInUri $logon -ActiveSignInUri $activeLogOnUri -IssuerUri $issuer -SignOutUri $logoff -PreferredAuthenticationProtocol "saml" -SigningCertificate $cert -FederatedIdpMfaBehavior "acceptIfMfaDoneByFederatedIdp"
   ```

   If the operation succeeds, PowerShell does not return a response. If an error appears, verify the command format and syntax.

## Examples

### Single domain used in Office 365 for SAML

```powershell
Set-MsolDomainAuthentication -Authentication Managed -DomainName test.example.com
$domain = "test.example.com"
$issuer = "https://test.trustedauth.com/api/saml"
$logon = "https://test.trustedauth.com/api/saml/SAML2/SSO"
$logoff = "https://test.trustedauth.com/logout.html"
$cert = "MIID7zCC..."
$activeLogOnUri = "https://test.trustedauth.com/api/saml/SAML2/SSOSoap/A0FFF35A7CB6D9A1D96B4606793551A85D7B5F07"
New-MgDomainFederationConfiguration -DomainId $domain -DisplayName $domain -PassiveSignInUri $logon -ActiveSignInUri $activeLogOnUri -IssuerUri $issuer -SignOutUri $logoff -PreferredAuthenticationProtocol "saml" -SigningCertificate $cert -FederatedIdpMfaBehavior "acceptIfMfaDoneByFederatedIdp"
```

### Two domains used in Office 365 for SAML

```powershell
Update-MgDomain -DomainId this.sample.com -AuthenticationType Managed
$domain = "this.sample.com"
$issuer = "https://test.trustedauth.com/api/saml?domain=this.sample.com"
$logon = "https://sales.trustedauth.com/api/saml/SAML2/SSO?domain=this.sample.com"
$logoff = "https://sales.trustedauth.com/logout.html"
$cert = "MIID4xDE..."
$activeLogOnUri = "https://sales.trustedauth.com/api/saml/SAML2/SSOSoap/9C4A75F5EB0DDC9A0C826C39B83EFD4C7ECD02EE?domain=this.example.com"
New-MgDomainFederationConfiguration -DomainId $domain -DisplayName $domain -PassiveSignInUri $logon -ActiveSignInUri $activeLogOnUri -IssuerUri $issuer -SignOutUri $logoff -PreferredAuthenticationProtocol "saml" -SigningCertificate $cert -FederatedIdpMfaBehavior "acceptIfMfaDoneByFederatedIdp"
```