Descope Magic Link Auth

2025-05-08 21:25 UTC o4-mini-high Open in ChatGPT ↗

Here’s a complete recipe for adding email‐based magic‐link authentication to your Gradio app with Descope, gated by a whitelist of allowed emails.

Install dependencies

pip install descope gradio python-dotenv uvicorn fastapi

Configure environment
Create a .env file (or export in your shell) with at least:
```
DESCOPE_PROJECT_ID=<Your Descope Project ID>
BASE_URL=http://localhost:8000       # or your deployed URL
PORT=8000
```
You can find your Project ID on the Descope Console’s project page.

Set up your Python app
Below is a single script that:

Initializes the Descope SDK
Defines a whitelist of allowed emails
Exposes a Gradio‐powered login UI at /
Hosts a FastAPI endpoint at /verify-magic-link to complete authentication

import os
from dotenv import load_dotenv
from descope import DescopeClient, DeliveryMethod
import gradio as gr
from fastapi import FastAPI, Request
import uvicorn

# Load .env
load_dotenv()

# Initialize Descope client
descope_client = DescopeClient(project_id=os.getenv("DESCOPE_PROJECT_ID"))  # citeturn2view0

# Whitelist
ALLOWED_EMAILS = {
    "alice@example.com",
    "bob@example.com",
    # add more allowed emails here
}

# Gradio UI function: send magic link if allowed
def send_magic_link(email: str) -> str:
    if email not in ALLOWED_EMAILS:
        return "❌ This email is not on the allowed list."
    try:
        masked = descope_client.magiclink.sign_up_or_in(
            method=DeliveryMethod.EMAIL,
            login_id=email,
            uri=f"{os.getenv('BASE_URL')}/verify-magic-link"
        )  # citeturn3view0
        return f"✅ Magic link sent to {masked} (check your inbox)"
    except Exception as e:
        return f"❌ Error: {e}"

# Build Gradio interface
blocks = gr.Blocks()
with blocks:
    gr.Markdown("## 🔐 Login with Magic Link")
    email_box = gr.Textbox(label="Your email")
    send_btn   = gr.Button("Send Magic Link")
    status_out = gr.Textbox(label="Status")
    send_btn.click(send_magic_link, inputs=email_box, outputs=status_out)

# FastAPI app to host both Gradio and verify endpoint
app = FastAPI()
app.mount("/", blocks.server_app)

@app.get("/verify-magic-link")
async def verify_magic_link(t: str):
    """
    Descope will redirect users here with ?t=<token>.
    We verify the token and issue session tokens.
    """
    try:
        resp = descope_client.magiclink.verify(token=t)  # citeturn3view0
        # Extract JWTs
        session_jwt = resp["sessionToken"]["jwt"]
        refresh_jwt = resp["refreshToken"]["jwt"]
        return {
            "status": "success",
            "session_jwt": session_jwt,
            "refresh_jwt": refresh_jwt,
        }
    except Exception as e:
        return {"status": "error", "detail": str(e)}

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=int(os.getenv("PORT", 8000)))

How it works
- DescopeClient setup: reads your DESCOPE_PROJECT_ID and creates a client you’ll call against citeturn2view0.
- Magic‐link initiation: magiclink.sign_up_or_in(...) sends a one‐time link to the user’s email if they’re whitelisted citeturn3view0.
- Verification callback: when the user clicks the link, Descope redirects them to /verify-magic-link?t=<token>, where you call magiclink.verify(token) to mint actual session and refresh tokens citeturn3view0.
Next steps
- Store the returned JWTs in cookies or in your frontend for authenticated requests.
- Secure any downstream Gradio endpoints by checking session_jwt.
- In production, replace BASE_URL and tighten CORS/security as needed.

That’s it—your Gradio app now sends magic links only to allowed emails and completes login through Descope!

To persist the user’s session so they don’t have to click a magic link every time, you can set the Descope session JWT as an HTTP-only cookie in your FastAPI verify-magic-link endpoint, then read that cookie on subsequent requests to check authentication.

Here’s how to augment your existing app:

import os
from dotenv import load_dotenv
from descope import DescopeClient, DeliveryMethod
import gradio as gr
from fastapi import FastAPI, Request, Response, Depends, HTTPException
from fastapi.responses import RedirectResponse
import uvicorn

load_dotenv()
descope_client = DescopeClient(project_id=os.getenv("DESCOPE_PROJECT_ID"))

ALLOWED_EMAILS = {
    "alice@example.com",
    "bob@example.com",
}

