Single Sign-On

Introduction

SCAYLE's Authentication API offers a unified OAuth 2.0 interface for connecting external Identity Providers (IdPs) using a secure redirect-based flow. This allows tenants to support logins from providers like Google, Facebook, Microsoft, etc., without custom integrations.

Indentiy Provider

Our Authentication API offers a single, consistent interface that makes connecting to a wide range of OAuth 2.0-compliant Identity Provider like Google, Facebook, Microsoft, and many others straightforward. Some Identity Provider are available out of the box and only need to be configured. Others are available, but need to be requested through your SCAYLE Account Manager.

Available

These following Identity Provider are available out of the box and are configurable the SCAYLE’s Panel.

Requestable

The following identity providers can be added by SCAYLE upon request. To learn more about extending SCAYLE’s Identity Provider Service, please contact your SCAYLE Account Manager.

How it works

User Flow

When a user clicks "Login with SSO" on the Shop site, they are redirected to SCAYLE’s Authentication API, which then forwards them to an external Identity Provider for authentication. Once the user successfully logs in, they are redirected back to the Shop using a predefined callback URL. At this point, the Shop receives an Authorization Code, which it can exchange for access and refresh tokens to authenticate and manage the user session.

Token Management

Token Life Time

Access token TTLs are centrally managed by SCAYLE and automatically synchronized with the expiration of the external Identity Provider's tokens.

Any invalid TTL configuration is rejected with a clear HTTP 401 error. If your application needs to access the external IdP token directly (e.g., for downstream API calls), you can retrieve it securely via SCAYLE’s get-token endpoint.

Refresh Token

When a new access_token is required, the application can send a POST request to the token endpoint /oauth/token using the refresh_token grant type. The system will then provide a new pair of access token and refresh token.

Revoke Token

SCAYLE provides flexible options for invalidating access tokens issued by Identity Providers (IdPs), supporting both internal and external revocation flows. The behavior is configurable per IDP through flags exposed in the SCAYLE Panel.

For Identity Providers without redirect functionality, SCAYLE enables automatic token revocation on logout.

For Identity Providers with redirect functionality, SCAYLE supports manual token revocation via redirection to a predefined URL.

Custom Parameter in Redirect URL

When using OIDC login via external identity providers (e.g., Auth0), SCAYLE supports passing custom parameters to control aspects such as token audience and login page localization.

This is achieved by adding key-value pairs to the JWT field authUrlParameters. These parameters are automatically appended as query strings to the final redirect URL sent to the IDP.

Scope of authUrlParameters

• ✅ Optional: can be omitted entirely
• ✅ Flexible: supports multiple key-value pairs
• ✅ Resilient: can be null or undefined without errors
• ✅ only attach the query parameter when some data are available

Example: JWT Payload

json

Copy

Resulting Redirect URL

bash

Copy

Error handling

Error handling in the authentication flow depends on whether the Identity Provider (IDP) follows the OAuth 2.0 / OpenID Connect (OIDC) standard for error propagation

Limitations

PKCE

Overview

PKCE (Proof Key for Code Exchange) adds an optional but strong security layer to the OAuth 2.1 Authorization Code flow by requiring a dynamically generated secret (code_verifier) from the client when exchanging the authorization code for a token.

At SCAYLE, PKCE validation is triggered automatically if code_challenge and code_challenge_method are provided as part of the JWT in the initial redirect request. No additional configuration or OAuth client changes are required to utilize PKCE.

The implementation follows the specifications of RFC 7636.

PKCE Flow

Validation & Errors

Validation

RFC 7636 defines two methods to derive a code_challenge from a code_verifier:

Best Practice: Always use S256.

Errors