

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à.

# Guida introduttiva alla federazione delle identità in uscita

Questa guida mostra come abilitare la federazione delle identità in uscita per i tuoi AWS account e ottieni il tuo primo JSON Web Token (JWT) (utilizzando [GetWebIdentityToken](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetWebIdentityToken.html) API). Abiliterai la funzionalità, stabilirai una relazione di fiducia con un servizio esterno, configurerai le autorizzazioni IAM e richiederai un token utilizzando uno dei due AWS CLI o AWS SDK per Python (Boto3).

## Prerequisiti
<a name="outbound-federation-prerequisites"></a>

Prima di iniziare, assicurati di disporre di quanto segue:
+ Ultima versione di AWS CLI o Python 3.8 (o successivo) e Boto3 installati (per AWS Esempi SDK)
+ Un account di servizio esterno in cui è possibile configurare le relazioni di fiducia (ad esempio un provider cloud esterno, un provider SaaS o un'applicazione di test)

**Nota**  
Il `GetWebIdentityToken` L'API non è disponibile sull'endpoint STS Global.
Assumere un ruolo in un altro [AWS partizione](https://docs.aws.amazon.com/whitepapers/latest/aws-fault-isolation-boundaries/partitions.html), scambia il JWT restituito da [GetWebIdentityToken](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetWebIdentityToken.html) per le credenziali temporanee chiamando [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html). Questo scambio è supportato solo attraverso i confini delle partizioni. Per ulteriori informazioni, consulta [Federando AWS identità trasversali AWS partizioni](id_roles_providers_outbound_cross_partition.md). Per presupporre il ruolo della stessa partizione, utilizzare [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) API invece.

## Abilita la federazione delle identità in uscita per il tuo account
<a name="enable-outbound-federation"></a>

Devi abilitare la federazione delle identità in uscita prima di poter richiedere i token. È possibile abilitare la funzionalità utilizzando il AWS Console di gestione o programmaticamente utilizzando [EnableOutboundWebIdentityFederation](https://docs.aws.amazon.com/IAM/latest/APIReference/API_EnableOutboundWebIdentityFederation.html) API.

### Utilizzo di AWS CLI
<a name="enable-using-cli"></a>

```bash
aws iam enable-outbound-web-identity-federation
```

### Utilizzo AWS SDK for Python
<a name="enable-using-sdk"></a>

```python
import boto3

# Create IAM client
iam_client = boto3.client('iam')

# Enable outbound identity federation
response = iam_client.enable_outbound_web_identity_federation()
print(f"Feature enabled. Issuer URL: {response['IssuerUrl']}")
print(f"Status: {response['Status']}")
```

### Utilizzo di AWS Console
<a name="enable-using-console"></a>

Accedi a IAM e seleziona **Impostazioni dell'account** sotto **Gestione degli accessi** sezione del menu di navigazione a sinistra

![voce di menu delle impostazioni dell'account evidenziata nella barra di navigazione a sinistra nella sezione Gestione degli accessi.](https://docs.aws.amazon.com/it_it/IAM/latest/UserGuide/images/outbound-screen-1.png)


Una volta abilitata la funzione, annota l'URL dell'emittente specifico del tuo account. Utilizzerai questo URL per configurare le relazioni di fiducia nei servizi esterni. È inoltre possibile recuperare l'URL dell'emittente, se necessario, utilizzando [GetOutboundWebIdentityFederationInfo](https://docs.aws.amazon.com/IAM/latest/APIReference/API_GetOutboundWebIdentityFederationInfo.html) API.

![Interfaccia Outbound Identity Federation che mostra lo stato Attivato con il pulsante Disabilita e l'URL dell'emittente del token.](https://docs.aws.amazon.com/it_it/IAM/latest/UserGuide/images/outbound-screen-2.png)


## Stabilisci una relazione di fiducia nel servizio esterno
<a name="establish-trust-relationship"></a>

Configura il servizio esterno in modo che si fidi e accetti i token emessi dal tuo AWS account. Le fasi specifiche variano in base al servizio, ma generalmente comportano:
+ Registrazione del tuo AWS URL dell'emittente dell'account come provider di identità affidabile
+ Configurazione delle dichiarazioni da convalidare (destinatario, modelli tematici)
+ Mappatura delle dichiarazioni dei token alle autorizzazioni nel servizio esterno

Per istruzioni di configurazione dettagliate, consulta la documentazione del servizio esterno. Se l'interlocutore è AWS in un'altra partizione, vedere [Federando AWS identità trasversali AWS partizioni](id_roles_providers_outbound_cross_partition.md).

## Configurazione delle autorizzazioni IAM
<a name="configure-iam-permissions"></a>

Crea una policy IAM che conceda il permesso di chiamare il [GetWebIdentityToken](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetWebIdentityToken.html) API e allega la policy a un ruolo IAM che deve generare token.

Questa policy di esempio garantisce l'accesso alla generazione di token con restrizioni specifiche. Consente di richiedere token solo per»https://api.example.com«come pubblico e impone una durata massima del token di 5 minuti (300 secondi). Fare riferimento a [IAM e AWS STS chiavi di contesto delle condizioni](reference_policies_iam-condition-keys.md) per un elenco di chiavi di condizione che puoi utilizzare per applicare le proprietà dei token.

### Policy IAM di esempio
<a name="example-iam-policy"></a>

```json
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "sts:GetWebIdentityToken",
            "Resource": "*",
            "Condition": {
                "ForAllValues:StringEquals": {
                    "sts:IdentityTokenAudience": "https://api.example.com"
                },
                "Null": {
                    "sts:IdentityTokenAudience": "false"
                },
                "NumericLessThanEquals": {
                    "sts:DurationSeconds": 300
                }
            }
        }
    ]
}
```

## Richiedi il tuo primo JSON Web Token (JWT)
<a name="request-first-jwt"></a>

Puoi richiedere un JSON Web Token utilizzando [GetWebIdentityToken](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetWebIdentityToken.html) API. È possibile specificare i seguenti parametri quando si chiama l'API:
+ **Destinatari (obbligatorio):** Il destinatario previsto del token. Questo valore compila il claim «aud» nel JWT. I servizi esterni convalidano questa dichiarazione per assicurarsi che il token sia destinato a loro.
+ **SigningAlgorithm (obbligatorio):** L'algoritmo crittografico utilizzato per firmare il token. I valori validi sono ES384 e RS256. Utilizzate ES384 per sicurezza e prestazioni ottimali o RS256 per una maggiore compatibilità con i sistemi che non supportano l'ECDSA.
+ **DurationSeconds (opzionale):** La durata del token in secondi. I valori validi vanno da 60 a 3600. Il valore predefinito è 300 (5 minuti). Consigliamo una durata più breve dei token per una maggiore sicurezza.
+ **Tag (opzionali):** Un elenco di coppie chiave-valore da includere come attestazioni personalizzate nel token. I servizi esterni possono utilizzare queste attestazioni per un'autorizzazione dettagliata.

L'API restituisce i seguenti campi:
+ **WebIdentityToken:** Il JWT firmato come stringa codificata in base64url. Includi questo token nelle richieste a servizi esterni.
+ **Scadenza:** Il timestamp UTC relativo alla scadenza del token.

### Utilizzo di AWS CLI
<a name="using-aws-cli"></a>

```
aws sts get-web-identity-token \
    --region us-east-1 \
    --endpoint-url https://sts.us-east-1.amazonaws.com \
    --audience "https://api.example.com" \
    --signing-algorithm ES384 \
    --duration-seconds 300 \
    --tags Key=team,Value=data-engineering \
           Key=environment,Value=production \
           Key=cost-center,Value=analytics
```

### Utilizzo AWS SDK for Python
<a name="using-aws-sdk-python"></a>

```python
import boto3

# GetWebIdentityToken requires a Regional STS endpoint.
sts_client = boto3.client(
    'sts',
    region_name='us-east-1',
    endpoint_url='https://sts.us-east-1.amazonaws.com'
)

response = sts_client.get_web_identity_token(
    Audience=['https://api.example.com'],
    DurationSeconds=300,
    SigningAlgorithm='ES384',
    Tags=[
        {'Key': 'team', 'Value': 'data-engineering'},
        {'Key': 'environment', 'Value': 'production'},
        {'Key': 'cost-center', 'Value': 'analytics'}
    ]
)

token = response['WebIdentityToken']
```

Puoi anche decodificare il JWT per controllarne il contenuto utilizzando librerie JWT standard come PyJWT, Python-jose per Python, Nimbus JOSE\+JWT per Java o debugger come jwt.io. Fare riferimento a [Comprendere le dichiarazioni relative ai token](id_roles_providers_outbound_token_claims.md) per ulteriori informazioni sui claim inclusi nel token.

## Usa il token con un servizio esterno
<a name="use-token-with-external-service"></a>

Dopo aver ricevuto il token, includilo nelle richieste al servizio esterno. Il metodo varia in base al servizio, ma la maggior parte dei servizi accetta i token nell'intestazione di autorizzazione. Il servizio esterno dovrebbe implementare una logica di convalida dei token che recupera le chiavi JWKS dal noto endpoint dell'emittente, verifica la firma del token e convalida le attestazioni essenziali prima di concedere l'accesso al tuo AWS carichi di lavoro.

## Recupera le chiavi di verifica e i metadati dagli endpoint OpenID Connect (OIDC)
<a name="fetch-verification-keys"></a>

L'URL dell'emittente univoco per il tuo AWS l'account ospita gli endpoint di rilevamento OpenID Connect (OIDC) che contengono le chiavi di verifica e i metadati necessari per la verifica dei token.

L'URL dell'endpoint di rilevamento OIDC contiene i metadati utilizzati da alcuni provider per verificare i token. È disponibile all'indirizzo:

```json
{issuer_url}/.well-known/openid-configuration
```

L'endpoint JWKS (JSON Web Key Set) contiene le chiavi utilizzate per verificare le firme dei token. È disponibile all'indirizzo:

```json
{issuer_url}/.well-known/jwks.json
```

### Recupera JWKS usando curl
<a name="fetch-jwks-curl"></a>

```non
curl https://{issuer_url}/.well-known/jwks.json
```

Risposta:

```json
{
  "keys": [
    {
      "kty": "EC",
      "use": "sig",
      "kid": "key-id-1",
      "alg": "ES384",
      "crv": "P-384",
      "x": "base64-encoded-x-coordinate",
      "y": "base64-encoded-y-coordinate"
    },
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "key-id-2",
      "n": "base64-encoded-modulus",
      "e": "AQAB"
    }
  ]
}
```

### Utilizzo AWS SDK for Python
<a name="fetch-using-sdk"></a>

```python
import requests

# Fetch Openid Configuration
open_id_config_response = requests.get("https://{issuer_url}/.well-known/openid-configuration")
open_id_config = open_id_config_response.json()

# Fetch JWKS
jwks_response = requests.get("https://{issuer_url}/.well-known/jwks.json")
jwks = jwks_response.json()
```

Consigliamo di memorizzare nella cache queste chiavi per evitare di recuperarle per ogni verifica del token.

### Convalide essenziali dei reclami
<a name="essential-claim-validations"></a>
+ **Oggetto (sub):** Verifica che l'attestazione oggetto contenga il pattern ARN principale IAM previsto.
+ **Scadenza (exp):** Assicurati che il token non sia scaduto. Le librerie JWT in genere lo gestiscono automaticamente.
+ **Pubblico (aud):** Verifica che il pubblico corrisponda al valore previsto. Ciò impedisce che i token destinati ad altri servizi vengano utilizzati con i tuoi.
+ **Emittente (iss):** Verifica che l'emittente corrisponda a AWS account di cui ti fidi. Mantieni un elenco di URL di emittenti affidabili.

Quando possibile, dovresti convalidare ulteriori AWS-richieste specifiche volte a implementare un controllo granulare degli accessi nel vostro servizio esterno. Ad esempio, convalida l'attestazione org\_id per limitare l'accesso ai principali IAM nel tuo AWS Organizzazione, controlla principal\_tags per applicare il controllo degli accessi basato sugli attributi (ad esempio consentendo solo ambienti di produzione o team specifici) o verifica le dichiarazioni relative al contesto della sessione come lambda\_source\_function\_arn o ec2\_instance\_source\_vpc per limitare l'accesso in base alla risorsa di calcolo. Fai riferimento a [Comprendere le dichiarazioni relative ai token](id_roles_providers_outbound_token_claims.md) per un elenco completo dei claim inclusi nel token.