# 1️⃣ Magic-link sender (same as before)
def send_magic_link(email: str) -> str:
    if email not in ALLOWED_EMAILS:
        return "❌ This email is not on the allowed list."
    try:
        masked = descope_client.magiclink.sign_up_or_in(
            method=DeliveryMethod.EMAIL,
            login_id=email,
            uri=f"{os.getenv('BASE_URL')}/verify-magic-link"
        )
        return f"✅ Magic link sent to {masked}"
    except Exception as e:
        return f"❌ Error: {e}"

# 2️⃣ Dependency to get current user from cookie
def get_current_user(request: Request):
    token = request.cookies.get("session_token")
    if not token:
        raise HTTPException(status_code=401, detail="Not authenticated")
    try:
        user_info = descope_client.tokens.verify_session(token)
        return user_info["loginId"]
    except Exception:
        # Invalid or expired token
        raise HTTPException(status_code=401, detail="Session expired")

# 3️⃣ Gradio UI, now gated on session
def gradio_app(user=Depends(get_current_user)):
    # If we get here, user is authenticated
    return gr.Markdown(f"👋 Logged in as **{user}**!")

blocks = gr.Blocks()
with blocks:
    gr.Markdown("## 🔐 Login with Magic Link")
    email_box = gr.Textbox(label="Your email")
    send_btn   = gr.Button("Send Magic Link")
    status_out = gr.Textbox(label="Status")
    send_btn.click(send_magic_link, inputs=email_box, outputs=status_out)

app = FastAPI()
# Mount the login UI at "/"
app.mount("/", blocks.server_app)

# 4️⃣ Verification endpoint: set cookie & redirect home
@app.get("/verify-magic-link")
async def verify_magic_link(t: str):
    try:
        resp = descope_client.magiclink.verify(token=t)
        session_jwt = resp["sessionToken"]["jwt"]
        # Set cookie and redirect back to root
        response = RedirectResponse(url="/")
        response.set_cookie(
            key="session_token",
            value=session_jwt,
            httponly=True,
            secure=True,
            samesite="lax",
            max_age=60 * 60 * 24  # 1 day, adjust as needed
        )
        return response
    except Exception as e:
        return {"status": "error", "detail": str(e)}

# 5️⃣ (Optional) A protected API route example
@app.get("/protected")
async def protected_endpoint(user_email=Depends(get_current_user)):
    return {"message": f"Hello {user_email}, this is protected!"}

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=int(os.getenv("PORT", 8000)))

What changed?

/verify-magic-link now uses FastAPI’s RedirectResponse to send the user back to / and sets an HTTP-only session_token cookie containing the Descope JWT.
A dependency get_current_user reads that cookie on every request, calls descope_client.tokens.verify_session(...) to ensure it’s still valid, and either returns the user’s email or throws a 401.
You can then gate any Gradio or FastAPI endpoint by declaring Depends(get_current_user). If the cookie is valid, they’ll see the app; otherwise they’ll be redirected or see an error.

With this in place, once a user clicks their magic link, the cookie keeps them logged in—no repeated emails needed. You can tweak max_age/expires or add a /logout endpoint that calls response.delete_cookie("session_token") when you need to invalidate the session.

Here’s how to pull your “allowed emails” dynamically from a Google Sheet at runtime, instead of hard-coding them:

1. Add Google Sheets API dependencies

pip install google-auth google-auth-httplib2 google-api-python-client

2. Service-account setup

In GCP, create a Service Account and grant it Editor (or at least Viewer) access to your target Sheet.
Download the JSON key and either:
- save it as google-credentials.json in your project root, or
- copy its contents into an env-var called GOOGLE_CREDS_JSON.
Share your Google Sheet with the service account’s email (found in the JSON under client_email).

Note your Sheet’s ID (the long string in its URL) and set it in your .env:

SHEET_ID=your_google_sheet_id_here
GOOGLE_CREDS_FILE=./google-credentials.json   # if you saved the file
#–– or, if using an env-var for the JSON itself:
# GOOGLE_CREDS_JSON='{"type": "...", … }'

3. Code changes

Below is the full app—only the parts in bold are new/changed:

import os
import json
from dotenv import load_dotenv
from descope import DescopeClient, DeliveryMethod
import gradio as gr
from fastapi import FastAPI, Request, Depends, HTTPException
from fastapi.responses import RedirectResponse
import uvicorn

