Guida ai casi d'uso dell'API di gestione delle applicazioni v2023-11-30

Versione API: 2023-11-30

Cos'è l'API Gestione delle applicazioni?

L'API Gestione delle applicazioni per i partner di vendita consente di ruotare il segreto client a livello di programmazione nelle applicazioni registrate.

È necessario registrare una coda Amazon Simple Queue Service (Amazon SQS) per ricevere le credenziali prima di chiamare rotateApplicationClientSecret Funzionamento API. Quando si effettua la chiamata API, viene creato un nuovo segreto client per l'applicazione che si sta chiamando. La nuova credenziale viene inviata alla coda SQS preregistrata insieme alla data di scadenza delle vecchie credenziali. È necessario aggiornare l'applicazione per utilizzare la nuova credenziale prima della scadenza della vecchia credenziale.

🚧

Concedi ad Amazon le autorizzazioni per scrivere nella coda SQS

Be sure to follow the steps in Grant Selling Partner API permission to write to your SQS queue so Amazon can send notifications to your SQS queue.

Terminologia

• ID client: parte delle credenziali Accedi con Amazon (LWA). Per ottenere questo valore, consulta Visualizzazione delle informazioni e delle credenziali dell'applicazione.
• Segreto del cliente: Parte delle tue credenziali LWA. Per ottenere questo valore, consulta Visualizzazione delle informazioni e delle credenziali della tua candidatura.
• Rotazione delle credenziali: il processo di creazione di un nuovo segreto client e di invalidazione di quello precedente.

Tutorial: notifica di rotazione delle credenziali

Scopri come impostare una notifica che ti avvisa quando è necessario ruotare le credenziali.

Prerequisiti:

Per completare con successo questo tutorial, devi avere accesso a:

• La Console per gli sviluppatori
• Amazon SQS
• Una coda SQS

Passaggio 1. Concedere all'API per i partner di vendita l'autorizzazione per scrivere nella coda SQS

Per ricevere notifiche, devi concedere a Selling Partner API l'autorizzazione a scrivere nella tua coda SQS.

1. Apri la console di gestione AWS e accedi con le tue credenziali AWS.
2. Dalla console, apri Amazon Simple Queue Service.
3. Seleziona la coda standard in cui desideri ricevere le notifiche.
4. Choose the Access Policy tab.
5. From the Access policy (Permissions) section, select Edit. The Edit Test Queue page opens.
6. Scroll down to Access policy, then select the Policy generator link. The AWS Policy Generator opens in a new tab.
7. In Step 1 of the policy generator, select SQS Queue Policy.
8. In Step 2 of the policy generator:
   a. Set Effect to Allow.
   b. Set Principal to 437568002678.
   c. Set Actions to SendMessage and GetQueueAttributes.
   d. Enter the SQS ARN value in Amazon Resource Name (ARN).
   e. Choose Add Statement and verify the details.
9. In Step 3 of the policy generator, select Generate Policy. A dialog box with the new policy opens.
10. Copia la policy.
11. Navigate back to the Amazon SQS queue, open the Access policy tab, then paste the policy into the Access Policy (Permissions) section.
12. Salva le modifiche.
13. Reference the queue's Details section and note the ARN for this queue, as you need it to register your queue in the next step.

Passaggio 1. Registrare la coda SQS per ricevere la notifica delle credenziali in scadenza

1. Sign in to your developer account on the Solution Provider Portal. Navigate to the Developer Console page that lists all your applications.

   📘

   Nota

   Per Seller Central utenti, accedi a Seller Central per il tuo marketplace e vai a Apps and Services, quindi Develop Apps.

   Per Vendor Central utenti, accedi a Vendor Central per il tuo marketplace e vai a Integration, quindi API Integration.

2. Seleziona Notification Preferences.

3. On the Subscription page, find the application for which you want to receive expiring credential notifications.

4. In the Application Client Secret Expiry row, select the SQS ARN where you want to receive the expiring credential notification.

Fase 3 Ascolta le credenziali in scadenza

Amazon invierà una notifica alla coda registrata quando l'applicazione si avvicina alla scadenza delle credenziali LWA. Rimani in ascolto della coda SQS e ruota le credenziali quando ricevi la notifica.

Usa un client Amazon SQS per ricevere il messaggio dalla tua coda preregistrata. Segui il ReceiveMessage documentazione.

Esempio di notifica

{
  "notificationVersion":"1.0",
  "notificationType":"APPLICATION_OAUTH_CLIENT_SECRET_EXPIRY",
  "payloadVersion":"2023-11-30",
  "eventTime":"2024-01-10T02:15:10.045Z",
  "payload":{
    "applicationOAuthClientSecretExpiry":{
      "clientId":"amzn1.application-oa2-client.xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "clientSecretExpiryTime":"2024-03-03T22:06:39.224Z",
      "clientSecretExpiryReason":"PERIODIC_ROTATION"
    }
  },
  "notificationMetadata":{
    "applicationId":"amzn1.sp.solution.xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "subscriptionId":"a275c00d-260c-4xxxxxxxxxxxf25",
    "publishTime":"2024-01-10T02:15:14.269Z",
    "notificationId":"e7e27216-4970-477a-882c-e4xxxxxxxxxxxxxdc"
  }
}

