Contas conectadas

Agentes e APIs muitas vezes precisam agir em outro serviço como o usuário: abrir uma issue no GitHub, ler um arquivo no Google Drive. As contas conectadas guardam esse acesso no Authio. O usuário conecta a conta uma vez, o Authio guarda e renova os tokens dela, e o seu servidor de recurso troca o token que recebeu do usuário pelo access token do serviço externo sempre que precisar. O refresh token do serviço externo nunca sai do Authio.

Um provedor de conexão é o app OAuth que o seu realm registra no serviço externo. Cada realm usa o próprio app, então o que os usuários de um realm autorizam nunca alcança outro.

Como funciona

1. 1

   Você registra um provedor de conexão

   O app OAuth que você criou no GitHub, no Google ou em outro serviço, registrado no realm.

2. 2

   O usuário conecta a conta dele

   Nas telas hospedadas do Authio, já logado na sua aplicação, o usuário autoriza o serviço. O Authio guarda os tokens cifrados.

3. 3

   O seu servidor de recurso troca o token do usuário

   Quando o usuário chama a sua API ou o seu servidor MCP, ele apresenta o access token que recebeu ao endpoint de token do Authio, numa requisição de token exchange.

4. 4

   O Authio devolve o access token do provedor

   Renovado antes, se estiver para vencer. O seu servidor chama o serviço com ele, em nome do usuário.

Registre um provedor de conexão

1. 1

   Crie o app no provedor

   No serviço externo, crie um app OAuth e cadastre nele esta URL de callback (redirect):

   URL de callbackTexto simples

   https://authio.api.hyperio.tech/realms/acme/connections/callback

2. 2

   Registre-o no Authio

   Abra Conexões externas, escolha Nova conexão externa, selecione o tipo e preencha os dados do app:

   Campo	Regras
   Alias	De 2 a 64 letras minúsculas, dígitos e hífens, como google-drive. Único no realm e fixo depois de criado, porque os links de conexão e as requisições de troca o usam.
   Nome de exibição	Até 128 caracteres, mostrado aos usuários.
   Client ID e segredo	Os do app que você criou. O segredo é guardado cifrado e nunca mais é mostrado.
   Escopos	O que uma conexão pede ao serviço. Em branco, valem os escopos padrão do tipo. Separe-os com espaços; vírgulas também são aceitas.
   Servidores de recurso autorizados	Os servidores de recurso que podem trocar tokens deste provedor. Vazio quer dizer todos os servidores de recurso do realm, inclusive os criados depois.

3. 3

   Mantenha-o ativo

   Só um provedor ativo aceita novas conexões e trocas. Desativar um provedor mantém as contas já conectadas por ele.

Tipos de provedor

Deixe os usuários conectarem as contas

A conexão acontece nas telas hospedadas do Authio, para um usuário logado no realm pelo seu client. Mande-o para um destes dois endereços em https://authio.api.hyperio.tech:

• Sem uma sessão do realm e do client, o usuário cai numa página de erro que pede para entrar primeiro.
• O fluxo usa PKCE (S256) com todo provedor que o aceita, e um state de uso único válido por 15 minutos.
• Na volta do provedor, a página de destino recebe connected=google-drive em caso de sucesso, ou connection_error=ConnectionDenied quando o usuário recusou.
• Reconectar a mesma conta externa renova os tokens dela e a coloca de novo em vigor. A primeira conta conectada de um provedor vira a padrão.

Obtenha o token do serviço externo

Só um servidor de recurso pode fazer a troca. Quem chama se autentica como o cliente de introspecção de um servidor de recurso ativo — um client confidencial com o grant Token Exchange habilitado — e o access token do usuário precisa estar endereçado (aud) a um dos servidores de recurso dele.

curl -X POST https://authio.api.hyperio.tech/realms/acme/protocol/openid-connect/token \
  -u "acme-api:YOUR_CLIENT_SECRET" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  -d "subject_token=$USER_ACCESS_TOKEN" \
  -d "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
  -d "requested_token_type=urn:authio:params:oauth:token-type:connection-access-token" \
  -d "connection_provider=google-drive"

• Envie connection_id para escolher uma conexão quando o usuário tem várias. Sem ele, o Authio usa a conexão padrão, ou a única ativa.
• Um token que vence em até 60 segundos é renovado com o provedor antes de ser devolvido, e requisições simultâneas nunca gastam o mesmo refresh token duas vezes.
• expires_in fica de fora quando o token do provedor não expira. O refresh token do provedor nunca faz parte da resposta.

Quando não há token para devolver

Os erros vêm no formato OAuth, com error_code e, quando ajudam, connect_uri, connection_provider e connections:

{
  "error": "connection_required",
  "error_code": "ConnectionRequired",
  "connection_provider": "google-drive",
  "connect_uri": "https://authio.api.hyperio.tech/realms/acme/clients/acme-web/connections/google-drive/connect"
}

Organizações e políticas de conexão

Toda conexão é feita para um contexto: o próprio usuário ou uma das organizações dele. Um token com org_id só alcança conexões feitas para aquela organização; um token sem ele só alcança as pessoais.

Cada organização pode definir políticas de conexão na aba Pessoas, dizendo quais contas externas aceita:

• Domínios de e-mail permitidos, com comparação exata: acme.com não aceita br.acme.com. Contas Google são conferidas pelo domínio do Workspace, então uma conta @gmail.com é recusada.
• Organizações do GitHub permitidas, para provedores do GitHub: a conta precisa ser membro ativo de uma delas.
• A política própria de um provedor substitui a política geral da organização; as duas nunca se somam.
• Com Exigir contexto da organização desligado, um token da organização pode recorrer à conta pessoal do usuário naquele provedor, desde que a política a aceite.

As políticas são aplicadas quando a conta é conectada e de novo a cada troca. Uma conexão que deixa de atender à política é marcada como violação de política e fica inutilizável até o usuário conectar uma conta aceita — afrouxar a política depois não a traz de volta.

Desconectar e revogar

• O usuário desconecta uma conta na página de contas conectadas dele. O Authio pede ao provedor que revogue os tokens, até onde cada provedor permite, e apaga a conexão.
• Administradores revogam a conexão de um usuário na aba Credenciais do usuário, em Usuários. Os tokens são descartados e a conexão continua listada como revogada até o usuário conectar a mesma conta de novo.
• Excluir um provedor revoga e apaga todas as conexões feitas por ele.

Notas de segurança

• Access e refresh tokens ficam cifrados em repouso. A API administrativa nunca os devolve; ela mostra datas, escopos concedidos e a conta externa.
• Só o cliente de introspecção de um servidor de recurso pode fazer a troca, e só com um token de usuário endereçado a um dos servidores dele.
• Restrinja cada provedor aos servidores de recurso que precisam dele: uma lista vazia quer dizer todos.
• Cada conexão guarda a própria trilha — conectada, usada, renovada, falha na renovação, desconectada, revogada, violação de política — na aba Acesso do provedor, e toda troca, entregue ou recusada, fica no log de acesso como token exchange.

Próximos passos