API Applicazioni

Le applicazioni in Auris rappresentano app client o servizi che si integrano con la piattaforma IAM — web app, app mobile, server API, CLI e servizi machine-to-machine. Ogni applicazione ha un Client ID (sempre visibile) e opzionalmente un Client Secret (per client riservati). Auris supporta quattro tipi di applicazione: WEB, MOBILE, API e M2M.

Tutti gli endpoint in questa sezione richiedono il permesso manage:applications e l’header x-tenant.

CRUD Applicazioni

GET/api/applicationsRequires: manage:applications

Elenca tutte le applicazioni registrate nel tenant. Restituisce le informazioni di riepilogo per ciascuna applicazione incluso il tipo, il Client ID, gli URI di redirect consentiti e la data di creazione.

Parametri di query

Parametro	Tipo	Descrizione
`page`	integer	Numero di pagina (default: 1)
`limit`	integer	Elementi per pagina (default: 20)
`type`	`WEB` \| `MOBILE` \| `API` \| `M2M`	Filtra per tipo di applicazione
`search`	string	Cerca per nome applicazione

Risposta di successo


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "app_abc123",
        "name": "La Mia Web App",
        "type": "WEB",
        "clientId": "cid_abc123",
        "redirectUris": ["https://app.tuodominio.it/callback"],
        "allowedOrigins": ["https://app.tuodominio.it"],
        "createdAt": "2025-01-10T08:00:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 3, "totalPages": 1 }
  }
}

POST/api/applicationsRequires: manage:applications

Crea una nuova applicazione. Per i tipi WEB e MOBILE, devono essere forniti i redirectUris. Per il tipo M2M, i redirectUris non sono richiesti ma gli scope M2M devono essere configurati separatamente. Un clientSecret viene generato automaticamente e restituito solo nella risposta di creazione — conservalo in modo sicuro. Non può essere recuperato di nuovo; usa la rotazione dei secret per generarne uno nuovo.

Corpo della richiesta


{
  "name": "La Mia Dashboard",
  "type": "WEB",
  "redirectUris": [
    "https://app.tuodominio.it/callback",
    "http://localhost:3000/callback"
  ],
  "allowedOrigins": [
    "https://app.tuodominio.it",
    "http://localhost:3000"
  ]
}

Risposta di successo


{
  "ok": true,
  "data": {
    "id": "app_def456",
    "name": "La Mia Dashboard",
    "type": "WEB",
    "clientId": "cid_def456",
    "clientSecret": "cs_sk_...",
    "redirectUris": ["https://app.tuodominio.it/callback", "http://localhost:3000/callback"],
    "allowedOrigins": ["https://app.tuodominio.it", "http://localhost:3000"],
    "createdAt": "2025-02-18T12:00:00Z"
  }
}

Il clientSecret viene restituito una sola volta al momento della creazione. Salvalo immediatamente. Per i client pubblici (SPA browser e app mobile), non usare il clientSecret — usa invece PKCE.

Codici di errore

Codice	HTTP	Descrizione
`NAME_TAKEN`	409	Esiste già un’applicazione con questo nome
`VALIDATION_ERROR`	400	Formato URI di redirect non valido o campo obbligatorio mancante

GET/api/applications/[id]Requires: manage:applications

Ottieni i dettagli completi di una singola applicazione, inclusi tutti i campi di configurazione. Il clientSecret non viene mai restituito dopo la creazione — usa la rotazione per generarne uno nuovo.

Risposta di successo


{
  "ok": true,
  "data": {
    "id": "app_abc123",
    "name": "La Mia Web App",
    "type": "WEB",
    "clientId": "cid_abc123",
    "redirectUris": ["https://app.tuodominio.it/callback"],
    "allowedOrigins": ["https://app.tuodominio.it"],
    "enableDeviceFlow": false,
    "enableCiba": false,
    "enableDpop": false,
    "enableM2m": false,
    "createdAt": "2025-01-10T08:00:00Z",
    "updatedAt": "2025-02-01T15:30:00Z"
  }
}

