Integração com o Office 365

Integrações · Autenticação · 1.2

A integração entre o Gfacility e o Office 365 assenta numa abordagem 2-legged, com um registo de aplicação no Microsoft Entra ID (anteriormente Azure Active Directory). O Gfacility inicia sessão com a identidade dessa aplicação, sem pop-up nem consentimento por utilizador. É mais estável e mais seguro.

Como funciona?

A integração tem quatro componentes. Ativa cada um em separado no Gfacility, em Integrations & Login → Office 365. Todos funcionam através de um único registo de aplicação da sua organização.

Sincronização de utilizadores · todas as noites

Coloca os seus colaboradores no Gfacility.

Sincronização de departamentos · com a de utilizadores

Associa cada colaborador ao respetivo departamento.

Sincronização de localizações · todas as noites

Coloca as salas de reuniões no Gfacility, com edifício e piso.

Sincronização de calendários · imediata

Mantém as reservas iguais no Gfacility e no Outlook.

Sincronização de utilizadores

Todas as noites, o Gfacility vai buscar os seus colaboradores à Microsoft.

Novo colaborador? É criado.
Dados alterados? O nome, o endereço de e-mail e o número de telefone são atualizados.
Saiu da empresa? Quem já não consta na Microsoft passa a inativo no Gfacility.

Que campos são copiados?

Campo na Microsoft	Campo no Gfacility
Nome de início de sessão (`userPrincipalName`)	Endereço de e-mail
Nome próprio (`givenName`)	Nome próprio
Apelido (`surname`)	Apelido
Telemóvel (`mobilePhone`)	Número de telefone
Departamento (`department`)	Organização principal, apenas com a sincronização de departamentos ativa
Licença	Ativo ou inativo

Nota: o endereço de e-mail no Gfacility é o nome de início de sessão Microsoft, não o campo E-mail. Normalmente são iguais.

Não são copiados: o cargo, o local de trabalho, o telefone profissional e a fotografia de perfil. Um novo colaborador recebe a organização predefinida e a localização predefinida do seu workspace; pode alterá-las depois no Gfacility.

Convém saber:

Só são incluídos os colaboradores com uma licença do Microsoft 365. As salas e as caixas de correio partilhadas não.
A sincronização de utilizadores não trata do início de sessão. Apenas garante que o Gfacility conhece os seus colaboradores. Para o início de sessão, escolha Iniciar sessão com Microsoft ou SSO.

Importar apenas uma parte dos seus colaboradores?

O Gfacility vai sempre buscar todos os colaboradores. Não é possível restringir isso na Microsoft, nem com RBAC nem atribuindo utilizadores à aplicação. Por isso, é o Gfacility que configura o filtro por si.

Envie-nos uma query para esse efeito: a regra que determina quem fica incluído. Por exemplo:

Por domínio de e-mail: endswith(mail,'@suaempresa.pt')
Por departamento: department eq 'Facilities'
Por país: usageLocation eq 'NL'
Combine com and, or e not.

Não sabe qual é a query? Descreva em palavras simples quem deve e quem não deve ser incluído. Nós transformamos isso numa query. Ainda não é possível filtrar por grupo. Atenção: quem deixar de corresponder ao filtro passa a inativo na sincronização seguinte.

Sincronização de departamentos

A sincronização de departamentos é uma opção adicional da sincronização de utilizadores. Ativa-a em Integrations & Login → Office 365, logo abaixo da sincronização de utilizadores. O interruptor só aparece quando a sincronização de utilizadores está ativa. Não é necessária nenhuma permissão adicional: User.Read.All é suficiente.

Em cada sincronização de utilizadores, o Gfacility lê o campo Departamento de cada utilizador no Microsoft Entra ID e associa o utilizador à organização com esse nome, como organização principal.

Situação	O que o Gfacility faz
Existe uma organização com esse nome	O utilizador é associado a essa organização. O Gfacility procura-a primeiro pelo nome e depois pelo código, sem distinguir maiúsculas de minúsculas.
Ainda não existe nenhuma organização	O Gfacility cria uma nova organização no nível superior, com o nome do departamento como nome e como código, e o tipo de organização Department (ou o tipo predefinido, se esse não existir).
O departamento no Entra está vazio	O utilizador mantém a organização atual. Um novo utilizador recebe a organização predefinida.
O departamento de um utilizador muda	Na sincronização seguinte, é associado à nova organização.

Convém saber

