Configuracao de Login OAuth / OIDC¶

Permita que seus clientes facam login na central de suporte usando o provedor de identidade da propria empresa (Keycloak, Azure AD, Auth0, Okta, etc.).

Como Funciona¶

Sistema Enterprise        AtendeAqui                   Provider OIDC
(sistema do cliente)      (central de suporte)         (Keycloak, etc.)
      |                        |                            |
      |-- clica "Suporte" ---->|                            |
      |                        | /perfil/login/{slug}/      |
      |                        |                            |
      |                        |-- redirect authorize_url ->|
      |                        |                            |
      |                        |                 usuario autoriza
      |                        |                            |
      |                        |<-- callback com code ------|
      |                        |  /perfil/callback/         |
      |                        |                            |
      |                        |-- troca code por token --->|
      |                        |<-- access_token -----------|
      |                        |                            |
      |                        |-- GET userinfo ----------->|
      |                        |<-- JSON do usuario --------|
      |                        |                            |
      |                        | cria/atualiza usuario      |
      |                        | cria/atualiza cliente      |
      |                        | faz login                  |
      |                        |                            |
      |<-- redirect dashboard -|                            |

1. O usuario esta logado no sistema enterprise (ex: ERP, portal interno)
2. Clica no botao "Central de Suporte", que aponta para a URL de Login do provedor no AtendeAqui
3. O AtendeAqui redireciona automaticamente para o provider OIDC (sem tela de login intermediaria)
4. Se o usuario ja esta autenticado no provider (SSO), o fluxo e transparente — ele nem percebe a autenticacao
5. O provider redireciona de volta para o AtendeAqui com um codigo de autorizacao
6. O AtendeAqui troca o codigo por um token, consulta o userinfo e faz login automaticamente
7. O usuario e redirecionado para o dashboard de cliente

Configurando o Provedor¶

Passo 1: Acessar Configuracoes¶

1. Acesse Painel > Configuracoes > Autenticacao
2. Clique em Novo Provedor OAuth

Passo 2: Preencher os Dados¶

Passo 3: Configurar o Provider OIDC¶

No seu provedor de identidade, configure um client (ou "application") com:

