Integrate EasyCLA sanctions checking with Sanctions Screening Service (SSS)

[mlehotskylf]

Context

EasyCLA currently sets is_sanctioned on the Organization record but has no real-time screening against sanctions watchlists. The Sanctions Screening Service (SSS) is a new centralized service that screens orgs against Descartes watchlists, caches results, and deduplicates across all LFX products.

EasyCLA is the first SSS consumer. The integration calls SSS at CCLA signing time and ECLA acknowledgement time to block sanctioned orgs.

SSS repo: linuxfoundation/lfx-sanctions-screening

SSS API

GET /api/v1/organizations/status
Authorization: Bearer <Auth0 M2M token>

Parameter	Required	Source in EasyCLA
domain	Yes	Organization Service → Link field (strip protocol)
org_name	Yes	company_name from companies table
sfdc_id	No	company_external_id (only when it starts with 001)
country	No	Organization Service address, if available

Response: { "status": "clean" | "flagged", "entity_id": "...", "source": "...", ... }

SSS handles all complexity (Clearbit dedup, SFDC cache, Descartes API calls) — EasyCLA just sends org details and gets back clean or flagged.

SSS Environment URLs

Env	SSS Base URL
Dev	https://sanctions-screening.dev.v2.cluster.linuxfound.info/api/v1
Staging	https://sanctions-screening.staging.v2.cluster.linuxfound.info/api/v1
Prod	https://sanctions-screening.lfx.linuxfoundation.org/api/v1

Auth0 M2M

EasyCLA authenticates to SSS using Auth0 client credentials flow. Tokens are valid for 24 hours and should be cached.

Env	Auth0 Domain	SSS Audience
Dev	linuxfoundation-dev.auth0.com	https://sanctions-screening.dev.v2.cluster.linuxfound.info/
Staging	linuxfoundation-staging.auth0.com	https://sanctions-screening.staging.v2.cluster.linuxfound.info/
Prod	linuxfoundation.auth0.com	https://sanctions-screening.lfx.linuxfoundation.org/

Prerequisite: EasyCLA's Auth0 M2M client needs a client_credentials grant to the SSS audience. This requires a PR in auth0-terraform — see #4986.

Enforcement points

1. CCLA signing — before DocuSign envelope is sent or before CCLA approval. Primary gate.
2. ECLA acknowledgement — when a contributor acknowledges under their company's CCLA. Catches orgs flagged after CCLA signing. SSS call is fast (~200ms cached).

Decision needed: SSS unavailability

When SSS returns 503 or times out during CCLA signing, what should EasyCLA do?

• Option A: Block signing (strict — no signing without screening, safest for compliance)
• Option B: Allow signing, flag for re-check (permissive — avoids blocking users)
• Option C: Retry once, then block (middle ground)

References

• SSS API spec: docs/api-specification.md in lfx-sanctions-screening
• SSS integration guide: docs/integration-guide.md in lfx-sanctions-screening
• Auth0 SSS setup: auth0-terraform PR Updated golang lib lockfile #260

Child tickets

• Auth0: Grant EasyCLA M2M client access to SSS audience #4986 — Auth0: Grant EasyCLA M2M client access to SSS audience (auth0-terraform)
• Implement SSS HTTP client with Auth0 M2M authentication #4987 — Implement SSS HTTP client with Auth0 M2M authentication
• Check sanctions status via SSS during CCLA signing and ECLA acknowledgement #4988 — Check sanctions status via SSS during CCLA signing and ECLA acknowledgement

Future work (not in scope)

• SSS → EasyCLA real-time status notifications: Instead of checking SSS at each enforcement point, SSS pushes status changes to EasyCLA when an org's status changes (via Descartes webhook). Possible approaches: NATS event, webhook callback, or SNS/SQS. This eliminates the staleness window and removes the need for SSS calls at ECLA time.
• Periodic re-screening of existing orgs
• Backfill v1 orgs that may lack domain in the Organization Service