O Entra prevalece. Uma organização principal que altere manualmente no Gfacility volta a ser o departamento do Entra na sincronização seguinte.
As organizações existentes nunca são alteradas nem eliminadas. Se um departamento desaparecer do Entra, a organização continua no Gfacility.
Já tem as organizações criadas? Garanta que o nome ou o código corresponde exatamente ao departamento no Entra antes de ativar a sincronização. Caso contrário, o Gfacility cria uma segunda organização. Quer outro nome no Gfacility? Coloque o nome do departamento do Entra no código.
As organizações criadas de novo ficam no nível superior. Pode depois movê-las na árvore; a associação continua a funcionar, porque é feita pelo nome ou pelo código.
Ativar a sincronização de departamentos com a sincronização de utilizadores já ativa inicia de imediato uma sincronização.

Sincronização de localizações (Places)

Todas as noites, o Gfacility vai buscar as salas de reuniões à Microsoft. Para cada sala, são atualizados o nome, a capacidade, o edifício e o piso. Um edifício ou piso que ainda não exista é criado pelo Gfacility.

Que campos são copiados?

Campo na Microsoft	Campo no Gfacility
Nome a apresentar (`DisplayName`)	Nome
Endereço de e-mail da sala	Endereço de e-mail (a ligação ao calendário da sala)
Capacidade (`Capacity`)	Capacidade
Edifício (`Building`)	Edifício (localização superior)
Número do piso (`Floor`)	Piso (nome e código)
ID da sala	Código

Não são copiados: o nome do piso (FloorLabel), a morada e a cidade, o equipamento (ecrã, áudio, vídeo), a acessibilidade para cadeiras de rodas e as etiquetas.

Atenção: em cada sincronização, o Gfacility volta também a marcar a sala como reservável e preenche a descrição com um texto fixo. Se alterar qualquer um destes no Gfacility, a sincronização seguinte repõe-no. Para que uma sala não seja tocada, desative a sincronização externa dessa sala no Gfacility.

Como configurar isto na Microsoft é explicado em Gestão de salas no Microsoft.

Sincronização de calendários

A sincronização de calendários funciona nos dois sentidos:

Do Gfacility para o Outlook. Crie uma reserva no Gfacility e ela aparece também no calendário do Outlook do organizador, com a sala incluída. Altere-a ou cancele-a e o mesmo acontece no Outlook.
Do Outlook para o Gfacility. Mova, altere ou cancele essa reunião no Outlook e o Gfacility atualiza de imediato a reserva.
Calendários das salas. O Gfacility lê também os calendários das salas de reuniões. Assim, o quadro de planeamento e os ecrãs das salas mostram também as reuniões reservadas apenas no Outlook.

O que é sincronizado?

Dados	Sentido
Título	Nos dois sentidos
Hora de início e de fim, dia inteiro	Nos dois sentidos
Descrição	Nos dois sentidos (o texto do Teams é removido)
Participantes (colegas e visitantes)	Nos dois sentidos
Salas	Nos dois sentidos. No Outlook aparecem como participante e em Localização
Reunião do Teams e respetiva ligação	Nos dois sentidos
Cancelamento	Nos dois sentidos
Organizador	Do Outlook para o Gfacility
Catering e serviços	Ficam no Gfacility. Se a hora ou a sala mudar no Outlook, são assinalados para revisão

Dos calendários das salas, o Gfacility lê por reunião: título, hora de início e de fim, organizador, número de participantes e se a sala aceitou. Uma reunião marcada como privada no Outlook aparece no Gfacility como “Privado”.

Convém saber:

Uma reunião reservada apenas no Outlook não se torna uma reserva no Gfacility. A sala aparece, no entanto, como ocupada.
Todas as noites, o Gfacility verifica se houve alterações não captadas e recupera-as.

Como se configura?

São quatro passos:

Crie um registo de aplicação na Microsoft.
Atribua as permissões.
Escolha como o Gfacility pode aceder aos calendários.
Introduza os dados no Gfacility.

Depois, ative no Gfacility os componentes que quer usar.

1. Criar um registo de aplicação no Azure Portal

Crie um registo de aplicação dedicado ao Gfacility, separado de outras aplicações. Assim, o controlo e a segurança ficam nas suas mãos.

Passo	O que fazer
1	Inicie sessão no Azure Portal → Registos de aplicações.
2	Clique em + Novo registo e introduza um nome.
3	Escolha o tipo de conta adequado (por exemplo Contas apenas neste diretório organizacional).
4	O URI de redirecionamento pode ficar em branco.
5	Clique em Registar. Anote o ID da aplicação (cliente) e o ID do diretório (inquilino).
6	Aceda a Certificados e segredos.
7	Clique em + Novo segredo do cliente e indique uma descrição e uma data de expiração.
8	Clique em Adicionar.

