Single Sign-On

Single Sign-On (SSO) authenticates the user with a corporate identity provider enabled in the environment. The flow takes place in the browser, through redirects and cookies.

The provider is identified by the name registered by the service administrator (provider parameter).

OAuth 2.0, OAuth 2.1 and OpenID Connect

In sign-in with OAuth 2.0 and OpenID Connect, the API uses PKCE (S256) and a single-use state, as OAuth 2.1 requires.

    sequenceDiagram
    participant U as Browser
    participant A as Riversoft STCP DirectLink API
    participant P as Identity provider
    U->>A: GET /sso/login?provider=<name>
    A-->>U: Redirect to the provider
    U->>P: User authentication
    P-->>U: Redirect with state and code
    U->>A: GET or POST /sso/oauth2/cb
    A-->>U: Session established (session cookie)
  

Start the login

Open the login URL with the provider name in the browser:

https://api.example.com/directlink/v2/sso/login?provider=corporate-provider

To inspect the redirect:

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

Authorization callback

After it authenticates the user, the provider redirects the browser to GET or POST /sso/oauth2/cb with state and code. The state must match the one created at the start of the flow; do not make up or reuse these values.

# Illustrative format; in a real login, the provider redirect makes this call.
curl -i --get \
  --data-urlencode 'state=<state-provided-in-the-flow>' \
  --data-urlencode 'code=<authorization-code>' \
  "$API_BASE/sso/oauth2/cb"

Federated logout

Logout starts at GET /sso/logout, with the provider and the authenticated session. The API forwards the browser to the provider or to the logout destination:

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

The provider completes the logout by calling GET or POST /sso/oauth2/logout/cb with state and provider:

# Illustrative format.
curl -i --get \
  --data-urlencode 'state=<state-provided-in-the-flow>' \
  --data-urlencode 'provider=corporate-provider' \
  "$API_BASE/sso/oauth2/logout/cb"

SAML 2.0

    sequenceDiagram
    participant U as Browser
    participant A as Riversoft STCP DirectLink API
    participant P as SAML provider
    U->>A: GET /sso/login?provider=<name>
    A-->>U: Redirect to the provider
    U->>P: User authentication
    P-->>U: Form with SAMLResponse
    U->>A: POST /sso/saml2/acs
    A-->>U: Session established (session cookie)
  

Get the metadata

To register the API with the SAML provider, get the XML metadata of the configured provider. Specify the provider in the query string or in the path:

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

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

Login

SAML login starts at GET /sso/login?provider=saml-provider. After authentication, the provider sends an HTTP POST form to /sso/saml2/acs with SAMLResponse and, when applicable, RelayState:

# Illustrative format; use it only in tests with values from a valid SAML flow.
curl -i -X POST "$API_BASE/sso/saml2/acs" \
  --data-urlencode 'SAMLResponse=<saml-response-base64>' \
  --data-urlencode 'RelayState=<optional-state>'

Logout

SAML logout uses the same starting point (GET /sso/logout?provider=saml-provider). The provider sends the logout response to /sso/saml2/slo, through GET or POST:

# Illustrative format.
curl -i -X POST "$API_BASE/sso/saml2/slo" \
  --data-urlencode 'SAMLResponse=<saml-logout-response-base64>' \
  --data-urlencode 'RelayState=<optional-state>'

Reference

Full contracts in Reference: Single Sign-On.