Architettura di identità e accesso a difesa in profondità
Passinstance applica autenticazione multilivello, isolamento delle sessioni e limitazione crittografica degli ambiti delle chiavi per gli operatori della Dashboard (/settings/workspace/security), il Single Sign-On (SSO) aziendale tramite SAML 2.0, le integrazioni API server-to-server e i dispositivi scanner nei punti vendita.
Endpoint per la postura di sicurezza e la gestione degli accessi
I proprietari del workspace e gli amministratori della sicurezza configurano i criteri di autenticazione (/settings/workspace/security), gestiscono le chiavi API (/settings/workspace/developer/api-credentials) ed esportano i registri di controllo per la conformità (/settings/workspace/developer/audit-logs) tramite i seguenti endpoint montati:
| Percorso Endpoint | Metodo | Autenticazione | Descrizione | |||
|---|---|---|---|---|---|---|
/api/v1/customer/:customerId/security-settings | GET / PUT / POST / DELETE | Bearer | Legge, aggiorna (request payload), ripristina o rimuove i controlli dei criteri di sicurezza del workspace. | |||
/api/v1/auth/saml/admin/:customerId/idp | GET / PUT / DELETE | Bearer | Configura i metadati SAML Identity Provider, l'Entity ID e i certificati IdP X.509 (GET .../setup per la guida SP). | |||
/api/v1/auth/saml/:customerId/login | GET | Pubblico | Avvia il reindirizzamento SP-SSO (insieme a GET .../metadata, POST .../acs e GET /api/v1/auth/saml/resolve). | |||
/api/v1/organizations/current/workspaces/switch | POST | Bearer | Cambia il workspace tenant attivo e ruota i token di sessione per prevenire attacchi di replay cross-tenant. | |||
/api/v1/api-keys | GET / POST | Bearer | Elenca o genera chiavi API vincolate all'ambiente (pi_live_ in produzione, pi_test_ in sandbox). | |||
/api/v1/api-keys/:id/regenerate | POST | Bearer | Ruota in modo atomico il segreto di una chiave API preservandone l'UUID e gli ambiti configurati. | |||
/api/v1/api-keys/:id/deactivate | POST | Bearer | Sospende immediatamente una chiave API senza eliminare la telemetria storica di utilizzo. | |||
/api/v1/audit-log | GET | Bearer | Interroga gli eventi di audit amministrativi e di sicurezza immutabili del workspace (classificazioni fino a SecurityLevel: `LOW | MEDIUM | HIGH | CRITICAL`). |
/api/v1/audit-log/export.csv | GET | Bearer (audit:read-all) | Trasmette fino a 1000 righe di audit filtrate in formato text/csv per revisioni SOC 2 e di conformità. |
Configurazione delle impostazioni di sicurezza del workspace (request payload)
Gli amministratori possono imporre l'autenticazione a due fattori a livello di organizzazione, configurare i timeout per le sessioni inattive, bloccare i tentativi di accesso brute-force, richiedere la complessità delle password, disabilitare i certificati di firma demo e controllare la durata delle chiavi API tramite PUT /api/v1/customer/:customerId/security-settings:
{
"requireTwoFactor": true,
"enforceTwoFactorAuth": true,
"sessionTimeoutMinutes": 60,
"maxLoginAttempts": 5,
"lockoutDurationMinutes": 15,
"passwordMinLength": 12,
"passwordRequireUppercase": true,
"passwordRequireNumbers": true,
"passwordHistoryLength": 5,
"preventDemoCertificates": true,
"apiRateLimitPerMinute": 120,
"apiKeyExpirationDays": 180
}
Single Sign-On aziendale SAML 2.0 (SAML Identity Provider)
I workspace Enterprise possono federare gli accessi degli operatori con Okta, Microsoft Entra ID (Azure AD), Google Workspace o Ping Identity tramite SAML SSO API (/api/v1/auth/saml/:customerId/*) e SAML Admin API (/api/v1/auth/saml/admin/:customerId/*). Ogni record SAML Identity Provider associa direttamente al dominio del tenant un Entity ID dell'identity provider, un URL di accesso SSO e un certificato di firma X.509.
Ciclo di vita delle chiavi API con ambito limitato (API_KEY_SCOPE_VALUES e API_KEY_ENVIRONMENT_VALUES)
Passinstance applica l'isolamento degli ambienti (API_KEY_ENVIRONMENT_VALUES: 'live' | 'test') separando le credenziali di produzione (pi_live_...) dalle chiavi sandbox (pi_test_...). Durante la generazione di una chiave tramite POST /api/v1/api-keys, assegni ambiti con privilegi minimi da API_KEY_SCOPE_VALUES:
-
'passes'— Emette, aggiorna, annulla e ricerca le istanze di pass. -
'templates'— Legge gli schemi dei modelli, gli attributi e le meccaniche. -
'scans'— Esegue la convalida e i riscatti delle meccaniche. -
'webhooks'— Gestisce le sottoscrizioni webhook push e pull. -
'analytics'— Interroga le metriche e i report del workspace. -
'*'— Accesso amministrativo completo alle API per sviluppatori (predefinito sescopesviene omesso).
{
"name": "POS Checkout Integration — Production",
"environment": "live",
"scopes": ["passes", "scans"],
"expiresAt": "2027-05-15T00:00:00.000Z"
}
Importante: I segreti in chiaro delle chiavi API (
data.key) e i token di associazione dello scanner (key) vengono restituiti una sola volta al momento della creazione o della rotazione (POST /api/v1/api-keys/:id/regenerate). Conservi i segreti in un vault dedicato o in un gestore di segreti e non incorpori mai chiavipi_live_nei bundle del browser lato client o nei file binari delle applicazioni mobili.
Consulti i controlli di crittografia dell'infrastruttura e di conformità nel Centro sicurezza e fiducia.