2. Atribuir permissões de API

No registo de aplicação, aceda a Permissões de API → + Adicionar uma permissão → Microsoft Graph. Adicione por caso de utilização:

Integração de utilizadores

Para que o Gfacility conheça os seus colaboradores. Para o início de sessão propriamente dito, consulte Iniciar sessão com Microsoft ou SSO.

Aplicação: User.Read.All
Delegada: User.Read

Places / Localizações

Sincronização automática das salas de reuniões a partir do Outlook.

Aplicação: Place.Read.All

Calendários (eventos do Outlook)

Para reservas, agendamento, análises e ecrãs das salas. Para isto escolhe uma de duas formas no passo 3, por isso não adicione ainda nada aqui.

Calendários partilhados

Acesso a caixas de correio partilhadas.

Delegada: Calendars.Read.Shared
Delegada: Calendars.ReadWrite.Shared

Por fim, clique em Conceder consentimento de administrador para [inquilino]. Caso contrário, as permissões ficam pendentes.

3. Escolher como o Gfacility pode aceder aos calendários

O Gfacility tem de ler e escrever eventos nos calendários das salas e dos utilizadores. Escolha uma destas duas formas:

Opção A · Todos os calendários

A mais simples. O Gfacility obtém acesso a todos os calendários do seu inquilino.

Aplicação: Calendars.ReadWrite

Adicione-a no Entra ID, a par das permissões do passo 2, e conceda o consentimento de administrador. Calendars.Read não é necessária: a ReadWrite já inclui a leitura.

Opção B · Restrito via Exchange RBAC

O Gfacility só obtém acesso às caixas de correio que escolher, por exemplo as salas e os colaboradores que fazem reservas.

Não adicione nenhuma permissão de calendário no Entra ID. O acesso é configurado no Exchange Online, conforme os passos abaixo.

Opção B passo a passo (Exchange Online PowerShell)

1. Ligue-se e crie o principal de serviço. Use o ID da aplicação e o ID do objeto da aplicação empresarial, não do registo de aplicação:

Connect-ExchangeOnline

New-ServicePrincipal `
  -AppId "<Application ID>" `
  -ObjectId "<Enterprise App Object ID>" `
  -DisplayName "Gfacility Application RBAC"

2. Crie um âmbito. Com base num domínio ou num grupo com correio ativado (os grupos de segurança normais não funcionam):

# Opção 1: por domínio (os novos utilizadores ficam automaticamente dentro do âmbito)
New-ManagementScope `
  -Name "Gfacility-DomainScope" `
  -RecipientRestrictionFilter "PrimarySmtpAddress -like '*@contoso.com'"

# Opção 2: por grupo com correio ativado (controlo total)
$Group = Get-DistributionGroup "Gfacility Scope"
New-ManagementScope `
  -Name "Gfacility-GroupScope" `
  -RecipientRestrictionFilter "MemberOfGroup -eq '$($Group.DistinguishedName)'"

3. Atribua a função. Use Application Calendars.ReadWrite, porque o Gfacility escreve reservas nos calendários. Só com Application Calendars.Read, as reservas nunca chegam ao Outlook.

New-ManagementRoleAssignment `
  -Name "Gfacility-Calendars-Scoped" `
  -Role "Application Calendars.ReadWrite" `
  -App "<Application ID>" `
  -CustomResourceScope "Gfacility-DomainScope"

Get-ManagementRoleAssignment -App "<Application ID>" | Format-List Name,Role,CustomResourceScope

4. Teste com uma sala e um utilizador:

Test-ServicePrincipalAuthorization -Identity "<Application ID>" -Resource "meetingroom1@contoso.com"
Test-ServicePrincipalAuthorization -Identity "<Application ID>" -Resource "employee@contoso.com"

Ambos têm de mostrar InScope True, com Calendars.ReadWrite.

Consulte também o guia da Microsoft sobre o Application RBAC no Exchange Online.

4. Introduzir os dados no Gfacility

O administrador do Gfacility introduz estes dados em Integrations & Login → Office 365 → Service account (app registration) e clica em Test connection. Em alternativa, partilhe-os connosco:

ID da aplicação (cliente)
ID do diretório (inquilino)
Valor do segredo do cliente

Partilhe estes dados sensíveis por um meio seguro (uma ligação de um gestor de palavras-passe), nunca soltos num e-mail.

← Anterior: Gestão de salas no Microsoft Seguinte: Iniciar sessão com Microsoft→