Pular para o conteúdo principal

SSO (Single Sign-On)

Introdução​

A funcionalidade SSO (Single Sign-On - Login Único) permite que sistemas externos gerem tokens de acesso para login direto de usuários na plataforma ProExtend sem necessidade de credenciais.

Casos de Uso​

Portais Institucionais
Adicione links diretos de acesso ao ProExtend no portal da sua instituição.

Convites e E-mails
Envie links de acesso temporário para novos usuários ou ações específicas.

Suporte Técnico
Gere acessos temporários para equipes de suporte realizarem manutenções.

Sistemas Integrados
Conecte sistemas acadêmicos ao ProExtend de forma simples.

Fluxo de Autenticação​

O processo de autenticação SSO segue os seguintes passos:

1. Sistema Externo solicita geração de token
   ↓
2. Sistema Externo → API ProExtend
   POST /integration/v1/sso/generate-token
   {
     "user_code": "PROF001",
     "expires_in": 86400,
     "single_use": false
   }
   ↓
3. API ProExtend valida usuário e gera token
   ↓
4. API ProExtend → Sistema Externo
   {
     "login_url": "https://{{instituicao}}.proextend.com.br/login?token=abc123..."
   }
   ↓
5. Sistema Externo redireciona usuário para login_url
   ↓
6. Usuário é autenticado automaticamente no ProExtend
   ↓
7. Usuário acessa plataforma ProExtend sem digitar credenciais

Gerar Token SSO​

Endpoint​

POST /integration/v1/sso/generate-token

Parâmetros​

IMPORTANTE

O usuário pode ser identificado por email (e-mail) ou code (código). É obrigatório fornecer pelo menos um dos dois campos.

CampoTipoObrigatórioDescrição
user_emailstringCondicionalE-mail do usuário (obrigatório se user_code não fornecido)
user_codestringCondicionalCódigo do usuário (obrigatório se user_email não fornecido)
expires_inintegerNãoTempo de expiração em segundos - padrão: 86400 (24 horas)
single_usebooleanNãoToken de uso único - padrão: false (reutilizável)

expires_in (Tempo de Expiração)​

Define por quanto tempo o token SSO permanecerá válido.

REUTILIZAÇÃO DE LINKS

