Single Sign-On

Single Sign-On (SSO) authenticates the operator at a corporate identity provider registered in the API registration (ssoProviders). The flow takes place in the browser, through redirects, and ends with a Bearer token delivered to the Riversoft Console Portal or to your application.

Important

The return routes (/auth/api/v1/sso/saml2/acs and /auth/api/v1/sso/oauth2) are called by the identity provider during the flow. Your application must not simulate these calls.

    sequenceDiagram
    participant U as Browser
    participant A as Riversoft STCP Gemini API
    participant P as Identity provider
    U->>A: GET /auth/api/v1/sso/login?provider=<name>
    A-->>U: 307 Redirect to the provider
    U->>P: Operator authentication
    P-->>U: Return with SAMLResponse (SAML 2.0) or code (OAuth 2.0)
    U->>A: POST /saml2/acs or GET /oauth2
    A-->>U: 303 to sso_login_redirect?token=...&token_type=Bearer&scope=...

List the providers

GET /info/sso/providers lists the enabled providers, without requiring a token:

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

[
  {"Name": "EntraID", "Type": "oauth2"},
  {"Name": "corporate-directory", "Type": "ldap"}
]

saml2 and oauth2 providers use the flow on this page. ldap providers use sign-in with LDAP.

Start the sign-in

Open the sign-in URL with the provider name in the browser:

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

The API responds 307 and sends the browser to the provider. With a nonexistent provider or one of another type, it responds 400, in text.

Provider return

After authenticating the operator, the provider sends the browser back to the API:

Protocol	Return	Data received
SAML 2.0	`POST /auth/api/v1/sso/saml2/acs`	`SAMLResponse` and `RelayState`
OAuth 2.0 / OpenID Connect	`GET /auth/api/v1/sso/oauth2`	`code` and `state`

Register at the provider the return address set in ssoRedirectUrlOrEndpoint, in the provider registration (SsoProvider schema in the OpenAPI specification).

The API validates the response, identifies the operator by the name received from the provider and redirects the browser (303) to the sso_login_redirect address, with the token in the query string:

https://console.example.com/?token=<access_token>&token_type=Bearer&scope=<permissions as JSON, Base64-encoded>

Parameter	Description
`token`	Access token, used as Bearer in the following calls.
`token_type`	Always `Bearer`.
`scope`	Operator permissions, as Base64-encoded JSON.

On failure, the redirect carries the error parameter, with the reason.

Note

The operator must exist in Riversoft STCP Gemini API with the same name received from the provider. In SSO sign-in, the API 2FA is not applied: the authentication factors are those required by the identity provider.

Federated logout

Logout uses the common route, DELETE /disconnect/api/v3/logout. With sso_logout_end_session enabled, the response returns in redirect the provider logout address; redirect the browser to it.

In SAML 2.0, the provider completes the logout by calling POST /auth/api/v1/sso/saml2/slo, and the API redirects the browser (303) to the final destination.

Caution

The token arrives in the redirect query string. Read it as soon as the page loads, remove it from the URL and do not write it to logs.

Next steps

Password grant Session and logout