PUT/api/applications/[id]Requires: manage:applications

Aggiorna la configurazione di un’applicazione. Tutti i campi sono opzionali — vengono aggiornati solo i campi forniti.

Corpo della richiesta


{
  "name": "La Mia Web App v2",
  "redirectUris": [
    "https://app.tuodominio.it/callback",
    "https://staging.tuodominio.it/callback"
  ],
  "allowedOrigins": [
    "https://app.tuodominio.it",
    "https://staging.tuodominio.it"
  ],
  "enableDeviceFlow": false
}

Risposta di successo


{
  "ok": true,
  "data": {
    "id": "app_abc123",
    "name": "La Mia Web App v2",
    "redirectUris": [
      "https://app.tuodominio.it/callback",
      "https://staging.tuodominio.it/callback"
    ]
  }
}

DELETE/api/applications/[id]Requires: manage:applications

Elimina un’applicazione. Questo revoca tutti i token attivi emessi per l’applicazione. Questa azione non può essere annullata.

Risposta di successo


{
  "ok": true,
  "data": { "deleted": true }
}

Rotazione Secret

PATCH/api/applications/[id]?action=rotate-secretRequires: manage:applications

Genera un nuovo client secret per l’applicazione, invalidando immediatamente quello precedente. Il nuovo secret viene restituito una volta sola. Tutte le integrazioni che utilizzano il vecchio secret devono essere aggiornate.

La rotazione del secret invalida immediatamente quello precedente. Tutti i token M2M attivi ottenuti con il vecchio secret continuano a funzionare fino alla loro scadenza, ma non è possibile ottenere nuovi token.

Richiesta: Nessun corpo richiesto.

Risposta di successo


{
  "ok": true,
  "data": {
    "clientId": "cid_abc123",
    "clientSecret": "cs_sk_new...",
    "rotatedAt": "2025-02-18T14:00:00Z"
  }
}

Claim JWT Personalizzati

I claim personalizzati consentono di iniettare dati aggiuntivi negli access token emessi da un’applicazione specifica. I claim vengono risolti al momento dell’emissione del token e incorporati nel payload JWT.

Tipi di Valore

Tipo	Descrizione	Esempio
`STATIC`	Valore stringa fisso	`"piano": "enterprise"`
`USER_ATTRIBUTE`	Valore dall’attributo del profilo utente	`"email": user.email`
`ROLE_BASED`	Valore che cambia in base ai ruoli dell’utente	`"tier": "admin"` se ruolo `admin`
`EXPRESSION`	Espressione personalizzata valutata a runtime	`user.roles.includes('admin') ? 'full' : 'read'`

I claim JWT riservati (sub, iss, aud, exp, iat, jti, type, email, roles) non possono essere sovrascritti da claim personalizzati.

GET/api/applications/[id]/custom-claimsRequires: manage:applications

Elenca tutti i claim personalizzati configurati per un’applicazione.

Risposta di successo


{
  "ok": true,
  "data": [
    {
      "id": "claim_abc",
      "claimKey": "piano",
      "valueType": "STATIC",
      "staticValue": "enterprise",
      "isActive": true
    },
    {
      "id": "claim_def",
      "claimKey": "orgId",
      "valueType": "USER_ATTRIBUTE",
      "userAttribute": "organizationId",
      "isActive": true
    }
  ]
}

POST/api/applications/[id]/custom-claimsRequires: manage:applications

Crea un nuovo claim personalizzato per un’applicazione.

Corpo della richiesta — Claim statico


{
  "claimKey": "piano",
  "valueType": "STATIC",
  "staticValue": "enterprise"
}

Corpo della richiesta — Claim attributo utente


{
  "claimKey": "reparto",
  "valueType": "USER_ATTRIBUTE",
  "userAttribute": "department"
}

Corpo della richiesta — Claim basato su ruolo