Tutorial: ruotare il segreto client dell'applicazione

Scopri come modificare i segreti dei tuoi clienti utilizzando il rotateApplicationClientSecret operazione.

Prerequisiti:

Per completare correttamente questo tutorial, devi avere:

• Accesso alla console per sviluppatori.
• Accesso ad Amazon SQS e a una nuova coda SQS.
• Le credenziali attuali del client dell'applicazione.

Passaggio 1. Registra la coda SQS per ricevere le nuove credenziali

1. Sign in to your developer account on the Solution Provider Portal. Navigate to the Developer Console page that lists all your applications.

   📘

   Nota

   Per Seller Central utenti, accedi a Seller Central per il tuo marketplace e vai a Apps and Services, quindi Develop Apps.

   Per Vendor Central utenti, accedi a Vendor Central per il tuo marketplace e vai a Integration, quindi API Integration.

2. Seleziona Notification Preferences.

3. On the Subscription page, find the application for which you want to receive the expiring credential notification.

4. In the Application Client New Secret row, enter the SQS queue where you want to receive the new credential.

Passaggio 2. Chiama l'operazione rotateApplicationClientSecret

Chiama il rotateApplicationClientSecret operazione con la credenziale dell'applicazione che si desidera ruotare. I passaggi seguenti mostrano il flusso di lavoro, con schermate dello strumento Postman.

1. Genera un token di accesso LWA chiamando l'endpoint API del token (https://api.amazon.com/auth/O2/token) utilizzando client_id, client_sceret, grant_type, e scope nel POST chiama corpo come x-www-form-urlencoded parametri.

   

2. Usa il token di accesso LWA del passaggio 1 del x-amz-access-token intestazione del rotateApplicationClientSecret con l'URL dell'endpoint https://sellingpartnerapi-na.amazon.com/applications/2023-11-30/clientSecret.

   

Risposta

Questa operazione non restituisce una risposta. Se la credenziale viene ruotata correttamente, si riceve una risposta 204 e la nuova credenziale viene inviata come notifica alla coda SQS registrata.

❗️

Ruota le credenziali dopo aver effettuato la chiamata

The credential you use to call rotateApplicationClientSecret expires after seven days. If you don't update your credential before it expires, your application will stop working.

Esempio di richiesta

POST https://sellingpartnerapi-na.amazon.com/applications/2023-11-30/clientSecret

Risposta

Questa operazione non restituisce una risposta. Se la credenziale viene ruotata correttamente, si riceve una risposta 204 e la nuova credenziale viene inviata come notifica alla coda SQS registrata.

Fase 3. Ottieni l'ultimo segreto del cliente dalla tua coda SQS

Usa un client Amazon SQS per ricevere il messaggio dalla coda preregistrata. Per ricevere i messaggi nella coda SQS, consulta la documentazione ReceiveMessage.

Risposta

Esempio di risposta

{
  "notificationVersion": "1.0",
  "notificationType": "APPLICATION_OAUTH_CLIENT_NEW_SECRET",
  "payloadVersion": "2023-11-30",
  "eventTime": "2024-01-10T22:09:17.456Z",
  "payload": {
    "applicationOAuthClientNewSecret": {
      "clientId": "amzn1.application-oa2-client.6XXXXXXXXXXXXXXXXXXXXXXXXX",
      "newClientSecret": "amzn1.oa2-cs.v1.8b6XXXXXXXXXXXXXXXXXXXXXXXXX",
      "newClientSecretExpiryTime": "2024-07-08T22:09:17.198Z",
      "oldClientSecretExpiryTime": "2024-01-17T22:09:17.180Z"
    }
  },
  "notificationMetadata": {
    "applicationId": "amzn1.sp.solution.6XXXXXXXXXXXXXXXXXXXXXXXXX",
    "subscriptionId": "8594dc0e-78dc-4b05-83a4-a6XXXXXXXXXXXXXX",
    "publishTime": "2024-01-10T22:09:18.706Z",
    "notificationId": "b0805eb9-78f7-49bb-ac0e-XXXXXXXXXXX"
  }
}

Raccomandazioni generali

• Usa la notifica di scadenza: Si consiglia di utilizzare la notifica di scadenza per richiamare una rotazione. L'ora di scadenza indicata nella notifica di scadenza serve da indicatore del momento in cui è necessario ruotare le credenziali.

• Abilita la crittografia lato server per SQS: Per motivi di sicurezza, abilita la crittografia SQS lato server e concedi ad Amazon l'accesso per scrivere nella tua coda SQS. Per ulteriori informazioni, consulta Concedi a Selling Partner API il permesso di scrivere nella tua coda SQS.

• Store your credentials in your application's credential vault: For security, make sure you don't pass the secret in an unencrypted format. We recommended storing credentials in a credential vault, such as KMS custom keys store.

• Test dell'integrazione delle API di gestione delle applicazioni: utilizza l'API di gestione delle applicazioni su una bozza di applicazione prima di utilizzarla su un'applicazione di produzione. È quindi possibile testare l'infrastruttura per caricare il segreto dalla coda SQS all'archivio segreto dell'applicazione indipendentemente dall'applicazione di produzione. Dopo aver ricevuto il nuovo segreto per la bozza dell'applicazione, utilizzatelo per assicurarvi che funzioni.