Single Sign-On

O Single Sign-On (SSO) autentica o usuário em um provedor de identidade corporativo habilitado no ambiente. O fluxo acontece no navegador, por redirecionamentos e cookies.

O provedor é identificado pelo nome cadastrado pelo administrador do serviço (parâmetro provider).

OAuth 2.0, OAuth 2.1 e OpenID Connect

No login com OAuth 2.0 e OpenID Connect, a API usa PKCE (S256) e um state de uso único, como exige o OAuth 2.1.

    sequenceDiagram
    participant U as Navegador
    participant A as Riversoft STCP DirectLink API
    participant P as Provedor de identidade
    U->>A: GET /sso/login?provider=<nome>
    A-->>U: Redirecionamento ao provedor
    U->>P: Autenticação do usuário
    P-->>U: Redirecionamento com state e code
    U->>A: GET ou POST /sso/oauth2/cb
    A-->>U: Sessão estabelecida (cookie de sessão)
  

Iniciar o login

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

https://api.exemplo.com/directlink/v2/sso/login?provider=provedor-corporativo

Para inspecionar o redirecionamento:

curl -i --get \
  --data-urlencode 'provider=provedor-corporativo' \
  "$API_BASE/sso/login"

Callback de autorização

Depois de autenticar o usuário, o provedor redireciona o navegador para GET ou POST /sso/oauth2/cb com state e code. O state precisa corresponder ao criado no início do fluxo; não invente nem reutilize esses valores.

# Formato ilustrativo; em um login real, a chamada é feita pelo redirecionamento do provedor.
curl -i --get \
  --data-urlencode 'state=<estado-fornecido-no-fluxo>' \
  --data-urlencode 'code=<codigo-de-autorizacao>' \
  "$API_BASE/sso/oauth2/cb"

Logout federado

O logout começa em GET /sso/logout, com o provider e a sessão autenticada. A API encaminha o navegador ao provedor ou ao destino de logout:

curl -i -b cookies.txt -c cookies.txt --get \
  --data-urlencode 'provider=provedor-corporativo' \
  "$API_BASE/sso/logout"

O provedor conclui o logout chamando GET ou POST /sso/oauth2/logout/cb com state e provider:

# Formato ilustrativo.
curl -i --get \
  --data-urlencode 'state=<estado-fornecido-no-fluxo>' \
  --data-urlencode 'provider=provedor-corporativo' \
  "$API_BASE/sso/oauth2/logout/cb"

SAML 2.0

    sequenceDiagram
    participant U as Navegador
    participant A as Riversoft STCP DirectLink API
    participant P as Provedor SAML
    U->>A: GET /sso/login?provider=<nome>
    A-->>U: Redirecionamento ao provedor
    U->>P: Autenticação do usuário
    P-->>U: Formulário com SAMLResponse
    U->>A: POST /sso/saml2/acs
    A-->>U: Sessão estabelecida (cookie de sessão)
  

Obter os metadados

Para cadastrar a API no provedor SAML, obtenha os metadados XML do provedor configurado. Informe o provedor na query string ou no caminho:

curl -i --get \
  --data-urlencode 'provider=provedor-saml' \
  "$API_BASE/sso/saml2/metadata"

curl -i "$API_BASE/sso/saml2/metadata/provedor-saml"

Login

O login SAML começa em GET /sso/login?provider=provedor-saml. Depois da autenticação, o provedor envia um formulário HTTP POST para /sso/saml2/acs com SAMLResponse e, quando aplicável, RelayState:

# Formato ilustrativo; use apenas em testes com valores de um fluxo SAML válido.
curl -i -X POST "$API_BASE/sso/saml2/acs" \
  --data-urlencode 'SAMLResponse=<resposta-saml-base64>' \
  --data-urlencode 'RelayState=<estado-opcional>'

Logout

O logout SAML usa o mesmo início (GET /sso/logout?provider=provedor-saml). O provedor envia a resposta de logout para /sso/saml2/slo, por GET ou POST:

# Formato ilustrativo.
curl -i -X POST "$API_BASE/sso/saml2/slo" \
  --data-urlencode 'SAMLResponse=<resposta-logout-saml-base64>' \
  --data-urlencode 'RelayState=<estado-opcional>'

Referência

Contratos completos em Referência: Single Sign-On.