{
  "claimKey": "livelloAccesso",
  "valueType": "ROLE_BASED",
  "roleMapping": {
    "admin": "full",
    "editor": "write",
    "viewer": "read"
  }
}

Corpo della richiesta — Claim espressione


{
  "claimKey": "isPremium",
  "valueType": "EXPRESSION",
  "expression": "user.roles.includes('premium') || user.roles.includes('admin')"
}

Risposta di successo


{
  "ok": true,
  "data": {
    "id": "claim_ghi",
    "claimKey": "piano",
    "valueType": "STATIC",
    "staticValue": "enterprise",
    "isActive": true
  }
}

Codici di errore

Codice	HTTP	Descrizione
`CLAIM_KEY_RESERVED`	400	La chiave del claim è un campo JWT riservato
`CLAIM_KEY_TAKEN`	409	Esiste già un claim con questa chiave per questa applicazione

PATCH/api/applications/[id]/custom-claims/[claimId]Requires: manage:applications

Aggiorna un claim personalizzato. Supporta aggiornamenti parziali — vengono modificati solo i campi forniti.

Corpo della richiesta


{
  "staticValue": "professional",
  "isActive": false
}

Risposta di successo


{
  "ok": true,
  "data": {
    "id": "claim_abc",
    "claimKey": "piano",
    "valueType": "STATIC",
    "staticValue": "professional",
    "isActive": false
  }
}

DELETE/api/applications/[id]/custom-claims/[claimId]Requires: manage:applications

Elimina un claim personalizzato. Il claim non apparirà più nei token emessi dopo l’eliminazione.

Risposta di successo


{
  "ok": true,
  "data": { "deleted": true }
}

POST/api/applications/[id]/custom-claims/previewRequires: manage:applications

Anteprima di come verrebbero risolti i claim personalizzati per un utente specifico. Utile per testare la configurazione dei claim senza emettere un token reale.

Corpo della richiesta


{
  "userId": "usr_abc123"
}

Risposta di successo


{
  "ok": true,
  "data": {
    "userId": "usr_abc123",
    "resolvedClaims": {
      "piano": "enterprise",
      "reparto": "Ingegneria",
      "livelloAccesso": "write",
      "isPremium": false
    }
  }
}

Scope M2M

Gli scope M2M (Machine-to-Machine) definiscono cosa può fare un token client_credentials. Gli scope sono stringhe libere che il tuo resource server valida.

GET/api/applications/[id]/m2m-scopesRequires: manage:applications

Elenca gli scope M2M configurati per un’applicazione.

Risposta di successo


{
  "ok": true,
  "data": {
    "scopes": ["read:users", "manage:roles"],
    "allowedScopes": ["read:users", "manage:roles", "read:audit-logs"]
  }
}

scopes sono gli scope predefiniti emessi quando scope non è specificato nella richiesta del token. allowedScopes sono tutti gli scope che l’applicazione è autorizzata a richiedere.

POST/api/applications/[id]/m2m-scopesRequires: manage:applications

Configura gli scope M2M per un’applicazione. Sostituisce completamente la configurazione degli scope esistente.

Corpo della richiesta


{
  "scopes": ["read:users"],
  "allowedScopes": ["read:users", "read:audit-logs"]
}

Risposta di successo


{
  "ok": true,
  "data": {
    "scopes": ["read:users"],
    "allowedScopes": ["read:users", "read:audit-logs"]
  }
}

Dopo l’aggiornamento degli scope M2M, i token esistenti rimangono validi con i loro scope originali fino alla scadenza. Le nuove richieste di token utilizzeranno la configurazione degli scope aggiornata.

Pagine Correlate

OAuth 2.0 e OIDC — Standard di protocollo che le applicazioni implementano
Claim JWT Personalizzati — Configura claim per applicazione negli access token
Credenziali M2M Client — Autenticazione server-to-server per app M2M
Applicazioni — Gestisci le applicazioni dalla Console