Creare un client usando la Vantage API

Crea e configura un client Vantage API a livello di codice: invia richieste POST all’API di amministrazione per creare client e gestirne i client secret.

Crea client API a livello di codice quando devi automatizzare il provisioning, ad esempio nell’ambito dell’infrastruttura come codice o quando integri più app su larga scala.

Prima di creare un client, autenticati nella Vantage API. Per maggiori dettagli, vedi Authentication.

​

Creazione di un client

Invia una richiesta POST con l’header Authorization: Bearer <access token> a {baseUrl}/api/adminapi2/v2/tenants/{tenantId}/clients/ con i seguenti parametri nel corpo della richiesta HTTP:

Parameter	Description
clientId	L’identificatore del client.
clientName	Il nome del client (ad esempio, il nome della tua app).
allowOfflineAccess	Indica se viene generato un token di aggiornamento insieme al token di accesso. L’applicazione può usare il token di aggiornamento per rinnovare il token di accesso senza intervento dell’utente. Predefinito: false.
allowRememberConsent	Indica se l’utente può scegliere di salvare le decisioni di consenso. Predefinito: true.
backChannelLogoutSessionRequired	Indica se il meccanismo di Backchannel Logout è obbligatorio. Predefinito: true.
requireClientSecret	Indica se è richiesto un client secret. Predefinito: true.
requireConsent	Indica se è richiesta una schermata di consenso. Predefinito: false.
allowNoPkce	Indica se è consentito l’Authorization Code Flow senza Proof Key for Code Exchange (PKCE). Predefinito: false, il che significa che è consentito solo l’Authorization Code Flow con PKCE.
allowedGrantTypes	I tipi di grant che il client può usare.
allowedCorsOrigins	Indica se viene usato il meccanismo CORS (Cross-Origin Resource Sharing) predefinito.
allowedScopes	Gli scope trasferiti nel token. Deve essere un array che contenga esattamente "openid", "permissions" e "publicapi.all".
postLogoutRedirectUris	Un elenco di URI consentiti a cui reindirizzare dopo il logout.
redirectUris	Un elenco di URL di siti web o app consentiti per i reindirizzamenti del token di autorizzazione. I prefissi sono consentiti: se un prefisso corrisponde, è consentito qualsiasi URL che vi rientri. Ad esempio: ["https://myDomain.", "https://myApp.myDomain.com/oauth-signin.html"].
accessTokenLifetime	Il periodo di tempo durante il quale un token di accesso emesso consente l’accesso a Vantage. Predefinito: 24 ore.
refreshTokenLifetime	Il periodo di tempo assoluto, a partire dall’emissione del primo token di accesso, durante il quale il token di aggiornamento può essere usato per rinnovare il token di accesso. Predefinito: 30 giorni.

Quando esegui l’autenticazione usando Resource Owner Password Credentials (ROPC), imposta allowRopc su true. ROPC richiede che l’utente invii le proprie credenziali direttamente all’applicazione, quindi usalo solo per client riservati attendibili.

​

Richiesta di esempio

Linux o macOS

curl --location --request POST '{baseUrl}/api/adminapi2/v2/tenants/{tenantId}/clients/' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "clientId": "{clientId}",
    "clientName": "{clientName}",
    "allowOfflineAccess": true,
    "allowRememberConsent": true,
    "backChannelLogoutSessionRequired": true,
    "requireClientSecret": true,
    "requireConsent": false,
    "allowNoPkce": true,
    "allowedGrantTypes": ["{allowedGrantTypes}"],
    "allowedCorsOrigins": ["{allowedCorsOrigins}"],
    "allowedScopes": ["openid", "permissions", "publicapi.all"],
    "postLogoutRedirectUris": ["{postLogoutRedirectUris}"],
    "redirectUris": ["{redirectUris}"]
  }'

Windows (cmd)

curl --location --request POST "{baseUrl}/api/adminapi2/v2/tenants/{tenantId}/clients/" ^
  -H "accept: application/json" ^
  -H "Authorization: Bearer {token}" ^
  -H "Content-Type: application/json" ^
  -d "{\"clientId\":\"{clientId}\",\"clientName\":\"{clientName}\",\"allowOfflineAccess\":true,\"allowRememberConsent\":true,\"backChannelLogoutSessionRequired\":true,\"requireClientSecret\":true,\"requireConsent\":false,\"allowNoPkce\":true,\"allowedGrantTypes\":[\"{allowedGrantTypes}\"],\"allowedCorsOrigins\":[\"{allowedCorsOrigins}\"],\"allowedScopes\":[\"openid\",\"permissions\",\"publicapi.all\"],\"postLogoutRedirectUris\":[\"{postLogoutRedirectUris}\"],\"redirectUris\":[\"{redirectUris}\"]}"

La risposta contiene la descrizione del client creato.

​

Creazione di un secret

Ogni client può avere più secret. Questo consente al client di iniziare a utilizzare un nuovo secret quando quello corrente scade, senza eliminare quello precedente. Per impostazione predefinita, un client secret scade dopo sei mesi.

Invia una richiesta POST con l’header Authorization: Bearer <access token> a {baseUrl}/api/adminapi2/v2/tenants/{tenantId}/clients/{clientId}/secrets/ con i seguenti parametri nel corpo della richiesta HTTP:

Parameter	Description
description	Una breve descrizione per aiutarti a distinguere i diversi secret. Facoltativo.
startTime	La data di inizio del secret.
expiration	La data di scadenza del secret (tra 1 giorno e 3 anni). Ad esempio, 2021-09-07T13:03:38.380Z. Per impostazione predefinita, è impostata esattamente a sei mesi dalla data di creazione del secret.

​

Richiesta di esempio

Linux o macOS

curl --location --request POST '{baseUrl}/api/adminapi2/v2/tenants/{tenantId}/clients/{clientId}/secrets/' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json-patch+json' \
  -d '{
    "description": "{description}",
    "startTime": "{startTime}",
    "expiration": "{expiration}"
  }'

Windows (cmd)

curl --location --request POST "{baseUrl}/api/adminapi2/v2/tenants/{tenantId}/clients/{clientId}/secrets/" ^
  -H "accept: application/json" ^
  -H "Authorization: Bearer {token}" ^
  -H "Content-Type: application/json-patch+json" ^
  -d "{\"description\":\"{description}\",\"startTime\":\"{startTime}\",\"expiration\":\"{expiration}\"}"

La risposta contiene il client secret (value) e il relativo periodo di validità (startTime, expiration).

Il valore del client secret è disponibile solo al momento della creazione. Conservalo in un luogo sicuro: successivamente potrai visualizzare solo i primi tre caratteri del valore (valueDisplay).