# Recuperare le associazioni di attributi di una connessione

`GET /v1/connections/{connection_id}/attribute-mappings` · permesso `connections:read`

Restituisce le regole di associazione degli attributi di una connessione aziendale (SAML o OIDC), ordinate per destinazione. Ogni regola associa un attributo o una claim inviato dal provider di identità (`source_name`) a un campo utente (`target`). L'intestazione `ETag` riporta la versione dell'elenco; inviala come `If-Match` quando sostituisci l'elenco o applichi un profilo predefinito. Una connessione senza regole salvate restituisce un elenco vuoto: al momento dell'accesso si applica il valore predefinito del modello (il profilo `generic` per OIDC; per SAML non viene associato nulla). Le letture non vengono registrate nell'audit.

## Richiesta

| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `connection_id` | percorso | sì | ID della connessione aziendale (`conn_…`). |

## Risposta

`200 OK` con l'elenco e un `ETag`.

```json
{
  "attribute_mappings": [
    {
      "target": "email",
      "source_name": "email",
      "source_name_format": null,
      "overwrite": "always",
      "profile": "okta"
    },
    {
      "target": "user_metadata.department",
      "source_name": "department",
      "source_name_format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
      "overwrite": "if_empty",
      "profile": "generic"
    }
  ]
}
```

| Campo | Descrizione |
|---|---|
| `target` | `email`, `given_name`, `family_name`, `name`, `locale`, `zoneinfo`, `phone`, `groups` oppure `user_metadata.<key>`. |
| `source_name` | Attributo SAML `Name` o nome della claim OIDC (percorso con punti, profondità ≤ 3). |
| `source_name_format` | `NameFormat` SAML con cui viene letto l'attributo; `null` corrisponde solo per nome. |
| `overwrite` | `always` (a ogni accesso), `if_empty` (solo quando il campo è vuoto) oppure `never` (solo alla creazione). |
| `profile` | Profilo predefinito da cui deriva la regola; `generic` per le regole scritte a mano. |

## Errori

| HTTP | code | Quando |
|---|---|---|
| 404 | `not_found` | La connessione non esiste in questo ambiente o non è una connessione aziendale. |
| 401 | `unauthenticated` | La credenziale è assente, non valida o revocata. |
| 403 | `insufficient_permissions` | La credenziale non ha il permesso richiesto. |
| 429 | `rate_limited` | È stato superato il limite di frequenza; riprova dopo il periodo indicato da `Retry-After`. |
| 503 | `service_unavailable` | Una dipendenza è temporaneamente non disponibile; riprova dopo il periodo indicato da `Retry-After`. |

## Esempio

```bash
curl -i "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/attribute-mappings" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"
```

```bash
keenauth connections attribute-mappings get conn_01j9xp6q0r1s5t7v9w1x3y5z7b
```