# ─── NEW: Google Sheets imports ─────────────────────────────────────────────
from google.oauth2.service_account import Credentials
from googleapiclient.discovery import build
# ─────────────────────────────────────────────────────────────────────────────

load_dotenv()

# ─── DESCOPE SETUP ───────────────────────────────────────────────────────────
descope_client = DescopeClient(project_id=os.getenv("DESCOPE_PROJECT_ID"))
# ─────────────────────────────────────────────────────────────────────────────

# ─── NEW: Google Sheets client setup ────────────────────────────────────────
SCOPES = ["https://www.googleapis.com/auth/spreadsheets.readonly"]

if os.getenv("GOOGLE_CREDS_JSON"):
    creds_info = json.loads(os.getenv("GOOGLE_CREDS_JSON"))
    creds = Credentials.from_service_account_info(creds_info, scopes=SCOPES)
else:
    creds = Credentials.from_service_account_file(
        os.getenv("GOOGLE_CREDS_FILE"), scopes=SCOPES
    )

sheets = build("sheets", "v4", credentials=creds).spreadsheets()
SHEET_ID = os.getenv("SHEET_ID")

def get_allowed_emails():
    """
    Reads column A (skipping header) from the sheet and returns
    a set of normalized email addresses.
    """
    RANGE = "AllowedEmails!A2:A"  # adjust if your tab/range differs
    result = sheets.values().get(spreadsheetId=SHEET_ID, range=RANGE).execute()
    rows = result.get("values", [])
    return {row[0].strip().lower() for row in rows if row and row[0].strip()}
# ─────────────────────────────────────────────────────────────────────────────

# 1️⃣ Magic-link sender
def send_magic_link(email: str) -> str:
    email_norm = email.strip().lower()
    allowed = get_allowed_emails()
    if email_norm not in allowed:
        return "❌ This email is not on the allowed list."
    try:
        masked = descope_client.magiclink.sign_up_or_in(
            method=DeliveryMethod.EMAIL,
            login_id=email_norm,
            uri=f"{os.getenv('BASE_URL')}/verify-magic-link"
        )
        return f"✅ Magic link sent to {masked}"
    except Exception as e:
        return f"❌ Error: {e}"

# 2️⃣ Dependency to verify cookie
def get_current_user(request: Request):
    token = request.cookies.get("session_token")
    if not token:
        raise HTTPException(status_code=401, detail="Not authenticated")
    try:
        info = descope_client.tokens.verify_session(token)
        return info["loginId"]
    except Exception:
        raise HTTPException(status_code=401, detail="Session expired")

# 3️⃣ Gradio login UI
blocks = gr.Blocks()
with blocks:
    gr.Markdown("## 🔐 Login with Magic Link")
    email_box = gr.Textbox(label="Your email")
    send_btn   = gr.Button("Send Magic Link")
    status_out = gr.Textbox(label="Status")
    send_btn.click(send_magic_link, inputs=email_box, outputs=status_out)

app = FastAPI()
app.mount("/", blocks.server_app)

# 4️⃣ Set cookie on verification
@app.get("/verify-magic-link")
async def verify_magic_link(t: str):
    try:
        resp = descope_client.magiclink.verify(token=t)
        session_jwt = resp["sessionToken"]["jwt"]
        response = RedirectResponse(url="/")
        response.set_cookie(
            key="session_token",
            value=session_jwt,
            httponly=True,
            secure=True,
            samesite="lax",
            max_age=60*60*24
        )
        return response
    except Exception as e:
        return {"status": "error", "detail": str(e)}

# 5️⃣ Example protected endpoint
@app.get("/protected")
async def protected(user_email=Depends(get_current_user)):
    return {"message": f"Hello {user_email}, this is protected!"}

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=int(os.getenv("PORT", 8000)))

How it works

Google Sheets client
We build a readonly Sheets API client with a Service Account. You either point it at a file (GOOGLE_CREDS_FILE) or load the JSON straight from GOOGLE_CREDS_JSON.
get_allowed_emails()
Reads column A (from row 2 down) of the AllowedEmails sheet/tab, normalizes to lowercase, and returns a Python set.
send_magic_link
Calls get_allowed_emails() at runtime, so changes in your Sheet take effect immediately.
Cookie flow
Unchanged from before but now gated by a dynamically loaded whitelist.

With this in place, anytime you update your Google Sheet, newly added or removed emails will be reflected at once—no redeploy needed.

Absolutely—you can use a Google Apps Script “micro-service” to publish your allowed-emails sheet as a simple JSON endpoint, and then have your Python/Gradio app just fetch that at runtime instead of talking to the Sheets API directly.

