Registrazione dinamica dei client
Consentire alle applicazioni client di registrarsi autonomamente tramite OAuth 2.0 Dynamic Client Registration, con Initial Access Token.
Nota: disponibile con gli abbonamenti Advanced e Pro. La registrazione aperta per agenti AI richiede Pro.
Con la registrazione dinamica dei client, un'applicazione client si registra autonomamente invece di essere creata manualmente nella console di amministrazione. Invia i propri metadati (nome, URI di reindirizzamento, autenticazione del client) all'endpoint di registrazione e riceve in cambio un client ID e, per i client confidenziali, un client secret. La piattaforma implementa OAuth 2.0 Dynamic Client Registration (RFC 7591) e il protocollo di gestione che consente al client di leggere, aggiornare ed eliminare in seguito la propria registrazione (RFC 7592).
Per impostazione predefinita, ogni registrazione richiede un Initial Access Token emesso da Lei, così da decidere chi può registrare client e con quale frequenza. Per gli agenti AI e altri client pubblici è inoltre possibile consentire la registrazione aperta.
Gli Initial Access Token si gestiscono in Integrazioni → Applicazioni → Registrazioni dinamiche nella console di amministrazione.
Funzionamento
- Lei emette un Initial Access Token e lo consegna a chi registra il client, ad esempio un partner o una pipeline di deployment.
- Il client invia una richiesta di registrazione all'endpoint di registrazione, con l'Initial Access Token come Bearer token.
- La piattaforma verifica i metadati rispetto alle regole riportate sotto, crea l'applicazione e risponde con le credenziali del client, un Registration Access Token e l'URL di gestione del client stesso.
- Con il Registration Access Token, il client può leggere, aggiornare o eliminare la propria registrazione. Ogni aggiornamento emette un nuovo Registration Access Token e invalida quello precedente.
Il client registrato è elencato nella scheda Registrazioni dinamiche in Applicazioni registrate, insieme al modo in cui si è registrato e a quando è stato utilizzato l'ultima volta. La sua pagina di dettaglio è la stessa di qualsiasi altra applicazione, contrassegnata come Registrata dinamicamente. Nessuno può ancora accedervi: come per ogni nuova applicazione, l'accesso deve prima essere assegnato.
Emettere un Initial Access Token
- Vada in Integrazioni → Applicazioni e apra la scheda Registrazioni dinamiche.
- Selezioni Emetti token.
- Inserisca un Nome, ad esempio il partner o il sistema a cui è destinato il token. Compare nell'elenco e nell'audit log.
- Imposti la Validità in giorni (da 1 a 365). Il token scade al termine di questo periodo.
- Lasci selezionato Monouso se il token deve consentire esattamente una registrazione. Lo deselezioni per consentire un numero qualsiasi di registrazioni fino alla scadenza del token.
- Selezioni Emetti token e copi il token. Viene mostrato una sola volta e non può essere recuperato in seguito.
La pagina mostra anche l'Endpoint di registrazione da comunicare insieme al token. È pubblicato anche come registration_endpoint nel documento di discovery OpenID Connect.
L'elenco mostra per ogni token l'utilizzo, il numero di registrazioni effettuate, la scadenza e chi lo ha emesso. Revoca impedisce che un token venga utilizzato per nuove registrazioni. Le applicazioni già registrate con esso non ne sono influenzate. I token scaduti vengono rimossi automaticamente.
Registrazione aperta per agenti AI
Nota: disponibile con l'abbonamento Pro.
Gli agenti AI, ad esempio i client del Model Context Protocol (MCP), e gli strumenti da riga di comando si registrano autonomamente nel momento in cui un utente li collega, senza che nessuno distribuisca un token. Ogni installazione registra in genere il proprio client. La registrazione aperta consente esattamente questo per i client pubblici, che non hanno un client secret e fanno accedere gli utenti con l'Authorization Code Flow e PKCE.
- Vada in Impostazioni → Avanzate.
- Nella scheda Registrazione aperta, attivi Registrazione aperta per client pubblici.
- In Utenti autorizzati ad accedere, selezioni le directory i cui utenti possono utilizzare tali client.
- Selezioni Salva modifiche.
Per i client registrati in modo aperto:
- Sono accettati solo client pubblici. Una registrazione senza Initial Access Token deve inviare
"token_endpoint_auth_method": "none"e il client resta pubblico: un aggiornamento successivo non può aggiungere un client secret. I client confidenziali richiedono comunque un Initial Access Token. - L'accesso deriva dalle directory. Gli utenti delle directory selezionate possono accedere dopo aver dato il consenso, senza un'assegnazione per singola applicazione. La selezione si applica alle nuove registrazioni; le applicazioni già registrate mantengono le directory con cui sono state registrate.
- Le registrazioni sono soggette a limiti di frequenza: 10 all'ora per indirizzo IP del client e 200 all'ora in totale (20 durante il periodo di prova).
- Le registrazioni inutilizzate vengono rimosse. Un client a cui nessuno ha effettuato l'accesso viene eliminato dopo 24 ore, così come un client senza accessi né richieste di token per 90 giorni. Ogni rimozione viene registrata nell'audit log.
- Non c'è un proprietario. Le applicazioni registrate in modo aperto non sono assegnate ad alcun amministratore.
L'endpoint di registrazione è annunciato nel documento di discovery, disponibile in /.well-known/openid-configuration e, per i client OAuth che lo cercano lì, in /.well-known/oauth-authorization-server. Se un agente richiede un access token per una risorsa specifica, come un server MCP, registri tale risorsa come API.
Disattivando la registrazione aperta si interrompono le nuove registrazioni anonime. I client già registrati continuano a funzionare e possono ancora gestire la propria registrazione. Senza l'abbonamento Pro, gli utenti delle directory non ottengono più automaticamente l'accesso ai client registrati in modo aperto: li assegni esplicitamente, altrimenti i client inutilizzati vengono rimossi dopo 90 giorni.
Registrare un client
Il client invia i propri metadati come richiesta JSON POST:
curl -X POST https://id.example.com/oidc/register \
-H "Authorization: Bearer <initial access token>" \
-H "Content-Type: application/json" \
-d '{
"client_name": "Partner Portal",
"redirect_uris": ["https://portal.partner.example/callback"],
"post_logout_redirect_uris": ["https://portal.partner.example/"],
"grant_types": ["authorization_code", "refresh_token"],
"token_endpoint_auth_method": "client_secret_basic"
}'Una registrazione riuscita risponde con 201 Created:
{
"client_id": "V1StGXR8_Z5jdHi6B-myT",
"client_secret": "...",
"client_name": "Partner Portal",
"redirect_uris": ["https://portal.partner.example/callback"],
"grant_types": ["authorization_code", "refresh_token"],
"response_types": ["code"],
"token_endpoint_auth_method": "client_secret_basic",
"registration_client_uri": "https://id.example.com/oidc/register/V1StGXR8_Z5jdHi6B-myT",
"registration_access_token": "..."
}Il client conserva in modo sicuro client_secret e registration_access_token. Nessuno dei due può essere recuperato di nuovo.
Gestire la registrazione
Il client gestisce la propria registrazione in registration_client_uri, autenticandosi con il Registration Access Token attuale:
| Richiesta | Effetto |
|---|---|
GET | Restituisce la registrazione attuale. |
PUT | Sostituisce la registrazione con i metadati inviati. Il corpo deve contenere client_id; un campo omesso viene rimosso. La risposta contiene un nuovo Registration Access Token. |
DELETE | Elimina l'applicazione. I suoi utenti non possono più accedervi. |
Un amministratore può modificare o eliminare un'applicazione registrata dinamicamente nella console di amministrazione come qualsiasi altra. Tenga presente che il successivo PUT del client sovrascrive i campi di cui è titolare (nome, URI di reindirizzamento, grant type, autenticazione del client, URI del client e chiavi del client). Assegnazioni, criteri, proprietari e impostazione del consenso restano come impostati dall'amministratore.
Cosa può essere un client registrato
| Metadati | Regola |
|---|---|
token_endpoint_auth_method | client_secret_basic (predefinito), client_secret_post, private_key_jwt o none. |
| Tipo di applicazione | Derivato dall'autenticazione del client: none crea una single-page application, oppure un'applicazione nativa quando viene inviato "application_type": "native" o quando ogni URI di reindirizzamento è un indirizzo di loopback (http://127.0.0.1, http://[::1], http://localhost) o uno schema specifico dell'app. Un reindirizzamento di loopback nativo corrisponde su qualsiasi porta. Ogni altro metodo crea un'applicazione web. Un client nativo deve usare none. |
grant_types | Deve contenere authorization_code, può aggiungere refresh_token. I grant implicit, client credentials, device e token exchange vengono rifiutati. |
response_types | Solo code. |
redirect_uris, post_logout_redirect_uris | Nessun carattere jolly, nessun URI sul dominio proprio dell'Identity Provider. |
client_uri | Deve usare https. |
jwks | Solo chiavi pubbliche, RSA con almeno 2048 bit o EC sulla curva P-256. Necessario per private_key_jwt. |
jwks_uri, sector_identifier_uri, backchannel_logout_uri, request_uris | Rifiutati, perché la piattaforma dovrebbe chiamare autonomamente questi URL. Un amministratore può impostare le opzioni corrispondenti sull'applicazione in seguito. |
client_name | Facoltativo. Senza nome l'applicazione si chiama "Dynamic client" seguito dal suo client ID. A un nome già in uso viene aggiunta una parte del client ID. |
default_max_age | Accettato. |
Qualsiasi altro metadato viene ignorato e non fa parte della risposta.
Alcune impostazioni sono sempre decise dalla piattaforma, indipendentemente dal contenuto della richiesta:
- Richiedi il consenso dell'utente è attivato. Gli utenti confermano l'accesso richiesto al primo accesso e i refresh token vengono emessi solo quando il client richiede lo scope
offline_access. - Non viene applicato alcun profilo di sicurezza. Un amministratore può impostarne uno in seguito, vedere Sicurezza Financial-grade API.
- L'applicazione non è elencata nel portale delle applicazioni degli utenti.
- L'amministratore che ha emesso l'Initial Access Token diventa il proprietario dell'applicazione. Le applicazioni registrate in modo aperto non hanno proprietario.
Le registrazioni rientrano nel limite di applicazioni del Suo abbonamento.
Audit log
| Evento | Registrato quando |
|---|---|
INITIAL_ACCESS_TOKEN_CREATED | Un amministratore emette un Initial Access Token. |
INITIAL_ACCESS_TOKEN_REVOKED | Un amministratore revoca un Initial Access Token. |
CONFIGURATION_UPDATED | Un amministratore attiva o disattiva la registrazione aperta o ne modifica le directory. |
APPLICATION_REGISTERED | Un client si registra. Il client che si registra viene registrato come attore. |
APPLICATION_UPDATED | Un client aggiorna la propria registrazione. |
APPLICATION_DEREGISTERED | Un client elimina la propria registrazione, un amministratore elimina l'applicazione oppure viene rimossa una registrazione aperta inutilizzata. |
L'elenco completo è disponibile in Tipi di evento di audit.
Risoluzione dei problemi
invalid_tokendurante la registrazione: l'Initial Access Token è sconosciuto, scaduto, revocato oppure un token monouso è già stato utilizzato. Ne emetta uno nuovo. Senza token, la registrazione aperta è disattivata.429su una registrazione anonima: è stato raggiunto il limite di frequenza della registrazione aperta. Riprovi più tardi.invalid_tokenin lettura, aggiornamento o eliminazione: il Registration Access Token è stato sostituito da uno più recente all'ultimo aggiornamento, oppure l'applicazione è stata eliminata.invalid_client_metadatacon "dynamic client registration is not available": l'abbonamento non include la funzionalità. Registrazioni e aggiornamenti vengono rifiutati; la lettura e l'eliminazione di una registrazione esistente continuano a funzionare.invalid_client_metadata: i metadati violano una delle regole sopra indicate. L'error_descriptionindica il campo. Una richiesta rifiutata non consuma un token monouso.- Gli utenti non riescono ad accedere dopo la registrazione: l'applicazione non ha ancora assegnazioni. Assegni utenti, gruppi o directory nella scheda Assegnazioni dell'applicazione. Per un client registrato in modo aperto, verifichi che l'utente appartenga a una delle sue directory.