# Federation setup

Federation is the final step. It switches your Microsoft 365 domain from managed (password-based) to federated authentication managed by Peig. After this step, users can no longer log in with passwords — all authentication flows through Peig.

{% hint style="danger" %}
**Plan this step carefully.** Once the domain is switched to federated, users cannot log in with passwords until federation is reversed. Execute this step during a period of minimal user activity — early morning, late evening, or a weekend.

Federation can only be enabled or disabled once every 10 minutes.
{% endhint %}

## Prerequisites

Before proceeding, confirm:

* [ ] The migration configuration has been deleted (Step 4 is complete)
* [ ] All users are onboarded to Peig
* [ ] You have Windows PowerShell available with internet access
* [ ] You have Global Administrator credentials for your Microsoft 365 tenant

## Option A: Automatic (recommended)

Peig generates all required PowerShell commands pre-filled with your workspace's SAML configuration.

1. Open **Configuration** in Peig
2. Find your Microsoft 365 Active Provider
3. Click the **(i)** icon next to the provider
4. Copy the displayed PowerShell commands
5. Run them in Windows PowerShell

Federation is now active.

## Option B: Manual

If you prefer to configure federation manually, follow these steps.

### Install the Microsoft Graph PowerShell module

If not already installed, run:

```powershell
Install-Module Microsoft.Graph -Scope CurrentUser -AllowClobber
```

### Retrieve your SAML IDP details from Peig

1. Open **Configuration** in Peig
2. Click **SAML IDP Info**
3. Note the following values:
   * **IDP Entity ID** — format: `https://[SERVER]/idp/shibboleth`
   * **IDP Sign-In URL** — format: `https://[SERVER]/idp/profile/SAML2/POST/SSO`
   * **IDP Sign-Out URL** — format: `https://[SERVER]/idp/profile/Logout`
   * **IDP Certificate** — remove all whitespace and the `-----BEGIN CERTIFICATE-----` / `-----END CERTIFICATE-----` lines, keeping only the certificate data

### Connect to Microsoft Graph

```powershell
Connect-MgGraph -Scopes "Domain.ReadWrite.All", "Directory.ReadWrite.All"
```

Sign in with your Microsoft 365 Global Administrator credentials.

### Define your variables

```powershell
$dom      = "yourcompany.com"
$name     = "Peig"
$entityId = "https://[SERVER]/idp/shibboleth"
$signIn   = "https://[SERVER]/idp/profile/SAML2/POST/SSO"
$signOut  = "https://[SERVER]/idp/profile/Logout"
$cert     = "your-certificate-data"
```

### Activate federation

**For a domain not yet federated:**

```powershell
New-MgDomainFederationConfiguration `
  -DomainId $dom `
  -PassiveSignInUri $signIn `
  -SigningCertificate $cert `
  -IssuerUri $entityId `
  -SignOutUri $signOut `
  -PreferredAuthenticationProtocol "saml" `
  -FederatedIdpMfaBehavior "enforceMfaByFederatedIdp"
```

**For a domain with existing federation (updating):**

```powershell
Update-MgDomainFederationConfiguration `
  -DomainId $dom `
  -PassiveSignInUri $signIn `
  -SigningCertificate $cert `
  -IssuerUri $entityId `
  -SignOutUri $signOut `
  -PreferredAuthenticationProtocol "saml" `
  -FederatedIdpMfaBehavior "enforceMfaByFederatedIdp"
```

## After federation is active

* All Microsoft 365 sign-in attempts for your domain are redirected to Peig
* Users authenticate via their registered Peig device — no password required
* The Peig workspace dashboard is now the access point for all connected Microsoft 365 services

Notify your team that the change is live and explain the new sign-in experience.

{% hint style="info" %}
If your team uses Windows devices enrolled in Microsoft Entra ID, see [Entra Device Enrollment](/welcome-to-peig-documentation/deployment-guides/microsoft-365/entra-device-enrollment.md) to configure Peig as the Web Sign-In provider for the Windows lock screen.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.peig.io/welcome-to-peig-documentation/deployment-guides/microsoft-365/federation-setup.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.