> For the complete documentation index, see [llms.txt](https://ajuda.rnp.br/cafe/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ajuda.rnp.br/cafe/idp-cafe/faq/integracao-do-office365-com-shibboleth-idp.md).

# Integração do Office365 com Shibboleth IDP

**Versão 1.0**

## 1. Objetivo

Este guia descreve as configurações necessárias para estabelecer a integração técnica entre o IdP Shibboleth de sua instituição e os serviços de nuvem da Microsoft, como o Microsoft 365. O objetivo é viabilizar o acesso dos usuários ao serviço com suas credenciais institucionais, garantindo a correta transmissão dos atributos necessários e o atendimento aos requisitos técnicos e de segurança exigidos para autenticação federada.

## 2. Estrutura do guia

O guia está dividido nas seguintes seções:

* **Objetivo:** apresenta a finalidade do documento;
* **Estrutura do guia:** como o guia está organizado;
* **Como utilizar este guia:** reúne recomendações para a leitura do documento e orientações importantes antes da execução dos procedimentos;
* **Requisitos para execução do guia:** descreve os pré-requisitos necessários para realizar as configurações apresentadas neste guia;
* **Requisitos da integração com o Microsoft 365:** apresenta os requisitos técnicos que a resposta SAML deve atender para que a autenticação ocorra corretamente;
* **Configurações no IdP Shibboleth:** detalha as alterações que devem ser realizadas nos arquivos de configuração do IdP para atender aos requisitos da integração;
* **Configurações no Microsoft Entra ID:** descreve os procedimentos necessários para configurar a federação do domínio e concluir a integração com o IdP;
* **Solução de problemas:** reúne os problemas mais comuns encontrados durante a validação, suas possíveis causas e as respectivas soluções.

## 3. Como utilizar este guia

Esta seção apresenta recomendações importantes para a utilização deste documento e para a execução segura das alterações no ambiente.

### 3.1. Recomendações

Embora os procedimentos possam ser executados individualmente, recomenda-se a leitura completa deste guia antes de iniciar qualquer alteração no IdP. Isso permitirá compreender o objetivo de cada configuração, seus impactos e a forma como será realizada a validação ao final do processo.

Durante as etapas descritas neste documento, arquivos de configuração serão modificados. Antes de qualquer alteração, recomenda-se realizar backup do ambiente ou dos arquivos originais para possibilitar a restauração do ambiente em caso de necessidade.

Após a conclusão das alterações, será necessário reiniciar o serviço Jetty. Durante esse período, o IdP poderá ficar temporariamente indisponível para autenticação dos usuários. Recomenda-se realizar os procedimentos durante uma janela de manutenção, preferencialmente fora do horário comercial.

Sempre que possível, execute inicialmente os procedimentos em um ambiente de homologação antes de aplicá-los em produção.

### 3.2. Dicas importantes

Os exemplos de conteúdo XML apresentados neste documento foram formatados para facilitar a leitura.

{% hint style="warning" %}
Dependendo do editor utilizado para visualizar este guia (Google Docs, Microsoft Word, navegador etc.), podem ser adicionados caracteres invisíveis, espaços extras ou quebras de linha durante a operação de copiar e colar. Estes caracteres invisíveis podem afetar o funcionamento da aplicação.
{% endhint %}

{% hint style="warning" %}
Por esse motivo, recomenda-se copiar os trechos apresentados inicialmente para um **editor de texto simples** (por exemplo, Notepad, VS Code ou outro editor equivalente). Dessa forma, é possível verificar se o conteúdo foi copiado corretamente antes de inseri-lo nos arquivos de configuração do IdP.
{% endhint %}

Sempre confira cuidadosamente o conteúdo antes de salvar as alterações.

## 4. Requisitos para execução deste guia

Antes de iniciar os procedimentos descritos nas próximas seções, os seguintes requisitos devem ser atendidos.

**Para configuração do IdP:**

* Servidor com IdP Shibboleth versão 5.1.3 ou superior **com MFA**, cuja instalação tenha sido realizada seguindo a receita e/ou template oficial disponibilizado pela equipe da CAFe/RNP para garantir a conformidade técnica;

{% hint style="warning" %}
**ATENÇÃO:** caso este requisito não seja atendido, é necessária avaliação caso a caso para adequações à forma como seu servidor foi instalado/configurado.
{% endhint %}

* Acesso ao servidor com usuário que possua privilégios de root;
* Editor de texto disponível no servidor (vim, nano, etc.);

**Para configuração do Microsoft 365:**

* Tenant do Microsoft 365 com um domínio personalizado previamente configurado. O domínio padrão fornecido pela Microsoft (terminado em `onmicrosoft.com`) não pode ser federado e, portanto, não pode ser utilizado para este procedimento;
* Acesso ao tenant utilizando uma conta com privilégios de Administrador Global ou outra função administrativa com permissão para gerenciar a federação de domínios;
* Ambiente com PowerShell 7 (ou superior) instalado;
* Módulo Microsoft Graph PowerShell SDK instalado;

## 5. Requisitos da integração com o Microsoft

Esta seção descreve os requisitos técnicos esperados pelo Microsoft 365 para que uma autenticação federada utilizando SAML 2.0 seja considerada válida. Independentemente da configuração interna do IdP, a resposta SAML enviada ao Microsoft Entra ID deverá atender aos seguintes requisitos:

* **Requisito 1:** A resposta SAML deve conter uma asserção assinada e não deve estar criptografada.
* **Requisito 2:** O *SAML NameID* deve ser enviado no formato persistente e possuir o mesmo valor do atributo *onPremisesImmutableId* do usuário no Microsoft Entra ID;
* **Requisito 3:** O atributo *mail* deve ser enviado e possuir o mesmo valor do atributo **UserPrincipalName (UPN)** do usuário no Microsoft Entra ID;
* **Requisito 4:** Quando a autenticação for realizada utilizando múltiplos fatores (MFA), a resposta SAML deverá conter o AuthnContextClassRef com o valor `http://schemas.microsoft.com/claims/multipleauthn`.

Os procedimentos descritos nas próximas seções têm como objetivo configurar o IdP Shibboleth e o Microsoft Entra ID para atender a esses requisitos durante as autenticações destinadas ao Microsoft 365.

### 5.1. Visão geral da integração

### A integração entre o IdP Shibboleth e o Microsoft 365 envolve configurações tanto no IdP quanto no tenant do Microsoft 365.

{% stepper %}
{% step %}

#### Adicionar os metadados SAML do serviço Microsoft

{% endstep %}

{% step %}

#### Desabilitar a criptografia da asserção SAML

{% endstep %}

{% step %}

#### Configurar atributo e tipo para SAML NameID

{% endstep %}

{% step %}

#### Configurar a liberação dos atributos exigidos

{% endstep %}

{% step %}

#### Configurar AuthnContextClassRef para sinalização de MFA

{% endstep %}

{% step %}

#### Validar a resposta SAML gerada pelo IdP

{% endstep %}
{% endstepper %}

### **Etapas realizadas no Microsoft 365 (detalhadas na seção 7):**

{% stepper %}
{% step %}

#### Configurar a federação do domínio com o IdP Shibboleth

{% endstep %}

{% step %}

#### Configurar os usuários para autenticação federada

{% endstep %}

{% step %}

#### Validar o processo de autenticação

{% endstep %}
{% endstepper %}

## 6. Configurações no IdP Shibboleth

Nesta seção do guia, serão apresentadas com detalhes as etapas de configurações do IdP Shibboleth necessárias para integração com o Microsoft 365. As configurações descritas são exclusivamente para o serviço em questão e não alteram o comportamento padrão para os demais serviços já existentes ou que serão adicionados futuramente.

### 6.1. Inclusão dos metadados do Microsoft 365

A alteração a seguir deve ser efetuada para estabelecer a relação de confiança entre o IdP Shibboleth e o Microsoft Entra ID por meio da importação dos metadados SAML publicados pela Microsoft. A configuração é feita executando os seguintes passos no servidor do IdP.

{% stepper %}
{% step %}

#### Copie o conteúdo para um editor de texto simples

Copie o seguinte conteúdo para o editor de texto em sua máquina para remoção de caracteres de escape inseridos para facilitar a leitura (ver recomendações da seção 3.2):

```xml
<MetadataProvider id="microsoft365"
    xsi:type="FileBackedHTTPMetadataProvider"
    backingFile="%{idp.home}/metadata/microsoft365-metadata.xml"
    metadataURL="https://nexus.microsoftonline-p.com/federationmetadata/saml20/federationmetadata.xml"
    failFastInitialization="false"/>
```

{% endstep %}

{% step %}

#### Acesse o servidor do IdP

Acesse o servidor do IdP com um usuário que possua privilégios root.
{% endstep %}

{% step %}

#### Faça backup do arquivo de configuração

Faça backup do arquivo `/opt/shibboleth-idp/conf/metadata-providers.xml`.
{% endstep %}

{% step %}

#### Abra o arquivo de configuração

Abra o arquivo `/opt/shibboleth-idp/conf/metadata-providers.xml` com um editor de texto de sua preferência.
{% endstep %}

{% step %}

#### Localize o elemento de fechamento

Localize a última linha do arquivo contendo o elemento `</MetadataProvider>`.
{% endstep %}

{% step %}

#### Insira o conteúdo copiado

Copie o conteúdo transferido para sua máquina no passo 1 e cole numa nova linha **ANTERIOR** à do elemento encontrado no passo 5.
{% endstep %}

{% step %}

#### Confira o resultado

Caso o IdP não tenha sido alterado do padrão de instalação da CAFe/RNP, o trecho do final do arquivo alterado deve ficar semelhante ao conteúdo a seguir:

```xml
... restante do conteúdo do arquivo ...

<MetadataProvider id="microsoft365"
    xsi:type="FileBackedHTTPMetadataProvider"
    backingFile="%{idp.home}/metadata/microsoft365-metadata.xml"
    metadataURL="https://nexus.microsoftonline-p.com/federationmetadata/saml20/federationmetadata.xml"
    failFastInitialization="false"/>
</MetadataProvider>
```

{% endstep %}

{% step %}

#### Valide e salve o arquivo

Valide o conteúdo, salve e feche o arquivo.
{% endstep %}
{% endstepper %}

### 6.2. Remoção de criptografia da resposta SAML para Microsoft 365

A alteração a seguir deve ser efetuada para atender ao **Requisito 1** da integração com o Microsoft 365 (veja **Seção 5**). O procedimento adiciona uma configuração específica para o serviço Microsoft 365, ajustando a forma como o IdP gera a resposta SAML durante as autenticações destinadas a esse serviço.

Nessa configuração, a asserção SAML passa a ser enviada assinada e sem criptografia, conforme os requisitos definidos pelo Microsoft Entra ID, preservando o comportamento padrão para os demais provedores de serviço. A configuração é realizada executando os seguintes passos no servidor do IdP:

{% stepper %}
{% step %}

#### Copie o conteúdo para um editor de texto simples

Copie o seguinte conteúdo para o editor de texto em sua máquina para remoção de caracteres de escape inseridos para facilitar a leitura (ver recomendações da **seção 3.2**):

```xml
<bean parent="RelyingPartyByName" c:relyingPartyIds="urn:federation:MicrosoftOnline">
    <property name="profileConfigurations">
        <list>
            <bean parent="SAML2.SSO" p:encryptAssertions="false" p:signAssertions="true" >
                <property name="nameIDFormatPrecedence">
                    <list>
                        <value>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</value>
                        <value>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</value>
                    </list>
                </property>
            </bean>
            <ref bean="SAML2.Logout" />
        </list>
    </property>
</bean>
```

{% endstep %}

{% step %}

#### Faça backup do arquivo de configuração

Faça backup do arquivo `/opt/shibboleth-idp/conf/relying-party.xml`.
{% endstep %}

{% step %}

#### Abra o arquivo de configuração

Abra o arquivo `/opt/shibboleth-idp/conf/relying-party.xml` com um editor de texto de sua preferência.
{% endstep %}

{% step %}

#### Localize o elemento de lista

Localize o elemento `<util:list id="shibboleth.RelyingPartyOverrides">`.
{% endstep %}

{% step %}

#### Insira o conteúdo copiado

Copie o conteúdo transferido para sua máquina no passo 1 e cole numa nova linha **SEGUINTE** à do elemento encontrado no passo 4.
{% endstep %}

{% step %}

#### Confira o resultado

Caso o IdP não tenha sido alterado do padrão de instalação da CAFe/RNP, o trecho do arquivo alterado deve ficar semelhante ao conteúdo a seguir:

```xml
... restante do conteúdo do arquivo ...

<util:list id="shibboleth.RelyingPartyOverrides">
    <bean parent="RelyingPartyByName"
        c:relyingPartyIds="urn:federation:MicrosoftOnline">
        <property name="profileConfigurations">
            <list>
                <bean parent="SAML2.SSO" p:encryptAssertions="false"
                    p:signAssertions="true" >
                    <property name="nameIDFormatPrecedence">
                        <list>
                            <value>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</value>
                            <value>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</value>
                        </list>
                    </property>
                </bean>
                <ref bean="SAML2.Logout" />
            </list>
        </property>
    </bean>

... restante do conteúdo arquivo ...
```

{% endstep %}

{% step %}

#### Valide e salve o arquivo

Valide o conteúdo, salve e feche o arquivo.
{% endstep %}
{% endstepper %}

### 6.3. Definição do atributo e tipo para NameID

A alteração a seguir deve ser efetuada para atender ao **Requisito 2** da integração com o Microsoft 365 (veja **Seção 5**). O procedimento configura o IdP para utilizar o atributo *ImmutableID* como identificador persistente na geração do SAML NameID durante as autenticações destinadas ao Microsoft 365, mantendo o comportamento padrão para os demais provedores de serviço.

Em uma instalação padrão do IdP Shibboleth disponibilizada pela CAFe/RNP, o atributo *ImmutableID* já está configurado para ser recuperado da base LDAP e definido para utilização no IdP. A configuração é realizada executando os seguintes passos no servidor do IdP.

{% stepper %}
{% step %}

#### Copie o conteúdo para um editor de texto simples

Copie o seguinte conteúdo para o editor de texto em sua máquina para remoção de caracteres de escape inseridos para facilitar a leitura (ver recomendações da **seção 3.2**):

```xml
<bean parent="shibboleth.SAML2PersistentGenerator">
    <property name="activationCondition">
        <bean parent="shibboleth.Conditions.NOT">
            <constructor-arg>
                <bean parent="shibboleth.Conditions.RelyingPartyId"
                    c:candidate="urn:federation:MicrosoftOnline" />
            </constructor-arg>
        </bean>
    </property>
</bean>
<bean parent="shibboleth.SAML2AttributeSourcedGenerator"
    p:format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" p:attributeSourceIds="#{ {'ImmutableID'} }">
    <property name="activationCondition">
        <bean parent="shibboleth.Conditions.RelyingPartyId"
            c:candidate="urn:federation:MicrosoftOnline" />
    </property>
</bean>
```

{% endstep %}

{% step %}

#### Faça backup do arquivo de configuração

Faça backup do arquivo `/opt/shibboleth-idp/conf/saml-nameid.xml`.
{% endstep %}

{% step %}

#### Abra o arquivo de configuração

Abra o arquivo `/opt/shibboleth-idp/conf/saml-nameid.xml` com um editor de texto de sua preferência.
{% endstep %}

{% step %}

#### Localize o gerador persistente

Localize o elemento `<ref bean="shibboleth.SAML2PersistentGenerator" />`.
{% endstep %}

{% step %}

#### Comente a linha localizada

Comente a linha com o elemento encontrado no passo 4.
{% endstep %}

{% step %}

#### Insira o conteúdo copiado

Copie o conteúdo transferido para sua máquina no passo 1 e cole na linha **SEGUINTE** à do elemento encontrado no passo 4.
{% endstep %}

{% step %}

#### Confira o resultado

Caso o IdP não tenha sido alterado do padrão de instalação da CAFe/RNP, o trecho do arquivo alterado deve ficar semelhante ao conteúdo a seguir:

```xml
... restante do conteúdo do arquivo ...

<!--<ref bean="shibboleth.SAML2PersistentGenerator" />-->
<bean parent="shibboleth.SAML2PersistentGenerator">
    <property name="activationCondition">
        <bean parent="shibboleth.Conditions.NOT">
            <constructor-arg>
                <bean parent="shibboleth.Conditions.RelyingPartyId"
                    c:candidate="urn:federation:MicrosoftOnline" />
            </constructor-arg>
        </bean>
    </property>
</bean>
<bean parent="shibboleth.SAML2AttributeSourcedGenerator"
    p:format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" p:attributeSourceIds="#{ {'ImmutableID'} }">
    <property name="activationCondition">
        <bean parent="shibboleth.Conditions.RelyingPartyId"
            c:candidate="urn:federation:MicrosoftOnline" />
    </property>
</bean>

... restante do conteúdo do arquivo ...
```

{% endstep %}

{% step %}

#### Valide e salve o arquivo

Valide o conteúdo, salve e feche o arquivo.
{% endstep %}
{% endstepper %}

### 6.4. Filtro para liberação dos atributos do usuário

A alteração a seguir deve ser efetuada para atender ao **Requisito 3** da integração com o Microsoft 365 (veja **seção 5**). O procedimento configura o IdP para liberar os atributos exigidos pelo Microsoft Entra ID durante as autenticações destinadas ao Microsoft 365, mantendo a política de liberação atualmente utilizada pelos demais provedores de serviço.

A configuração é realizada executando os seguintes passos no servidor do IdP.

{% stepper %}
{% step %}

#### Copie o conteúdo para um editor de texto simples

Copie o seguinte conteúdo para o editor de texto em sua máquina para remoção de caracteres inseridos para facilitar a leitura (ver recomendações da **seção 3.2**):

```xml
<AttributeFilterPolicy id="releaseToMicrosoft365">
    <PolicyRequirementRule xsi:type="Requester" value="urn:federation:MicrosoftOnline" />
    <AttributeRule attributeID="ImmutableID">
        <PermitValueRule xsi:type="ANY"/>
    </AttributeRule>
    <AttributeRule attributeID="mail">
        <PermitValueRule xsi:type="ANY"/>
    </AttributeRule>
</AttributeFilterPolicy>
```

{% endstep %}

{% step %}

#### Faça backup do arquivo de configuração

Faça backup do arquivo `/opt/shibboleth-idp/conf/attribute-filter.xml`.
{% endstep %}

{% step %}

#### Abra o arquivo de configuração

Abra o arquivo `/opt/shibboleth-idp/conf/attribute-filter.xml` com um editor de texto de sua preferência.
{% endstep %}

{% step %}

#### Localize o elemento de fechamento

Localize a última linha do arquivo contendo o elemento `</AttributeFilterPolicyGroup>`.
{% endstep %}

{% step %}

#### Insira o conteúdo copiado

Copie o conteúdo transferido para sua máquina no passo 1 e cole na linha **ANTERIOR** a do elemento encontrado no passo 4.
{% endstep %}

{% step %}

#### Confira o resultado

Caso o IdP não tenha sido alterado do padrão de instalação da CAFe/RNP, o trecho do final do arquivo que foi alterado deve ficar semelhante ao conteúdo a seguir:

```xml
... restante do conteúdo do arquivo ...

<AttributeFilterPolicy id="releaseToMicrosoft365">
    <PolicyRequirementRule xsi:type="Requester"
        value="urn:federation:MicrosoftOnline" />
    <AttributeRule attributeID="ImmutableID">
        <PermitValueRule xsi:type="ANY"/>
    </AttributeRule>
    <AttributeRule attributeID="mail">
        <PermitValueRule xsi:type="ANY"/>
    </AttributeRule>
</AttributeFilterPolicy>
</AttributeFilterPolicyGroup>
```

{% endstep %}

{% step %}

#### Valide e salve o arquivo

Valide o conteúdo, salve e feche o arquivo.
{% endstep %}
{% endstepper %}

### 6.5. Configuração de AuthnContext para autenticações MFA

A alteração a seguir deve ser efetuada para atender ao **Requisito 4** da integração com o Microsoft 365 (veja **seção 5**). O procedimento ajusta o fluxo de autenticação multifator (MFA) do IdP para que, durante as autenticações destinadas ao Microsoft 365, seja incluído na resposta SAML o AuthnContextClassRef esperado pelo Microsoft Entra ID.

Quando um usuário concluir uma autenticação utilizando múltiplos fatores, o IdP adicionará automaticamente à resposta SAML o identificador `http://schemas.microsoft.com/claims/multipleauthn`, permitindo que o Microsoft Entra ID reconheça que a autenticação foi realizada utilizando MFA.

{% hint style="warning" %}
**Atenção!**

Este procedimento utiliza o fluxo de MFA configurado em um IdP Shibboleth 5.1.3+ com MFA instalado com o template padrão disponibilizado pela CAFe/RNP. Caso a instituição ainda não tenha configurado o MFA no IdP e deseje realizar os procedimentos necessários para suportar essa funcionalidade, abra um chamado em <atendimento@rnp.br> com o assunto: "CAFe/MFA - Adequação de IdP para suporte a MFA".
{% endhint %}

Caso seu IdP já suporte MFA, a alteração é realizada executando os seguintes passos no servidor do IdP.

#### Etapa 1

{% stepper %}
{% step %}

#### Acesse o servidor do IdP

Acesse o servidor do IdP com usuário que possua privilégios root.
{% endstep %}

{% step %}

#### Faça download do arquivo de configuração MFA

Execute no terminal o seguinte comando:

```bash
wget https://git.rnp.br/cafe-cliente/mfa-cafe/-/raw/main/templates-conf/microsoft-mfa-authn-config.xml
```

{% endstep %}

{% step %}

#### Faça backup do arquivo de configuração MFA

Faça backup do arquivo `/opt/shibboleth-idp/conf/authn/mfa-authn-config.xml`.
{% endstep %}

{% step %}

#### Substitua o conteúdo do arquivo

Substitua o conteúdo do arquivo `/opt/shibboleth-idp/conf/authn/mfa-authn-config.xml` pelo conteúdo do arquivo baixado no passo 2. Note que o nome do arquivo deve permanecer `/opt/shibboleth-idp/conf/authn/mfa-authn-config.xml`.
{% endstep %}
{% endstepper %}

#### Etapa 2

{% stepper %}
{% step %}

#### Copie o conteúdo para um editor de texto simples

Copie o seguinte conteúdo para o editor de texto em sua máquina para remoção de caracteres que foram inseridos para facilitar a leitura (vide recomendações da **seção 3.2**):

```xml
<entry>
    <key>
        <bean parent="shibboleth.SAML2AuthnContextClassRef"
            c:classRef="http://schemas.microsoft.com/claims/multipleauthn"/>
    </key>
    <value>100</value>
</entry>
```

{% endstep %}

{% step %}

#### Faça backup do arquivo de configuração

Faça backup do arquivo `/opt/shibboleth-idp/conf/authn/authn-comparison.xml`.
{% endstep %}

{% step %}

#### Abra o arquivo de configuração

Abra o arquivo `/opt/shibboleth-idp/conf/authn/authn-comparison.xml` com um editor de texto de sua preferência.
{% endstep %}

{% step %}

#### Localize o mapa de pesos

Localize o elemento `<util:map id="shibboleth.AuthenticationPrincipalWeightMap">`.
{% endstep %}

{% step %}

#### Insira o conteúdo copiado

Copie o conteúdo copiado para sua máquina no passo 5 e cole na linha **SEGUINTE** a do elemento encontrado no passo 8.
{% endstep %}

{% step %}

#### Confira o resultado

Caso o IdP não tenha sido alterado do padrão de instalação da CAFe/RNP, o trecho do arquivo que foi alterado deve ficar semelhante ao conteúdo a seguir:

```xml
... restante do conteúdo do arquivo ...

<util:map id="shibboleth.AuthenticationPrincipalWeightMap">
    <entry>
        <key>
            <bean parent="shibboleth.SAML2AuthnContextClassRef"
                c:classRef="http://schemas.microsoft.com/claims/multipleauthn"/>
        </key>
        <value>100</value>
    </entry>
    <entry>
        <key>
            <bean parent="shibboleth.SAML2AuthnContextClassRef"
                c:classRef="urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"/>
        </key>
        <value>1</value>
    </entry>

... restante do conteúdo do arquivo ...
```

{% endstep %}

{% step %}

#### Valide e salve o arquivo

Valide o conteúdo, salve e feche o arquivo.
{% endstep %}
{% endstepper %}

### 6.6. Restart do serviço

Após concluir todas as alterações, é necessário reiniciar o serviço Jetty para que a nova configuração seja carregada pelo IdP. Enquanto o serviço reinicia, é possível também acompanhar os eventos de logs para identificar caso algum erro ocorra. Para isso, execute o seguinte comando no terminal do servidor IdP com usuário que possua permissão de root:

```bash
systemctl restart jetty.service && tail -f /opt/shibboleth-idp/logs/idp-process.log
```

{% hint style="info" %}
**Obs.:** Após execução do comando anterior, o terminal irá apresentar linhas de LOGs e ficará bloqueado para outros comandos. Para liberar, pressione `Ctrl + c`.
{% endhint %}

### 6.7. Validação da resposta SAML

Antes de prosseguir com as etapas de configuração no Microsoft 365, recomenda-se validar a resposta SAML gerada pelo IdP. O procedimento descrito nesta seção permite verificar se todos os requisitos para integração do serviço foram atendidos com as configurações executadas nas seções anteriores.

Para isso, execute o seguinte comando no terminal do servidor IdP com o usuário que possua permissão de root, substituindo `<user>` pelo login do usuário que será utilizado no teste. Por exemplo, se o username utilizado para se autenticar é `alice.silva`, é este valor que deve ser substituído em `<user>`.

```bash
export IDP_BASE_URL=http://localhost:8080/idp && /opt/shibboleth-idp/bin/aacli.sh --saml2 -n "<user>" -r "urn:federation:MicrosoftOnline"
```

Ao final da execução, confirme que o NameID está no formato persistente e os atributos obrigatórios estão presentes. Um exemplo de saída esperada contém:

* Um `<saml2:NameID>` com `Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"` e `SPNameQualifier="urn:federation:MicrosoftOnline"`;
* O atributo `ImmutableID` (OID `urn:oid:1.2.840.113556.1.4.2`) com o mesmo valor do NameID;
* O atributo `mail` (OID `urn:oid:0.9.2342.19200300.100.1.3`) com o e-mail do usuário.

*Figura 1 – Exemplo de resultado esperado (saída do comando `aacli.sh`)*

Se a validação da resposta SAML foi bem-sucedida, prossiga para configuração do Microsoft 365, conforme descrito na **seção 7**.

## 7. Configurações no Microsoft Entra ID

Esta seção descreve as configurações que devem ser realizadas no Microsoft Entra ID para concluir a integração com o IdP Shibboleth configurado nas seções anteriores. Inicialmente será realizada a federação do domínio que utilizará autenticação institucional. Em seguida, será apresentado como configurar usuários para utilização da autenticação federada e, por fim, será realizado o teste do fluxo de autenticação para validar a integração.

As configurações descritas nesta seção devem ser executadas utilizando uma conta com privilégios administrativos no tenant do Microsoft 365, através do Microsoft Graph PowerShell SDK. Para informações de instalação do módulo consulte [Install the Microsoft Graph PowerShell SDK](https://learn.microsoft.com/en-us/powershell/microsoftgraph/installation).

{% hint style="warning" %}
**ATENÇÃO!**

A conta utilizada para realizar a federação deve pertencer a um domínio diferente daquele que será federado, como o domínio padrão do Microsoft 365 (`*.onmicrosoft.com`). Após a conclusão da federação, todas as autenticações dos usuários do domínio federado passarão a ser realizadas pelo IdP da instituição.

Por esse motivo, caso a integração ainda não esteja concluída ou ocorra algum problema durante a configuração, administradores que possuam contas exclusivamente no domínio federado poderão perder o acesso ao portal de administração do Microsoft Entra ID.
{% endhint %}

### 7.1. Configuração da federação do domínio

A alteração a seguir estabelece uma relação de confiança entre o Microsoft Entra ID e o IdP Shibboleth da instituição, permitindo que as autenticações dos usuários pertencentes ao domínio configurado sejam realizadas pelo IdP.

{% stepper %}
{% step %}

#### Solicite o certificado SAML

Solicite ao operador do IdP da instituição o certificado SAML armazenado em `/opt/shibboleth-idp/credentials/idp.crt`.
{% endstep %}

{% step %}

#### Salve o arquivo do certificado

Salve o arquivo em sua máquina que será utilizado para executar os passos a seguir.
{% endstep %}

{% step %}

#### Conecte-se ao Microsoft Graph

Abra uma janela do PowerShell com privilégios administrativos e execute o seguinte comando:

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

{% endstep %}

{% step %}

#### Autentique-se no tenant

Será apresentada uma janela para autenticação. Efetue o login utilizando a conta administrativa do tenant do Microsoft 365.
{% endstep %}

{% step %}

#### Crie as variáveis de configuração

Crie as variáveis abaixo alterando os valores para os definidos no IdP da instituição, conforme descrição:

* `$Domain`: Domínio que será federado (ex.: `example.org`).
* `$LogOnUrl`: Endpoint SAML de autenticação do IdP.
* `$LogOffUrl`: Endpoint SAML de logout do IdP.
* `$IssuerUri`: EntityID do IdP Shibboleth.
* `$Certificate`: Certificado salvo no passo 1.

```powershell
########
$Domain = "example.org"
$LogOnUrl = "https://idp.example.org/idp/profile/SAML2/POST/SSO"
$LogOffUrl = "https://idp.example.org/idp/profile/SAML2/Redirect/SLO"
$IssuerUri = "https://idp.example.org/idp/shibboleth"
$Certificate = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("idp.crt")
$SigningCertificate = [System.Convert]::ToBase64String($Certificate.RawData)
$Protocol = "saml"
```

{% endstep %}

{% step %}

#### Configure a federação do domínio

Execute o comando abaixo para efetuar a configuração de federação do domínio:

```powershell
New-MgDomainFederationConfiguration -DomainId $Domain -PassiveSignInUri $LogOnUrl -SignOutUri $LogOffUrl -IssuerUri $IssuerUri -SigningCertificate $SigningCertificate -PreferredAuthenticationProtocol $Protocol -FederatedIdpMfaBehavior "enforceMfaByFederatedIdp"
```

{% hint style="info" %}
**Obs.:** Após a execução com sucesso do comando acima, a alteração de alguma informação posteriormente deve ser executada com o comando `Update-MgDomainFederationConfiguration`.
{% endhint %}
{% endstep %}

{% step %}

#### Valide o redirecionamento para o IdP

Acesse via navegador a URL `https://login.microsoftonline.com` e insira um e-mail de usuário pertencente ao domínio federado. O resultado esperado é que o navegador seja redirecionado para página de login do IdP.
{% endstep %}
{% endstepper %}

### 7.2. Configuração de usuários no Microsoft Entra ID

Após a federação do domínio, para que os usuários do IdP possam acessar o Microsoft 365, suas contas devem estar previamente configuradas no Microsoft Entra ID, com os mesmos atributos que o IdP irá enviar na resposta SAML, conforme descrito na **seção 5** e resumido a seguir:

* O atributo **OnPremisesImmutableId** do usuário no Microsoft Entra ID deve possuir o mesmo valor do atributo **NameID** enviado pelo IdP;
  * Para este guia, o NameID é enviado com o valor do atributo `ImmutableID` do usuário no LDAP, conforme configurado na **seção 6.3**.
* O atributo **UserPrincipalName** do usuário no Microsoft Entra ID deve possuir o mesmo valor do atributo **mail** enviado pelo IdP.

Esses valores podem ser recuperados com a execução do procedimento descrito na **seção 6.7**, utilizando como parâmetro `<user>` o login do usuário que deseja obter as informações para configuração no Microsoft Entra ID. O próprio usuário também pode recuperar essas informações acessando o serviço <https://sp.rnp.br/cafe>.

As próximas seções apresentam exemplos de criação e atualização de usuários utilizando o Microsoft Graph PowerShell.

#### 7.2.1. Criar um usuário

Para criar um usuário, execute os passos descritos a seguir:

{% stepper %}
{% step %}

#### Recupere as informações do usuário

Recupere as informações do usuário para configurar no Microsoft Entra ID. Para inclusão de novos usuários, são obrigatórios os atributos: `DisplayName`, `UserPrincipalName`, `MailNickname` e `OnPremisesImmutableId`.
{% endstep %}

{% step %}

#### Conecte-se ao Microsoft Graph

Abra uma janela do PowerShell com privilégios administrativos e execute o seguinte comando:

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

{% endstep %}

{% step %}

#### Adicione a nova conta

Execute o comando abaixo para adicionar uma nova conta no Microsoft Entra ID, alterando os valores destacados para as informações do usuário coletadas no passo 1:

```powershell
New-MgUser -DisplayName "John Doe" -UserPrincipalName "john.doe@example.org" -MailNickname "johndoe" -AccountEnabled -OnPremisesImmutableId "550e8400-e29b-41d4-a716-446655440000"
```

{% endstep %}
{% endstepper %}

#### 7.2.2. Atualizar um usuário existente

Caso o usuário já exista no Microsoft Entra ID, atualize o atributo `OnPremisesImmutableId` para que possua o mesmo valor enviado pelo IdP.

{% stepper %}
{% step %}

#### Recupere o valor do atributo ImmutableID

Recupere o valor do atributo `ImmutableID` no usuário no IdP.
{% endstep %}

{% step %}

#### Conecte-se ao Microsoft Graph

Abra uma janela do PowerShell com privilégios administrativos e execute o seguinte comando:

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

{% endstep %}

{% step %}

#### Atualize a conta existente

Execute o comando abaixo para atualizar a conta existente no Microsoft Entra ID, alterando os valores destacados pelas informações do usuário recuperado no passo 1:

```powershell
Update-MgUser -UserId "john.doe@example.org" -OnPremisesImmutableId "550e8400-e29b-41d4-a716-446655440000"
```

{% endstep %}
{% endstepper %}

### 7.3. Validação com acesso ao serviço Microsoft 365

Esta etapa tem como objetivo validar a integração ponta a ponta entre o IdP da instituição e o serviço Microsoft 365, confirmando que o usuário consegue autenticar utilizando suas credenciais institucionais após as configurações realizadas neste guia.

Acesse, via navegador, a URL apresentada a seguir, substituindo o texto em destaque pelo domínio federado nesse guia:

```
https://login.microsoftonline.com/?whr=example.org
```

Após isso:

{% stepper %}
{% step %}

#### Redirecionamento para o IdP

O navegador deverá ser redirecionado para a página de login do IdP da instituição.
{% endstep %}

{% step %}

#### Autenticação institucional

Após o usuário realizar a autenticação utilizando suas credenciais institucionais, o IdP enviará a resposta SAML ao Microsoft Entra ID.
{% endstep %}

{% step %}

#### Acesso ao portal Microsoft 365

Após validação do serviço, o usuário deverá ser redirecionado para o portal do Microsoft 365.
{% endstep %}
{% endstepper %}

Se o acesso for realizado sem erros de autenticação ou de validação dos atributos SAML, a integração poderá ser considerada concluída com sucesso.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://ajuda.rnp.br/cafe/idp-cafe/faq/integracao-do-office365-com-shibboleth-idp.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.