Chiavi API

• Tipo non definito

Training

A Chiave API Permette a un'applicazione o a un'automazione di accedere ai servizi Immersive con i diritti di un account associato. Evita di chiedere password e codice MFA ogni volta che un programma viene eseguito.

Questo tutorial spiega come creare, visualizzare, estendere ed eliminare le chiavi da RestFrontage. È pensato per l'amministratore Cervello. Esempi di chiamate WebAPI e autenticazione del codice saranno trattati in un articolo separato.

Gli screenshot mostrano l'interfaccia di RestFrontage in un ambiente demo. Le chiavi mostrate non aprono alcun accesso al tuo ambiente.

1. Comprendere il principio

1.1 Un'identità per un'applicazione

Un'app di monitoraggio, uno strumento di importazione o un'attività programmata devono poter accedere a Immersive senza aspettare che qualcuno inserisca un codice sul proprio telefono. Viene utilizzata una chiave API per autenticare questo accesso automatizzato.

Ogni tasto è associato a:

• a Nome dell'applicazione, il che rende possibile identificarne l'uso;
• a Account immersivo, i cui diritti esercita;
• a Periodo di validità, con una data di inizio e una data di fine;
• uno stato Attivo o spento.

La chiave non concede automaticamente tutti i diritti. Se l'account associato può visualizzare una risorsa ma non modificarla, l'applicazione rimane soggetta a questa restrizione.

flowchart TD
    A["L’application présente son nom et sa clé API"] --> B["Vérifier la clé, ses dates et le compte associé"]
    B -->|Échec| R["Accès refusé"]
    B -->|Succès| D["Appliquer les droits du compte à la demande"]
    D -->|Droits insuffisants| F["Opération refusée"]
    D -->|Droits suffisants| G["Opération autorisée"]

1.2 Cosa c'entra questo con l'MFA?

MFA protegge gli accessi interattivi tramite nome utente e password. La chiave API è un altro mezzo di autenticazione, destinato ai programmi: non è richiesto alcun codice TOTP per usarlo.

Pertanto, non è necessario esentare l'account dalla MFA per permettere a un'applicazione di utilizzare la propria chiave API. Il login abituale di questo account rimane soggetto alla modalità MFA scelta in Immersive.

1.3 Scegli l'account collegato

Preferibilmente usare un Account app dedicato, con solo i diritti necessari. In questa guida, Supervisione del laboratorio Usato Account API - Monitoraggio.

Il nome dell'applicazione non è né un utente né un gruppo di permessi. È l'account associato a detenere i diritti. Associare una chiave a Cerebrate gli conferirebbe diritti Cerebrate; questa scelta dovrebbe essere riservata a usi che ne hanno davvero bisogno.

L'account deve rimanere disponibile: non deve essere disattivato, cancellato, scaduto o temporaneamente bloccato. Una chiave ancora valida non può aggirare l'indisponibilità dell'account.

2. Gestione delle chiavi aperte

Connettiti a RestFrontage con Cervello, apri Sicurezza, allora Chiavi API, riconoscibile dalla sua icona di chiave. L'indirizzo della pagina è /Security/ApiKeys.

Nell'interfaccia attuale, questa pagina e le sue operazioni di gestione sono riservate a Cerebrate.

La pagina mostra il numero di chiavi e il numero di chiavi attive. Ogni riga mostra il nome dell'applicazione, l'account associato, gli ultimi caratteri della chiave, il suo periodo di validità e la sua origine. Gli ultimi caratteri aiutano a distinguere le chiavi; non sostituiscono il valore completo.

Il campo Trova un'app o un account Filtra l'elenco. Clicca su una riga per aprire il suo record.

2.1 Comprensione degli stati

Stato	Significato
Attivo	La chiave viene attivata, il suo periodo di validità è in corso e l'account associato è disponibile. I diritti di conto continuano ad applicarsi a ogni transazione.
In arrivo	La data di inizio non è ancora stata raggiunta. La chiave non può ancora essere utilizzata.
Scaduto	La data di fine è stata raggiunta o superata. La chiave non può più essere autenticata.
Disabili	La chiave non è attivata. Non può essere usata.
Account non disponibile	L'account collegato non viene trovato, disattivato, cancellato, scaduto o temporaneamente bloccato.

Lo stato riassume la situazione quando la lista viene caricata. Aggiorna la pagina dopo un intervento esterno o per controllare una scadenza appena raggiunta. Possono coesistere diverse cause; controlla anche le date e l'account associato.

2.2 Due origini nella stessa lista

