How-to: Setup and Migrate Office 365 Integration with Keycloak

Knowledge Base Community
, , , , ,
1

HowTo:

Setup and Migrate Office 365 Integration with Keycloak Federation using Microsoft Graph

Overview

This guide provides a step-by-step process to install, configure, and migrate the Office 365 integration for Univention Corporate Server (UCS) using Keycloak as the identity provider. Additionally, it explains how to use the Microsoft Graph SDK for configuring SAML-based federation via PowerShell 7.

Environment

  • Product: Univention Corporate Server (UCS)

  • Components:

    • Office 365 Connector
    • Keycloak for UCS

  • External Requirements:

    • PowerShell 7.5.2 or later
    • .NET Framework (based on your Windows version)
    • Microsoft Graph SDK

Prerequisites

  • UCS system with administrative access
  • Windows 10 (or compatible OS) for executing PowerShell scripts
  • Administrator privileges on the Windows machine
  • DNS and domain properly set up for federation
  • A working Keycloak realm with SAML endpoints configured

Step 1: Install and Configure Office 365 App

  1. Install the Office 365 app from the Univention App Center.
  2. Complete the setup using the wizard in the Univention Management Console (UMC).

Refer to the UCS manual for detailed instructions:
https://docs.software-univention.de/manual/latest/en/idm-cloud/office-365.html#idmcloud-o365

Step 2: Perform Keycloak Migration for Office 365

Follow the official Keycloak migration documentation to adapt the UCS Office 365 connector for Keycloak (SAML-based authentication):

Keycloak Migration Guide:
https://docs.software-univention.de/keycloak-migration/migration-examples/saml.html#microsoft-365-connector

Step 3: Prepare the Windows Environment for PowerShell 7 and Microsoft Graph

  1. Install PowerShell 7.5.2
    Download and install from the official GitHub release:
    PowerShell 7.5.2 MSI Installer

  2. Install .NET Framework (based on your Windows version):
    https://learn.microsoft.com/en-us/dotnet/framework/install/

  3. Start PowerShell as Administrator and run:

    Install-Module PowerShellGet -Force
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Install-Module Microsoft.Graph -Scope AllUsers -Repository PSGallery -Force
Install-Module Microsoft.Graph.Beta -Repository PSGallery -Force

Step 4: Configure SAML Federation via Microsoft Graph

Use the following PowerShell script to configure federation for your domain:

# Connect to Microsoft Graph
Connect-MgGraph -Scopes "Domain.ReadWrite.All", "Directory.AccessAsUser.All"

# Set variables
$sso_url = "https://sso.m365conn.univention.de"
$signing_cert = "<Your_Base64_Encoded_Certificate>"
$domain = "m365conn.univention"
$username = "<your-admin-username>"
$password = "<your-admin-password>"
$realm = "UCS"

$issuer_uri = "$sso_url/realms/$realm"
$passive_logon_uri = "$sso_url/realms/$realm/protocol/saml"
$logoff_uri = "$sso_url/realms/$realm/protocol/saml"
$protocol = "saml"

# Prepare credentials
$pass = ConvertTo-SecureString -String "$password" -AsPlainText -Force
$credential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $username, $pass

# Use Get-Credential if needed
$o365cred = Get-Credential $credential

# Switch to managed before setting federation
Update-MgDomain -DomainId $domain -AuthenticationType "Managed"

# Create new Federation Configuration
New-MgDomainFederationConfiguration `
  -DomainId $domain `
  -IssuerUri $issuer_uri `
  -PassiveSignInUri $passive_logon_uri `
  -PreferredAuthenticationProtocol $protocol `
  -SignOutUri $logoff_uri `
  -SigningCertificate $signing_cert `
  -FederatedIdpMfaBehavior "acceptIfMfaDoneByFederatedIdp"

Notes

  • The certificate must be a Base64-encoded X.509 certificate string.
  • The domain must already be verified in your Microsoft 365 tenant.
  • If issues occur, ensure that Connect-MgGraph is authenticated properly and the necessary permissions are granted.
  • If sporadic errors occur when logging out of Office365, reinitializing and fully reconfiguring the setup as described above may help. This approach has resolved logout issues in several environments.

Conclusion

By following the steps above, you can successfully configure Office 365 integration on UCS using Keycloak as a federated SAML identity provider. Transitioning from Windows-native PowerShell scripts to Microsoft Graph SDK is now the recommended and future-proof method for managing Azure AD federation.

For more information, visit:

Root Cause

Bug 52413

1 Like