1. Write & deploy the Apps Script

Open your Google Sheet.

Extensions → Apps Script, and in the editor replace Code.gs with:

/**
 * Publishes the "AllowedEmails" tab as JSON.
 */
function doGet(e) {
  const SHEET_ID = SpreadsheetApp.getActiveSpreadsheet().getId();
  const sheet = SpreadsheetApp.openById(SHEET_ID)
                    .getSheetByName('AllowedEmails');
  const rows = sheet.getRange('A2:A').getValues();  // skip header
  const emails = rows
    .flat()
    .map(e => e && e.toString().trim().toLowerCase())
    .filter(e => e);
  const payload = JSON.stringify({ emails });
  return ContentService
    .createTextOutput(payload)
    .setMimeType(ContentService.MimeType.JSON);
}

Deploy → New deployment → Web app
- Execute as: Me
- Who has access: Anyone (even anonymous)
- Click Deploy, and copy the Web app URL (it’ll look like https://script.google.com/macros/s/…/exec).

2. Simplify your Python code

Remove the Google-API client dependencies (google-auth, etc.)
Add the requests library (if you don’t have it):
Terminal window
```
pip install requests
```

In your app, replace get_allowed_emails() with a simple HTTP fetch:

import os
import requests
from descope import DescopeClient, DeliveryMethod
import gradio as gr
from fastapi import FastAPI, Request, Depends, HTTPException
from fastapi.responses import RedirectResponse
import uvicorn

DESCOPE_PROJECT_ID = os.getenv("DESCOPE_PROJECT_ID")
BASE_URL          = os.getenv("BASE_URL")
WHITELIST_URL     = os.getenv("WHITELIST_URL")
# e.g. "https://script.google.com/macros/s/ABCDEFG/exec"

descope = DescopeClient(project_id=DESCOPE_PROJECT_ID)

def get_allowed_emails():
    """Fetch the JSON whitelist from Apps Script."""
    res = requests.get(WHITELIST_URL, timeout=5)
    res.raise_for_status()
    data = res.json()
    return set(data.get("emails", []))

def send_magic_link(email: str) -> str:
    email_norm = email.strip().lower()
    if email_norm not in get_allowed_emails():
        return "❌ This email is not on the allowed list."
    try:
        masked = descope.magiclink.sign_up_or_in(
            method=DeliveryMethod.EMAIL,
            login_id=email_norm,
            uri=f"{BASE_URL}/verify-magic-link"
        )
        return f"✅ Magic link sent to {masked}"
    except Exception as e:
        return f"❌ Error: {e}"

def get_current_user(request: Request):
    token = request.cookies.get("session_token")
    if not token:
        raise HTTPException(401, "Not authenticated")
    try:
        info = descope.tokens.verify_session(token)
        return info["loginId"]
    except:
        raise HTTPException(401, "Session expired")

# Build the Gradio login UI
blocks = gr.Blocks()
with blocks:
    gr.Markdown("## 🔐 Login with Magic Link")
    email_box = gr.Textbox(label="Your email")
    send_btn   = gr.Button("Send Magic Link")
    status_out = gr.Textbox(label="Status")
    send_btn.click(send_magic_link, inputs=email_box, outputs=status_out)

app = FastAPI()
app.mount("/", blocks.server_app)

@app.get("/verify-magic-link")
async def verify_magic_link(t: str):
    try:
        r = descope.magiclink.verify(token=t)
        jwt = r["sessionToken"]["jwt"]
        resp = RedirectResponse("/")
        resp.set_cookie(
            "session_token", jwt,
            httponly=True, secure=True, samesite="lax",
            max_age=86400
        )
        return resp
    except Exception as e:
        return {"status": "error", "detail": str(e)}

@app.get("/protected")
async def protected(user_email=Depends(get_current_user)):
    return {"message": f"Hello {user_email}, this is protected!"}

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=int(os.getenv("PORT", 8000)))

Environment variables

DESCOPE_PROJECT_ID=…
BASE_URL=http://localhost:8000
WHITELIST_URL=https://script.google.com/macros/s/…/exec

Why this helps

Zero Sheets-API dependencies in your Python app.
Instant updates: changing the Sheet updates your whitelist immediately.
Lightweight: your app now just does an HTTP GET against a tiny JSON endpoint.

That’s it—your Gradio+Descope app now uses Google Apps Script as a drop-in whitelist service!