Origine	Gestione possibile dal sito
Sicurezza della Base	La chiave è stata creata da questa interfaccia. Puoi visualizzare la sua carta, vedere il suo valore quando disponibile, estendere la data di fine e cancellarla.
Appimpostazioni · Sola lettura	La chiave è definita nella configurazione del server. Puoi visualizzare la sua scheda e il suo valore disponibile. Modificarla o eliminarla è responsabilità dell'operatore nella configurazione.

Le chiavi di configurazione non vengono automaticamente trasformate in chiavi gestite dal sito. Le due origini possono coesistere.

3. Crea una chiave API

3.1 Compila la domanda e scegli il tuo account

1. Click Crea una chiave API.
2. In Nome dell'app, inserire un nome riconoscibile, come Supervisione del laboratorio.
3. Clicca sul link Scegli un utente.
4. Nella finestra di ricerca, trova l'account che vuoi collegare e selezionalo.
5. Controlla che il nome compare in Account collegato.

Selezionando questa opzione si apre una seconda finestra senza perdere le informazioni già inserite. Il link con il nome dell'account ti permette quindi di scegliere un altro utente prima della creazione.

3.2 Date e salvataggio

1. Controlla il Inizio della validità.
2. Scegli il Fine della validità, che è successiva all'inizio e situata nel futuro.
3. Sia Chiave attivata Verificato la presenza di una chiave destinata a essere utilizzabile in questo periodo.
4. Click Creare la Chiave.
5. Aspetta il messaggio La chiave API è stata salvata.

Le date sono indicate nel Fuso orario del browser. Quando il modulo viene aperto, viene proposto un periodo di circa un anno; adattarlo alle reali esigenze della domanda. Per prepararsi ad accessi futuri, scegliere una data di inizio successiva.

Il valore chiave viene generato automaticamente, quindi non devi inventare una password o fornire MFA per l'applicazione.

4. Visualizza, visualizza e copia la chiave

4.1 Proprietà Aperte

Clicca sulla linea chiave nell'elenco. Il Proprietà della chiave API Mostra il nome dell'app, l'account associato, l'origine, lo stato attivato e le date.

La chiave è nascosto di default, anche quando si torna alla sua forma. I punti visibili non sono il suo valore e non permettono di dedurne la lunghezza.

4.2 Visualizza e poi copia

1. Click Programma.
2. Aspetta che appaia il valore. Durante il caricamento, un'animazione sostituisce il testo del pulsante.
3. Usa ilIcona di copia a destra del campo per copiare il valore completo.
4. Incollalo nella posizione protetta fornita dall'applicazione client.
5. Click Nasconditi Quando hai finito.

La chiave visibile in questa cattura appartiene solo all'ambiente demo utilizzato per le illustrazioni. È stata eliminata dopo il completamento delle catture.

L'icona di copia appare solo quando la chiave è visualizzata. Se il campo è troppo corto per mostrare il valore completo, usa questa icona: copia la chiave completa. Nasconditi rimuove il valore dallo schermo, ma non cancella ciò che è già stato copiato sulla cartellina.

4.3 Quali informazioni dovrebbero essere trasmesse all'applicazione?

L'integratore ha bisogno dell'indirizzo del server Immersive, il Nome dell'applicazione e il chiave API completa. Il nome corrisponde a x-app-name e la chiave di x-api-key negli exchange API.

La password dell'account associato e i codici della sua applicazione MFA non sono necessari per questo accesso a chiave. Le richieste e la gestione dei token di accesso saranno dettagliate nell'articolo WebAPI.

5. Estendere il periodo di validità

Per una tonalità originale Sicurezza della Base, l'estensione ti permette di mantenere lo stesso valore estendendo la sua data di fine.

1. Apri la tessera magnetica.
2. In Estendi a, scegli una data successiva alla fine attuale e che sia nel futuro.
3. Click Estendere.
4. Controlla il messaggio La data di fine è stata prorogata. e la nuova data mostrata.

L'estensione non cambia il nome dell'applicazione, l'account associato o il valore della chiave. Non accorcia il periodo di validità.

Una chiave scaduta può essere prorogata a una data futura. Torna a essere utilizzabile se viene attivata, la sua validità ha raggiunto l'inizio della sua validità e l'account associato è disponibile. L'estensione non riattiva un account disabilitato.

6. Visualizza una chiave da appsettings

Chiavi del cuscinetto Appimpostazioni · Sola lettura Derivano dalla configurazione del server.

Puoi aprire le loro proprietà e vedere il loro valore quando disponibile. L'annuncio non offre Estendere, né Elimina questa chiave.

Per modificarli, rimuoverli o prorogare la loro scadenza, contatta la persona che gestisce la configurazione del server. Non creare un'altra chiave pensando che sostituirà automaticamente la chiave appsettings: i due accessi rimarranno separati.

