Capítulo 1

Visão Geral da Integração OAuth

Bem-vindo à documentação oficial de integração do ACAPADEV ID. O nosso sistema atua como o servidor central de identidade (SSO) para todo o ecossistema de aplicações desenvolvidas por si ou por terceiros.

Em vez de construir um sistema de login isolado para o Contagil, outro para o A&C Farma, e outro para um sistema de faturação futuro, delegará toda a responsabilidade de Autenticação e Segurança ao ACAPADEV ID utilizando o protocolo aberto OAuth 2.0.

Como Funciona a Arquitetura?

Na prática, as suas aplicações satélites atuarão como "Clientes OAuth". O fluxo normal para um utilizador final será o seguinte:

• O utilizador tenta aceder à aplicação (ex: Contagil).
• A aplicação redireciona-o para o ecrã de login seguro do ACAPADEV ID.
• O utilizador introduz o e-mail e a senha (ou utiliza login com conta Google). Se tiver o 2FA ativo, o desafio é processado pelo ACAPADEV ID.
• Novidade: O utilizador pode gerir múltiplas contas em simultâneo (estilo Google) e alternar entre identidades com um único clique no ecrã de autorização, sem necessidade de voltar a inserir a palavra-passe.
• Após o sucesso (ou seleção da conta), o utilizador é redirecionado de volta para o Contagil com um código de autorização na URL.
• Nos bastidores (Server-to-Server), o Contagil troca esse código por um Token e pelos dados do utilizador.
• O Contagil faz o login local do utilizador e permite-lhe usar o sistema.

Configuração do Agnosticismo de Ambiente

As suas aplicações devem respeitar o princípio do agnosticismo de ambiente. Nunca programe a URL do SSO diretamente no seu código. Em vez disso, a URL do Identity Provider deve ser sempre lida através de uma variável de ambiente.

// ❌ ERRADO
$url = 'https://id.acapadev.com/oauth/authorize';

// ✅ CORRETO
$url = env('SSO_HOST') . '/oauth/authorize';

No ficheiro .env da sua aplicação cliente, defina o alvo adequado:

• Ambiente Local: SSO_HOST=https://id.acapadev.com (ou a sua configuração local)
• Produção: SSO_HOST=https://id.acapadev.com

Criação e Gestão de Aplicações

Nesta arquitetura, existem dois grandes polos de criação de aplicações (Clientes OAuth):

1. Aplicações Internas ACAPADEV (Primeira Parte)

Se estás a desenvolver uma aplicação interna do ecossistema central, não precisas do portal público. Como Super-Administrador, podes aceder ao Painel de Administração (na aba Aplicações) e gerir os clientes de forma privilegiada, bypassando o isolamento comum aos outros developers.

2. Aplicações Externas (Developer Portal)

Para integrações de terceiros, construímos um Portal Público do Developer totalmente isolado. Os developers externos registam as suas próprias contas e criam aplicações geridas no seu espaço pessoal. O Portal suporta ambientes de TESTE e LIVE, permitindo ensaios seguros (com Soft Deletes programados) antes da passagem a produção real.

---

✨ Autenticação Invisível (One-Tap)

Destaque especial para a nossa tecnologia Acapadev One-Tap. O seu portal satélite não precisa de ter um redirecionamento agressivo de página inteira! Com o nosso SDK leve, pode injetar um elegante "Toast" no ecrã do seu utilizador, permitindo o login cruzado com apenas 1 clique.

A solução suporta inclusivé um Account Switcher dinâmico e inteligente para os utilizadores gerirem múltiplas identidades ativas em simultâneo (e.g. conta profissional vs pessoal).

👉 Descubra o guia completo de Integração One-Tap.