Single Sign-On

O Single Sign-On (SSO) autentica o operador em um provedor de identidade corporativo, cadastrado no cadastro da API (ssoProviders). O fluxo acontece no navegador, por redirecionamentos, e termina com um token Bearer entregue ao Riversoft Console Portal ou à sua aplicação.

Importante

Os retornos (/auth/api/v1/sso/saml2/acs e /auth/api/v1/sso/oauth2) são chamados pelo provedor de identidade durante o fluxo. A sua aplicação não deve simular essas chamadas.

    sequenceDiagram
    participant U as Navegador
    participant A as Riversoft STCP Gemini API
    participant P as Provedor de identidade
    U->>A: GET /auth/api/v1/sso/login?provider=<nome>
    A-->>U: 307 Redirecionamento ao provedor
    U->>P: Autenticação do operador
    P-->>U: Retorno com SAMLResponse (SAML 2.0) ou code (OAuth 2.0)
    U->>A: POST /saml2/acs ou GET /oauth2
    A-->>U: 303 para sso_login_redirect?token=...&token_type=Bearer&scope=...

Listar os provedores

GET /info/sso/providers lista os provedores habilitados, sem exigir token:

curl -s "$API_BASE/info/sso/providers"

[
  {"Name": "EntraID", "Type": "oauth2"},
  {"Name": "diretorio-corporativo", "Type": "ldap"}
]

Os provedores saml2 e oauth2 usam o fluxo desta página. Os provedores ldap usam o login com LDAP.

Iniciar o login

Abra no navegador a URL de login com o nome do provedor:

https://api.exemplo.com:33070/auth/api/v1/sso/login?provider=EntraID

A API responde 307 e encaminha o navegador ao provedor. Com um provedor inexistente ou de outro tipo, responde 400, em texto.

Retorno do provedor

Depois de autenticar o operador, o provedor devolve o navegador à API:

Protocolo	Retorno	Dados recebidos
SAML 2.0	`POST /auth/api/v1/sso/saml2/acs`	`SAMLResponse` e `RelayState`
OAuth 2.0 / OpenID Connect	`GET /auth/api/v1/sso/oauth2`	`code` e `state`

Cadastre no provedor o endereço de retorno informado em ssoRedirectUrlOrEndpoint, no cadastro do provedor (esquema SsoProvider da Especificação OpenAPI).

A API valida a resposta, identifica o operador pelo nome recebido do provedor e redireciona o navegador (303) para o endereço de sso_login_redirect, com o token na query string:

https://console.exemplo.com/?token=<access_token>&token_type=Bearer&scope=<permissões em JSON, codificadas em Base64>

Parâmetro	Descrição
`token`	Token de acesso, usado como Bearer nas chamadas seguintes.
`token_type`	Sempre `Bearer`.
`scope`	Permissões do operador, em JSON codificado em Base64.

Em caso de falha, o redirecionamento leva o parâmetro error, com o motivo.

Nota

O operador precisa existir na Riversoft STCP Gemini API com o mesmo nome recebido do provedor. No login por SSO, a 2FA da API não é aplicada: os fatores de autenticação são os exigidos pelo provedor de identidade.

Logout federado

O logout usa a rota comum, DELETE /disconnect/api/v3/logout. Com sso_logout_end_session habilitado, a resposta traz em redirect o endereço de logout do provedor; redirecione o navegador para ele.

No SAML 2.0, o provedor conclui o logout chamando POST /auth/api/v1/sso/saml2/slo, e a API redireciona o navegador (303) para o destino final.

Cuidado

O token chega na query string do redirecionamento. Leia-o assim que a página carregar, remova-o da URL e não o registre em logs.

Próximos passos

Password grant Sessão e logout