7. Elimina o sostituisci una chiave

7.1 Rimuovere l'accesso che non è più necessario

1. Apri la tessera originale Sicurezza della Base.
2. Click Elimina questa chiave.
3. Controlla il nome dell'app e l'account nella finestra di conferma.
4. Click Elimina la chiave per confermare, o su Cancella per mantenere l'accesso.
5. Controlla il messaggio di cancellazione e la scomparsa della linea dalla lista.

La cancellazione è definitivo. La chiave e i token ottenuti con essa vengono revocati: non consentono più nuovi accessi. I dati già consultati o copiati dall'applicazione non vengono cancellati da questa azione.

7.2 Sostituire una chiave senza interrompere l'uso previsto

Per un rinnovo programmato, puoi creare una nuova chiave per la stessa app e account, con un periodo di validità che abbia senso. Più chiavi possono coesistere per lo stesso nome di app.

flowchart TD
    A["Créer une nouvelle clé"] --> B["Configurer l’application avec la nouvelle clé"]
    B --> C["Vérifier un accès et les opérations nécessaires"]
    C --> D{"Le fonctionnement est-il confirmé ?"}
    D -->|Non| E["Corriger la configuration ou les droits"]
    E --> C
    D -->|Oui| F["Supprimer l’ancienne clé"]

Localizza entrambe le chiavi per date e ultimi caratteri, così puoi eliminare quella corretta. La nuova chiave non disattiva automaticamente la vecchia chiave.

8. Risolvere le sfide comuni

8.1 L'account selezionato è disabilitato

La creazione viene respinta e un messaggio indica l'account interessato. Nel seguente esempio, Eric T. è disabilitato.

Scegli un account attivo adatto all'app. Se vuoi davvero che l'account selezionato venga riattivato, fallo prima nella sua scheda utente, poi ricomincia a crearlo. Non riattivare volontariamente un account disabilitato solo per far sparire il messaggio.

Un errore di validazione non crea la chiave. Il modulo conserva le informazioni inserite per permettere la correzione.

8.2 La chiave esiste, ma l'app non accede ai dati

Controlla successivamente lo stato della chiave, le sue date, l'account associato, il nome dell'applicazione e il valore completo copiato. Controlla anche che l'applicazione stia utilizzando il server Immersive corretto.

Se l'autenticazione ha successo ma un'operazione viene negata, si rivedere il Diritti dell'account associato sulla risorsa richiesta. Creare una nuova chiave per lo stesso account non gli assegna ulteriori diritti.

8.3 Altri messaggi e situazioni

Posizione	Azioni da intraprendere
Conto scaduto	Controlla se il suo utilizzo dovrebbe essere esteso nel file utente o seleziona un altro account attivo.
Data di fine negata	Quando la crei, scegli una fine futura che sia successiva all'inizio. Per un'estensione, scegli anche una data dopo la fine attuale della chiave.
Il valore di questa vecchia chiave non è stato preservato	La chiave esistente è ancora utilizzabile, ma il suo valore non può essere visualizzato nuovamente. Se viene persa, crea una nuova chiave, aggiorna l'applicazione e rimuovi quella vecchia.
La chiave non può essere decrittata su questo server	Fai controllare le chiavi di protezione del server dall'operatore. Questo errore di consultazione non modifica, da solo, l'accesso all'API.
Questa chiave è stata modificata o eliminata	Chiudi la scheda e aggiorna la lista prima di ricominciare. Un altro intervento potrebbe aver cambiato il suo stato.
La registrazione non è stata confermata	Aggiorna la lista e controlla il risultato prima di riprovare, per evitare una creazione duplicata.
Il pulsante copia non appare	Clicca prima Programma. Il pulsante è volutamente assente quando il tasto è nascosto.

Per le nuove chiavi consultabili, il server mantiene un valore protetto che permette di visualizzarle nuovamente. L'operatore deve mantenere gli elementi di protezione necessari durante i backup e i cambi di server. Questo punto non richiede nuove password da parte dell'utente.

9. Controlla la commissione

Prima di fornire una chiave per una domanda, controlla questi punti:

• Il nome dell'app è riconoscibile.
• L'account collegato è attivo e ha solo i diritti necessari.
• il periodo di validità corrisponde all'uso previsto;
• L'app utilizza il server, il nome e la chiave completa corretti.
• L'accesso e le operazioni previste sono stati verificati dall'app.
• La chiave viene conservata in un luogo protetto e la sua data di scadenza viene tracciata.
• Le vecchie chiavi che non erano più necessarie sono state rimosse dopo la sostituzione.