• Client ID: O mesmo valor informado no AtendeAqui
• Client Secret: O mesmo valor informado no AtendeAqui
• Redirect URI: A URI de redirecionamento exibida no AtendeAqui (ex: https://suaempresa.atendeaqui.com/perfil/callback/)
• Grant Type: authorization_code
• Response Type: code

Passo 4: Obter a URL de Login¶

Apos salvar o provedor, a URL de Login sera exibida na lista de provedores configurados (coluna "URL de Login"). Essa e a URL que o sistema enterprise do cliente deve usar.

Formato da URL:

https://{sua-org}.atendeaqui.com/perfil/login/{slug-do-provedor}/

Exemplo:

https://minhaempresa.atendeaqui.com/perfil/login/keycloak-corporativo/

Como compartilhar com o cliente enterprise:

1. Acesse Painel > Configuracoes > Provedores OAuth
2. Na lista, localize a coluna URL de Login (Provider)
3. Clique no botao Copiar ao lado da URL
4. Envie essa URL para o time de TI do cliente enterprise
5. O cliente deve usar essa URL no botao "Central de Suporte" (ou similar) do sistema deles

Passo 5: Testar¶

1. Abra a URL de login em uma janela anonima do navegador
2. Voce sera redirecionado ao provider OIDC
3. Faca login com um usuario de teste
4. Verifique se o usuario foi criado corretamente no painel do AtendeAqui
5. Teste tambem o fluxo completo: acesse a URL a partir do sistema enterprise do cliente

Formato do UserInfo¶

O endpoint userinfo do seu provider deve retornar um JSON com os seguintes campos:

Campos obrigatorios¶

{
  "sub": "user-unique-id-001",
  "email": "joao@empresa.com.br"
}

Campos opcionais do usuario¶

{
  "sub": "user-unique-id-001",
  "email": "joao@empresa.com.br",
  "email_verified": true,
  "name": "Joao da Silva",
  "given_name": "Joao",
  "family_name": "da Silva",
  "picture": "https://idp.empresa.com/avatar/001.jpg"
}

Claim customizado: organization (opcional)¶

Para associar automaticamente usuarios a uma empresa cliente, seu provider pode incluir o claim organization:

{
  "sub": "user-unique-id-001",
  "email": "joao@empresa.com.br",
  "name": "Joao da Silva",
  "given_name": "Joao",
  "family_name": "da Silva",
  "organization": {
    "id": "client-ext-001",
    "name": "Empresa ABC Ltda",
    "customer_since": "2024-01-15"
  }
}

Comportamento:

• Com organization.id: Usuarios com o mesmo ID sao agrupados no mesmo cliente. Exemplo: joao@empresa.com.br e maria@empresa.com.br com organization.id = "client-ext-001" ficam na mesma equipe.
• Sem organization: Cada usuario cria um registro de cliente individual. A associacao entre usuarios pode ser feita manualmente pelo painel.

Exemplos por Provider¶

Keycloak¶

URLs tipicas:

Autorizacao: https://keycloak.empresa.com/realms/{realm}/protocol/openid-connect/auth
Token:       https://keycloak.empresa.com/realms/{realm}/protocol/openid-connect/token
UserInfo:    https://keycloak.empresa.com/realms/{realm}/protocol/openid-connect/userinfo

Configurando o claim organization no Keycloak:

1. Acesse Clients > seu-client > Client Scopes > Dedicated Scope
2. Clique em Add mapper > By configuration > User Attribute
3. Crie mappers para cada campo:

1. Preencha os atributos org_id e org_name nos usuarios do Keycloak

Azure AD / Entra ID¶

URLs tipicas:

Autorizacao: https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize
Token:       https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
UserInfo:    https://graph.microsoft.com/oidc/userinfo

Auth0¶

URLs tipicas:

Autorizacao: https://{tenant}.auth0.com/authorize
Token:       https://{tenant}.auth0.com/oauth/token
UserInfo:    https://{tenant}.auth0.com/userinfo

Para incluir organization no Auth0, use uma Action no fluxo de login:

exports.onExecutePostLogin = async (event, api) => {
  api.idToken.setCustomClaim('organization', {
    id: event.user.app_metadata.org_id,
    name: event.user.app_metadata.org_name
  });
};

Okta¶

URLs tipicas:

Autorizacao: https://{org}.okta.com/oauth2/default/v1/authorize
Token:       https://{org}.okta.com/oauth2/default/v1/token
UserInfo:    https://{org}.okta.com/oauth2/default/v1/userinfo

Multiplos Provedores¶

Voce pode configurar mais de um provedor OAuth por organizacao. Exemplos de uso:

• Um provedor para funcionarios (Azure AD corporativo) e outro para clientes externos (Keycloak)
• Provedores diferentes para clientes de regioes distintas
• Migracao gradual de um provider para outro

Cada provedor aparece como um botao separado na pagina de login.

Seguranca¶

Boas Praticas¶

1. Use HTTPS em todas as URLs do provider
2. Mantenha o Client Secret seguro - nunca exponha em codigo frontend
3. Limite o Redirect URI no provider para aceitar apenas o dominio do AtendeAqui
4. Rotacione secrets periodicamente - atualize o Client Secret a cada 6-12 meses
5. Teste em ambiente de homologacao antes de ativar em producao

O que o AtendeAqui Protege¶

• Token state assinado: Previne ataques CSRF durante o fluxo OAuth
• Vinculo com sessao: O callback so e aceito pela mesma sessao que iniciou o fluxo
• Token de uso unico: Cada state token so pode ser usado uma vez
• Expiracao: Tokens state expiram apos 10 minutos

Troubleshooting¶

"Token de seguranca invalido"¶

• O fluxo demorou mais de 10 minutos. Tente novamente.
• O usuario abriu o login em outra aba. Use a mesma aba.

"Erro ao obter token de acesso"¶

• Verifique se o Client ID e Client Secret estao corretos
• Verifique se a URI de Redirecionamento no provider e identica a configurada no AtendeAqui
• Confirme que o provider esta acessivel na rede

"Erro ao obter informacoes do usuario"¶

• Verifique se a URL de Informacoes do Usuario (userinfo) esta correta
• Confirme que o token retornado pelo provider tem permissao para acessar o endpoint userinfo
• Verifique se os scopes openid, profile e email estao configurados no client do provider

Usuario criado mas nao associado ao cliente correto¶

• Verifique se o provider esta retornando o claim organization no userinfo
• Confirme que organization.id e consistente para todos os usuarios da mesma empresa
• Use o painel para associar usuarios manualmente se necessario

"Dados do usuario sao invalidos"¶

• O provider nao esta retornando o campo email ou sub
• Verifique a configuracao de scopes e claims no provider

Proximos Passos¶

• Setores e Controle de Acessos
• Configuracoes do Sistema

Precisa de ajuda? Entre em contato com nosso suporte para auxiliar na configuracao do seu provedor OAuth.