Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# Document-level controlli di accesso
**La consapevolezza ACL non è un'autorizzazione**
Bedrock Managed Knowledge Base fornisce un ACL-aware filtro, non un limite di sicurezza. Bedrock Managed Knowledge Base non autentica gli utenti finali: l'applicazione è responsabile dell'autenticazione degli utenti e del passaggio del contesto di identità verificato. Poiché Bedrock Managed Knowledge Base non è in grado di verificare l'autenticità del contesto utente fornito, questa funzione filtra i risultati in base all'identità fornita ma non costituisce una vera autorizzazione. Non devi fare affidamento su questa funzionalità come unico meccanismo di controllo degli accessi senza l'autenticazione a monte.
Le fonti di dati personalizzate supportano opzionalmente il controllo degli accessi a livello di documento. A differenza dei connettori sottoposti a scansione, un'origine dati personalizzata non dispone di un sistema di autorizzazioni nativo, quindi è necessario fornire l'elenco di controllo degli accessi (ACL) per ogni documento quando lo si inserisce con l'operazione. `IngestKnowledgeBaseDocuments` Per una panoramica del riconoscimento ACL su tutti i connettori, vedere. [Attivazione del riconoscimento delle liste di controllo degli accessi](kb-managed-acl.md)
## Come funziona
Per un'origine dati ACL-enabled personalizzata, Bedrock Managed Knowledge Base applica gli elenchi di controllo degli accessi forniti dal cliente durante il filtraggio preliminare, restituendo solo i documenti a cui l'utente che effettua l'interrogazione è autorizzato a accedere. Real-time La verifica ACL non è supportata per le origini dati personalizzate perché i metadati ACL forniti dal cliente sono la fonte della verità.
## Abilita il riconoscimento ACL
Per abilitare il riconoscimento ACL per un'origine dati personalizzata, imposta su `aclEnabled` `true` in `connectorParameters` quando crei o aggiorni l'origine dati. Per la struttura di configurazione dell'origine dati, vedi[Personalizzato](kb-managed-ds-custom.md).
```
"connectorParameters": {
"type": "CUSTOM",
"version": "1",
"aclEnabled": true
}
```
## Fornisci controlli di accesso durante l'importazione di documenti
Fornisci l'ACL di un documento tramite il `accessControlList` campo del documento `metadata` nella `IngestKnowledgeBaseDocuments` richiesta. L'origine ACL è determinata dallo `metadata.type` stesso campo che controlla la provenienza degli attributi dei metadati:
+ **`IN_LINE_ATTRIBUTE`**— L'ACL viene letto dall'`accessControlList`array nel corpo della richiesta.
+ **`S3_LOCATION`**— L'ACL viene letto dall'`accessControlList`array nel `.metadata.json` file del documento in Amazon S3.
Poiché `accessControlList` risiede sotto `metadata` anziché come campo di primo livello`KnowledgeBaseDocument`, un documento ha un'unica fonte ACL, controllata da. `metadata.type` In questo modo si evita che vengano forniti ACL in conflitto per lo stesso documento (ad esempio, un ACL in linea nella richiesta e un ACL nel file S3). Il compromesso è che non è possibile combinare un ACL in linea con attributi di metadati o S3-based un ACL con attributi di S3-based metadati in linea per lo stesso documento.
Ogni voce contiene: `accessControlList`
+ `name`— L'indirizzo e-mail di un utente.
+ `type`— Deve essere`USER`.
+ `access`— O `ALLOW` o`DENY`. Le eccezioni di negazione sono consentite.
### ACL in linea (metadata.type = IN\_LINE\_ATTRIBUTE)
Forniscili `accessControlList` direttamente nel corpo della richiesta insieme agli attributi dei metadati in linea.
```
PUT /knowledgebases/{{KB12345678}}/datasources/{{DS12345678}}/documents HTTP/1.1
Content-type: application/json
{
"documents": [
{
"content": {
"dataSourceType": "CUSTOM",
"custom": {
"customDocumentIdentifier": {
"id": "hr-policy-2026"
},
"inlineContent": {
"textContent": {
"data": "Annual leave policy: All full-time employees are entitled to..."
},
"type": "TEXT"
},
"sourceType": "IN_LINE"
}
},
"metadata": {
"type": "IN_LINE_ATTRIBUTE",
"inlineAttributes": [
{
"key": "department",
"value": { "stringValue": "HR", "type": "STRING" }
}
],
"accessControlList": [
{
"name": "{{alice@example.com}}",
"type": "USER",
"access": "ALLOW"
},
{
"name": "{{bob@example.com}}",
"type": "USER",
"access": "DENY"
}
]
}
}
]
}
```
### S3-based ACL (metadata.type = S3\_LOCATION)
Indirizza i metadati del documento verso un `.metadata.json` file in Amazon S3. Sia gli attributi dei metadati che i `accessControlList` vengono letti da quel file.
```
"metadata": {
"type": "S3_LOCATION",
"s3Location": {
"uri": "s3://{{amzn-s3-demo-bucket}}/{{hr-policy-2026}}.metadata.json"
}
}
```
Il `.metadata.json` file utilizza lo stesso formato dei [file di metadati per documento](kb-managed-ds-s3-acl.md#kb-managed-ds-s3-acl-perdoc) per le origini dati Amazon S3. Questo file utilizza nomi di campo ACL in maiuscolo (`Name`,,`Access`)`Type`, che differiscono dai nomi di campo in minuscolo (`name`,,`type`) utilizzati nella richiesta in linea. `access`
```
{
"metadataAttributes": {},
"accessControlList": [
{
"Name": "{{alice@example.com}}",
"Type": "USER",
"Access": "ALLOW"
},
{
"Name": "{{bob@example.com}}",
"Type": "USER",
"Access": "DENY"
}
]
}
```
## Verifica la tua configurazione
Poiché gli ACL personalizzati vengono forniti dal cliente`IngestKnowledgeBaseDocuments`, convalidali prima di eseguire la query:
1. `aclEnabled`La conferma è `true` nella fonte dei dati (). `connectorParameters` `type` `CUSTOM`
1. Verifica che ogni documento importato includa un valore `accessControlList` inferiore `metadata` e che `metadata.type` corrisponda alla fonte ACL (`IN_LINE_ATTRIBUTE`per un file in linea, `S3_LOCATION` per un file S3).
1. Verifica che l'involucro del campo di immissione ACL corrisponda all'origine: minuscolo//per gli ACL in linea, maiuscolo`name`/`type`/`access`per il file S3. `Name` `Type` `Access` `.metadata.json`
1. Verifica che l'e-mail di un utente di prova corrisponda esattamente a quella `ALLOW` inserita `name` in un documento che ti aspetti che recuperi.
## Risoluzione dei problemi
**Nota**
Le configurazioni errate dell'ACL non producono errori espliciti durante il recupero. Il recupero non riesce a essere chiuso: i documenti interessati vengono omessi automaticamente, quindi una query restituisce un numero inferiore o nullo di risultati anziché un errore. Utilizza i controlli di verifica sopra riportati per diagnosticare questi problemi.
**ACL-enabled Sintomi, cause e correzioni personalizzati**
| Caratteristiche | Causa probabile | Correggere |
| --- | --- | --- |
| Recupera restituisce 0 risultati per un utente che dovrebbe avere accesso. | L'userIde-mail non corrisponde a nessuna accessControlList voce. | Allinea l'e-mail dell'utente a quella contenuta name in una ALLOW voce. |
| Un ACL in linea viene rifiutato o ignorato. | Involucro del campo errato o non lo è. metadata.type IN\_LINE\_ATTRIBUTE | Usa le lettere minuscolename/type/accesse imposta su. metadata.type IN\_LINE\_ATTRIBUTE |
| Non viene S3-based applicato un ACL. | metadata.typenon lo è S3\_LOCATION oppure il .metadata.json file è mancanteaccessControlList. | metadata.typeImposta S3\_LOCATION e accessControlList includi nel file. |
| Un documento non viene mai restituito a nessuno. | Il documento è stato ingerito senza un. accessControlList | Re-ingest il documento con un. accessControlList |