Quando single_use é false, o link completo gerado (exemplo: https://instituicao.proextend.com.br/login?token=TbbVa3x8KlMnPqRsUvWxYz...) pode ser cadastrado em portais e acessado múltiplas vezes durante todo o período definido em expires_in.

Por exemplo, um token com expires_in: 15552000 (180 dias) permite que o link seja utilizado quantas vezes for necessário por até 6 meses. Ideal para links permanentes em portais institucionais onde usuários acessam recorrentemente.

  • Mínimo: 60 segundos (1 minuto)
  • Máximo: 31536000 segundos (365 dias)
  • Padrão: 86400 segundos (24 horas)

Valores comuns:

  • 15 minutos (900): Acesso temporário urgente
  • 1 hora (3600): Suporte técnico
  • 24 horas (86400): Acesso padrão
  • 7 dias (604800): Convites de primeiro acesso
  • 30 dias (2592000): Acesso de longa duração
  • 90 dias (7776000): Acesso de longa duração
  • 180 dias (15552000): Portal institucional ou período semestral

single_use (Uso Único)​

Define se o token pode ser usado apenas uma vez ou múltiplas vezes.

  • true: Token é invalidado automaticamente após primeiro uso (ideal para links em e-mails, convites, acessos sensíveis)
  • false: Token permanece válido até expirar - padrão (ideal para portais institucionais, acessos recorrentes)
SEGURANÇA

Para links enviados por e-mail ou convites de primeiro acesso, sempre use single_use: true. Isso garante que o token não possa ser reutilizado caso seja interceptado ou compartilhado indevidamente.

Exemplo de Requisição​

{
  "user_code": "PROF001",
  "expires_in": 604800,
  "single_use": false
}

Resposta de Sucesso​

{
  "success": true,
  "message": "Token SSO gerado com sucesso.",
  "data": {
    "login_url": "https://{{instituicao}}.proextend.com.br/login?token=TbbVa3x8KlMnPqRsUvWxYz...",
    "user": {
      "name": "Dr. João Silva",
      "profile_type": "professor"
    }
  }
}

Revogar Token SSO​

Revoga tokens SSO de um usuário específico.

AUTO-REVOGAÇÃO

Ao gerar um novo token SSO para um usuário, todos os tokens anteriores deste usuário são automaticamente revogados. Isso garante que apenas um token esteja ativo por vez, aumentando a segurança.

Endpoint​

POST /integration/v1/sso/revoke-token

Parâmetros​

CampoTipoObrigatórioDescrição
user_emailstringCondicionalE-mail do usuário (obrigatório se user_code não fornecido)
user_codestringCondicionalCódigo do usuário (obrigatório se user_email não fornecido)
revoke_allbooleanNãotrue = revoga todos tokens ativos (padrão) / false = revoga apenas expirados

Exemplo de Requisição​

{
  "user_code": "PROF001",
  "revoke_all": true
}

Resposta de Sucesso​

{
  "success": true,
  "message": "Todos os tokens do usuário foram revogados.",
  "data": {
    "revoked_count": 3,
    "user": {
      "name": "Dr. João Silva",
      "email": "professor@faculdade.edu.br",
      "profile_type": "professor"
    }
  }
}

Casos de Uso Práticos​

1. Portal Institucional​

Link permanente no portal da instituição.

Configuração:

{
  "user_code": "PROF001",
  "expires_in": 15552000,
  "single_use": false
}

Características:

  • Expira em 180 dias (1 semestre)
  • Token reutilizável
  • Ideal para acesso recorrente

2. E-mail de Convite​

Link temporário para primeiro acesso.

Configuração:

{
  "user_email": "novoprofessor@faculdade.edu.br",
  "expires_in": 604800,
  "single_use": true
}

Características:

  • Expira em 7 dias
  • Uso único
  • Ideal para novos usuários

3. Acesso Temporário​

Acesso para manutenção ou suporte.

Configuração:

{
  "user_code": "ADMIN001",
  "expires_in": 900,
  "single_use": true
}

Características:

  • Expira em 15 minutos
  • Uso único
  • Ideal para suporte técnico

Tratamento de Erros​

Usuário Não Encontrado​

{
  "success": false,
  "message": "Dados inválidos.",
  "errors": {
    "user_code": ["Usuário não encontrado com o código fornecido."]
  }
}

Usuário Suspenso​

{
  "success": false,
  "message": "Dados inválidos.",
  "errors": {
    "user_code": ["O usuário está suspenso e não pode gerar token SSO."]
  }
}
VALIDAÇÃO

Apenas usuários ativos podem gerar tokens SSO. Usuários suspensos (suspended_at não nulo) não podem autenticar via SSO até que a suspensão seja removida.

Parâmetro Inválido​

{
  "success": false,
  "message": "Dados inválidos.",
  "errors": {
    "expires_in": ["O tempo de expiração deve estar entre 60 e 31536000 segundos."]
  }
}

Identificador Ausente​

{
  "success": false,
  "message": "Dados inválidos.",
  "errors": {
    "user_email": ["O e-mail ou código do usuário é obrigatório."]
  }
}

Boas Práticas de Segurança​

Tempos de Expiração​

Utilize tempos de expiração adequados ao contexto de uso:

Curtos (15min-1h)
Para acessos sensíveis e suporte técnico.

Médios (1-7 dias)
Para convites e primeiro acesso.

Longos (30-180 dias)
Para portais institucionais ou períodos semestrais.

Tokens de Uso Único​

Prefira single_use: true para links enviados por e-mail.

Limite de Validade​

Evite tokens com validade superior a 180 dias.