# Integrating OpenIAM as your IdP

Configure OpenIAM as the identity provider and Microsoft Entra ID as the service provider.

In this flow, users start in Entra ID. Entra ID redirects them to OpenIAM for authentication. After sign-in, OpenIAM returns them to Entra ID.

{% hint style="warning" %}
**Before you start** complete [Configuring SSO](/federation/configuring-sso.md) to ensure OpenIAM is ready to act as an IdP.
{% endhint %}

{% hint style="warning" %}
Your OpenIAM URLs must use HTTPS. Microsoft requires it. If HTTPS is not in place, the configuration can fail silently.
{% endhint %}

Use a PowerShell session for this configuration.

{% stepper %}
{% step %}

### Load Microsoft.Graph

Load the Microsoft.Graph PowerShell module.

```powershell
Import-Module Microsoft.Graph
```

If the command fails, install the module first:

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

{% endstep %}

{% step %}

### Connect to your Entra ID tenant

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

These scopes allow you to manage domain and user settings.
{% endstep %}

{% step %}

### Load the OpenIAM certificate

Download the signing certificate from OpenIAM and load it into a PowerShell variable:

```powershell
[string]$cer = Get-Content "path_to_downloaded_certificate_from_OpenIAM"
```

{% endstep %}

{% step %}

### Create the domain dederation configuration

Run the following command, replacing the example values with your own:

```powershell
New-MgDomainFederationConfiguration -DomainId "yourdomain.com" `
  -ActiveSignInUri "https://{OpenIAMAddress}/idp/saml2/idp/login" `
  -PassiveSignInUri "https://{OpenIAMAddress}/idp/saml2/idp/login" `
  -IssuerUri "https://{OpenIAMAddress}/idp/saml2/idp/login/{IssuerIdentifier}" `
  -SignOutUri "https://{OpenIAMAddress}/idp/saml2/idp/logout" `
  -PreferredAuthenticationProtocol "saml" `
  -SigningCertificate $cer `
  -FederatedIdpMfaBehavior "rejectMfaByFederatedIdp"
```

| Parameter             | Description                                                                                                                      |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `-DomainId`           | The domain you want to federate with OpenIAM. **Use lowercase only** — mixed case can cause the `AADSTS50107` error in Entra ID. |
| `-ActiveSignInUri`    | Your OpenIAM active sign-in endpoint.                                                                                            |
| `-PassiveSignInUri`   | Your OpenIAM passive sign-in endpoint (same as active for most setups).                                                          |
| `-IssuerUri`          | The issuer identifier from OpenIAM.                                                                                              |
| `-SignOutUri`         | Your OpenIAM logout endpoint.                                                                                                    |
| `-SigningCertificate` | The certificate loaded in Step 3.                                                                                                |

{% hint style="info" %}
The change can take up to 15 minutes to propagate. Time may vary by region.
{% endhint %}
{% endstep %}

{% step %}

### Test the configuration

Open an Entra ID or Microsoft 365 service such as `portal.office.com`. Enter `username@yourdomain` where `yourdomain` is the federated domain. You should be redirected to OpenIAM for authentication instead of seeing a password prompt.
{% endstep %}
{% endstepper %}

## Verifying federation parameters

To verify the current federation configuration for a domain:

```powershell
Get-MgDomainFederationConfiguration -DomainId "yourdomain.com" | Select-Object *
```

## Removing federation configuration

To remove the federation configuration:

```powershell
Remove-MgDomainFederationConfiguration -DomainId "yourdomain.com" `
  -InternalDomainFederationId "{Federation-ID}"
```

Get the `Federation-ID` from the output of the verify command above.

## User sign-on requirements

To sign in to Entra ID with OpenIAM as the IdP, each Entra ID user must have an `ImmutableId` (called `OnPremisesImmutableId` in Microsoft.Graph). Its value must match the value defined in OpenIAM.

If you already have users in the tenant, you will likely need to set this value for each user.

**Check whether it is present:**

```powershell
Get-MgUser -UserId "user@yourdomain.com" -Property OnPremisesImmutableId | Format-List *
```

**Set it if missing** (you can use the same value as the UserPrincipalName):

```powershell
Update-MgUser -UserId "user@yourdomain.com" `
  -OnPremisesImmutableId "user@yourdomain.com"
```


---

# 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-beta.openiam.com/federation/integrating-openiam-as-your-idp.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.