Login with SSO

SSO Provider URL API

When a user clicks a social login button, the application must first obtain the OAuth URL from the backend before redirecting the user. This ensures the backend can track and manage the authentication flow.

Overview

The SSO Provider URL endpoint returns the URL to redirect users to for OAuth authentication with their chosen provider. This is a prerequisite step before initiating any social/OAuth login flow.

---

Endpoint

POST /idp/v1/Authentication/GetSocialLogInEndPoint

---

Request

Headers

Header	Required	Description
Content-Type	Yes	Must be application/json
X-Blocks-Key	Yes	Project API key

Body

{
  "provider": "google",
  "audience": "https://<deployed-domain>/login",
  "sendAsResponse": true
}

Request Fields

Field	Type	Required	Description
provider	string	Yes	OAuth provider identifier (e.g., google, github, microsoft)
audience	string	Yes	The redirect URL configured for this project
sendAsResponse	boolean	Yes	Must be true to receive the URL in the response

---

Response

Success Response

{
  "providerUrl": "https://accounts.google.com/o/oauth2/v2/auth?scope=https://www.googleapis.com/auth/userinfo.email+https://www.googleapis.com/auth/userinfo.profile&state=STATTE_CODE&redirect_uri=REDIRECT_URI&client_id=CLIENT_ID_OF_PROVIDER&response_type=code&approval_prompt=auto&access_type=online",
  "isAResponse": true,
  "error": ""
}

Response Fields

Field	Type	Description
providerUrl	string	Full OAuth authorization URL to redirect the user to
isAResponse	boolean	Indicates URL was returned in response (always true)
error	string	Error message if request failed (empty string on success)

---

OAuth URL Structure

The returned providerUrl is a standard OAuth authorization URL with the following components:

https://accounts.google.com/o/oauth2/v2/auth?
  scope=https://www.googleapis.com/auth/userinfo.email+
         https://www.googleapis.com/auth/userinfo.profile&
  state=STATE_CODE&
  redirect_uri=REDIRECT_URI&
  client_id=CLIENT_ID_OF_PROVDER&
  response_type=code&
  approval_prompt=auto&
  access_type=online

URL Components

Component	Description
scope	Permissions requested from the OAuth provider
state	Random string for CSRF protection
redirect_uri	Where the OAuth provider redirects after authentication
client_id	OAuth application client ID
response_type	Always code (authorization code flow)
approval_prompt	auto means no forced consent prompt
access_type	online means no offline access

---

Complete SSO Flow

1. Application → POST /GetSocialLogInEndPoint
               ← { providerUrl: "https://accounts.google.com/..." }

2. User → Browser redirects to providerUrl (Google)
       ← User authenticates with Google

3. Google → Browser redirects to redirect_uri with ?code=XXX&state=XXX

4. Application → POST /Token (grant_type=social, code=XXX)
               ← { access_token, refresh_token }

---

Error Handling

Error Response

{
  "providerUrl": "",
  "isAResponse": false,
  "error": "Provider not configured"
}

Common Errors

Error	Cause
Provider not configured	Provider not in project's SSO configuration
Invalid audience	Redirect URL doesn't match configuration
Empty error	Request failed (check network)

---

State Parameter

The state parameter in the OAuth URL is a security measure:

1. Generated by backend - Ensures the state is cryptographically random
2. Included in callback - OAuth provider returns the same state
3. Validated by application - Ensures the callback is from the initiated request

Important: Always validate the state parameter in the callback matches what was originally sent.

---

Provider Values

Supported OAuth providers:

Provider	Value in Request	Provider Domain
Google	google	accounts.google.com
GitHub	github	github.com
Microsoft	microsoft	login.microsoftonline.com
LinkedIn	linkedin	linkedin.com
X (Twitter)	x	api.twitter.com

---

Redirect URI Parameter

The redirect_uri value must match the redirect URI configured in the backend. This is typically:

• Your application's login callback URL
• Format: https://<deployed-domain>/login

Using the correct red ensures that the OAuth application knows where to redirect after authentication

---

Security Considerations

URL Validation

Before redirecting, the application should:

1. Verify providerUrl is not empty
2. Verify error is empty
3. Verify URL starts with expected provider domain

State Validation

When receiving the OAuth callback:

1. Extract state from query parameters
2. Validate it matches the original state (if stored)
3. Reject if state is missing or doesn't match

Redirect URI Validation

The backend validates that:

• The redirect URI matches configured values
• The request comes from an allowed origin
• The client_id belongs to the project

---

Timing Considerations

URL Expiration

The OAuth authorization URL may have a limited validity period:

• Some providers expire authorization URLs after a few minutes
• Best practice: Redirect immediately after receiving the URL

Token Exchange

After user authentication:

• Authorization codes are typically short-lived
• Exchange them for tokens immediately
• Do not store or cache authorization codes

---

Example Implementation

Step 1: Get Provider URL

const response = await fetch("/idp/v1/Authentication/GetSocialLogInEndPoint", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Blocks-Key": "YOUR_PROJECT_KEY",
  },
  body: JSON.stringify({
    provider: "google",
    audience: "https://<deployed-domain>/login",
    sendAsResponse: true,
  }),
});

const data = await response.json();

if (data.error) {
  console.error("SSO error:", data.error);
  return;
}

// Redirect user to the OAuth provider
window.location.href = data.providerUrl;

Step 2: Handle Callback

// Extract parameters from callback URL
const params = new URLSearchParams(window.location.search);
const code = params.get("code");
const state = params.get("state");

// Exchange code for tokens
const tokenResponse = await fetch("/idp/v1/Authentication/Token", {
  method: "POST",
  headers: {
    "Content-Type": "application/x-www-form-urlencoded",
  },
  body: new URLSearchParams({
    grant_type: "social",
    code: code,
    state: state,
  }),
});

const tokens = await tokenResponse.json();
// tokens.access_token
// tokens.refresh_token

---

Summary

Aspect	Details
Endpoint	POST /idp/v1/Authentication/GetSocialLogInEndPoint
Purpose	Get OAuth authorization URL
Authentication	None (public endpoint)
Provider URL validity	Short-lived, redirect immediately
State validation	Required for security
Error handling	Check error field in response