本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# Amazon OpenSearch Service 的 JWT 身分驗證和授權
<a name="JSON-Web-tokens"></a>

Amazon OpenSearch Service 現在可讓您使用 JSON Web Token (JWTs) 進行身分驗證和授權。JWTs是以 JSON 為基礎的存取字符，用於授予單一登入 (SSO) 存取。您可以使用 OpenSearch Service 中的 JWTs來建立單一登入字符，以驗證對 OpenSearch Service 網域的請求。若要使用 JWTs，您必須啟用精細存取控制，而且必須提供有效的 RSA 或 ECDSA PEM 格式公有金鑰。如需精細存取控制的詳細資訊，請參閱 [Amazon OpenSearch Service 中的精細存取控制](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/fgac.html)。

您可以使用 OpenSearch Service 主控台、 AWS Command Line Interface (AWS CLI) 或 AWS SDKs來設定 JSON Web 權杖。

## 考量事項
<a name="consider"></a>

將 JWTs與 Amazon OpenSearch Service 搭配使用之前，您必須考慮下列事項：
+ 由於 RSA 公有金鑰的大小採用 PEM 格式，我們建議您使用 AWS 主控台來設定 JWT 身分驗證和授權。
+ 指定 JWTs 的主題和角色欄位時，您必須提供有效的使用者和角色，否則請求將被拒絕。
+ OpenSearch 2.11 是可用於 JWT 身分驗證的最早相容版本。

## 修改網域存取政策
<a name="modifying"></a>

您必須先更新網域存取政策，以允許 JWT 使用者存取網域，才能將網域設定為使用 JWT 身分驗證和授權。否則，所有傳入的 JWT 授權請求都會遭到拒絕。提供子資源 (/\*) 完整存取權的建議網域存取政策為：

------
#### [ JSON ]

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
      {
      "Effect": "Allow",
      "Principal": {
        "AWS": "*"
      },
      "Action": "es:ESHttp*",
      "Resource": "arn:aws:es:{{us-east-1}}:{{111122223333}}:domain/{{domain-name}}/*"
    }
  ]
}
```

------

## 設定 JWT 身分驗證和授權
<a name="configuration"></a>

您可以在網域建立程序期間或透過更新現有網域來啟用 JWT 身分驗證和授權。設定步驟會因您選擇的選項而略有不同。

下列步驟說明如何在 OpenSearch Service 主控台中設定 JWT 身分驗證和授權的現有網域：

1. 在**網域組態**下，導覽至 ** OpenSearch 的 JWT 身分驗證和授權**，選取**啟用 JWT 身分驗證和授權**。

1. 設定要用於網域的公有金鑰。若要這樣做，您可以上傳 PEM 檔案、包含公有金鑰，或手動輸入。
**注意**  
如果上傳或輸入的金鑰無效，則會在指定問題的文字方塊上方顯示警告。

1. （選用） 在其他設定下，您可以設定下列選用欄位
   + **主旨金鑰** — 您可以保留此欄位空白，以使用 JWTs的預設`sub`金鑰。
   +  **角色金鑰** — 您可以保留此欄位空白，以使用 JWTs的預設`roles`金鑰。

   完成變更後，請儲存您的網域。

## 使用 JWKS 端點來驗證 JWT
<a name="jwks-endpoint"></a>

您可以設定 JSON Web 金鑰集 (JWKS) 端點 URL，從身分提供者動態擷取公有金鑰，而不是設定靜態公有金鑰。設定 JWKS 端點時，OpenSearch Service 會自動擷取和快取用於驗證 JWT 簽章的公有金鑰，無需在身分提供者輪換簽署金鑰時手動更新金鑰。

JWKS 端點組態需要 OpenSearch 3.3 版或更新版本。

**注意**  
同時設定 JWKS URL 和靜態公有金鑰時，會優先使用 JWKS URL，並忽略靜態公有金鑰。

### 回溯相容性
<a name="jwks-backward-compatibility"></a>

此功能可維持完整的回溯相容性：
+ 當 `JwksUrl` 未指定或設定為 null 時，系統會使用現有的靜態公有金鑰機制。
+ 現有的 JWT 組態會繼續運作，無需修改。
+ 您可以更新網域組態，在靜態金鑰和 JWKS 之間切換。

### 設定 JWKS 端點
<a name="jwks-configuring"></a>

您可以使用 OpenSearch Service 主控台、 AWS CLI或組態 API 來設定 JWKS 端點。

#### 主控台
<a name="jwks-console"></a>

**設定 JWKS 端點**

1. 在**網域組態**下，導覽至 ** OpenSearch 的 JWT 身分驗證和授權**。

1. 選取**啟用 JWT 身分驗證和授權**。

1. 針對**金鑰來源**，選取 **JWKS URL**。

1. 輸入身分提供者提供的 JWKS 端點 URL （例如 `https://example.com/.well-known/jwks.json`)。

1. （選用） 在其他**設定**下設定**主旨金鑰**和**角色金鑰**欄位。

1. 選擇**儲存變更**。

#### AWS CLI
<a name="jwks-cli"></a>

下列 AWS CLI 命令會為現有網域上的 JWT 身分驗證設定 JWKS 端點：

```
aws opensearch update-domain-config \
  --domain-name {{my-domain}} \
  --advanced-security-options '{"JWTOptions":{"Enabled":true, "JwksUrl":"{{https://example.com/.well-known/jwks.json}}", "SubjectKey":"{{sub}}", "RolesKey":"{{roles}}"}}'
```

#### 組態 API
<a name="jwks-api"></a>

對組態 API 的下列請求會為現有網域上的 JWT 身分驗證設定 JWKS 端點：

```
POST https://es.{{us-east-1}}.amazonaws.com/2021-01-01/opensearch/domain/{{my-domain}}/config
{
  "AdvancedSecurityOptions": {
    "JWTOptions": {
      "Enabled": true,
      "JwksUrl": "{{https://example.com/.well-known/jwks.json}}",
      "RolesKey": "{{optional-roles-key}}",
      "SubjectKey": "{{optional-subject-key}}"
    }
  }
}
```

### JWT 標頭需求
<a name="jwks-header-requirements"></a>

使用 JWKS 端點時，JWT 標頭必須包含金鑰 ID (`kid`)，以識別要用於驗證的特定金鑰：

```
{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "V-diposfUJIk5jDBFi_QRouiVinG5PowskcSWy5EuCo"
}
```

此`kid`值必須符合 JWKS 端點回應中的金鑰識別符。

如需 JWKS 組態選項和安全性設定的詳細資訊，請參閱 OpenSearch 文件中的[使用 JWKS 端點來驗證 JWT](https://docs.opensearch.org/latest/security/authentication-backends/jwt/#using-a-jwks-endpoint-to-validate-a-jwt)。

## 使用 JWT 傳送測試請求
<a name="test"></a>

使用指定的主旨和角色對建立新的 JWT 之後，您可以傳送測試請求。若要這樣做，請使用私有金鑰，透過建立 JWT 的工具簽署您的請求。OpenSearch Service 能夠透過驗證此簽章來驗證傳入請求。

**注意**  
如果您為 JWT 指定自訂主體金鑰或角色金鑰，則必須為 JWT 使用正確的宣告名稱。

以下是如何使用 JWT 字符透過網域的搜尋端點存取 OpenSearch Service 的範例：

```
curl -XGET "$search_endpoint" -H "Authorization: Bearer <JWT>"
```

### 設定 JWT 身分驗證和授權 (AWS CLI)
<a name="cli"></a>

如果網域存在，以下 AWS CLI 命令會啟用 OpenSearch 的 JWT 身分驗證和授權：

```
aws opensearch update-domain-config --domain-name <your_domain_name> --advanced-security-options '{"JWTOptions":{"Enabled":true, "PublicKey": "<your_public_key>", "SubjectKey": "<your_subject_key>", "RolesKey": "<your_roles_key>"}}'
```

#### 設定 JWT 身分驗證和授權 （透過 API 設定）
<a name="API"></a>

下列對組態 API 的請求會在現有網域上啟用 OpenSearch 的 JWT 身分驗證和授權：

```
POST https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/domain/my-domain/config
{
  "AdvancedSecurityOptions": {
    "JWTOptions": {
      "Enabled": true,
      "PublicKey": "public-key",
      "RolesKey": "optional-roles-key",
      "SubjectKey": "optional-subject-key"
   }  
  }
}
```

##### 產生金鑰對
<a name="gen-key-pair"></a>

為了為您的 OpenSearch 網域設定 JWTs，您需要以隱私權增強郵件 (PEM) 格式提供公有金鑰。Amazon OpenSearch Service 目前在使用 JWTs時支援兩種非對稱加密演算法：RSA 和 ECDSA。

若要使用通用 openssl 程式庫建立 RSA 金鑰對，請遵循下列步驟：

1. `openssl genrsa -out privatekey.pem 2048`

1. `openssl rsa -in privatekey.pem -pubout -out publickey.pem`

在此範例中， `publickey.pem` 檔案包含用於 Amazon OpenSearch Service 的公有金鑰，而 `privatekey.pem`包含用於簽署傳送至服務的 JWTs的私有金鑰。此外，如果您需要私有金鑰來產生 JWTs，您可以選擇將私有金鑰轉換為常用`pkcs8`格式。

如果您使用上傳按鈕將 PEM 檔案直接新增至主控台，則檔案必須具有`.pem`副檔名、其他副檔名，例如 `.crt``.cert`或 目前`.key`不受支援。