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

# Amazon OpenSearch Serverless 的 SAML 身分驗證
<a name="serverless-saml"></a>

您可以透過 Amazon OpenSearch Serverless 的 SAML 身分驗證，使用現有身分提供者，為無伺服器集合的 OpenSearch Dashboards 端點提供單一登入 (SSO)。

SAML 身分驗證讓您可以使用第三方身分提供者，登入 OpenSearch Dashboards，以便為資料編製索引和進行搜尋。OpenSearch Serverless 支援使用 SAML 2.0 標準的提供者，例如 IAM Identity Center、Okta、Keycloak、Active Directory Federation Services (AD FS) 和 Auth0。您可以設定 IAM Identity Center 來同步來自其他身分來源的使用者和群組，例如 Okta、OneLogin 和 Microsoft Entra ID。如需 IAM Identity Center 支援的身分來源清單以及設定這些來源的步驟，請參閱《*IAM Identity Center 使用者指南*[》中的入門教學](https://docs.aws.amazon.com/singlesignon/latest/userguide/tutorials.html)課程。

**注意**  
SAML 身分驗證僅適用於透過 Web 瀏覽器存取 OpenSearch Dashboards。經驗證的使用者只能透過 OpenSearch Dashboards 中的**開發工具**，向 OpenSearch API 操作發出請求。SAML 憑證*不能*讓您對 OpenSearch API 操作發出直接 HTTP 請求。

若要設定 SAML 身分驗證，您應先設定 SAML 身分提供者 (IdP)。然後，您可以將該 IdP 中的一個或多個使用者納入[資料存取政策](serverless-data-access.md)中。此政策會向它授予集合和/或索引的某些許可。然後，使用者可以登入 OpenSearch Dashboards，並執行資料存取政策中允許的動作。

![\[SAML authentication flow with data access policy, OpenSearch interface, and JSON configuration.\]](http://docs.aws.amazon.com/zh_tw/opensearch-service/latest/developerguide/images/serverless-saml-flow.png)


**Topics**
+ [考量事項](#serverless-saml-considerations)
+ [必要許可](#serverless-saml-permissions)
+ [建立 SAML 提供者 (主控台)](#serverless-saml-creating)
+ [存取 OpenSearch Dashboards](#serverless-saml-dashboards)
+ [授予 SAML 身分對集合資料的存取權](#serverless-saml-policies)
+ [建立 SAML 提供者 (AWS CLI)](#serverless-saml-creating-api)
+ [檢視 SAML 提供者](#serverless-saml-viewing)
+ [更新 SAML 提供者](#serverless-saml-updating)
+ [刪除 SAML 提供者](#serverless-saml-deleting)

## 考量事項
<a name="serverless-saml-considerations"></a>

設定 SAML 身分驗證時請考量下列事項：
+ 不支援已簽署和已加密的請求。
+ 不支援已加密的聲明。
+ 不支援 IdP 啟動的身分驗證和登出。
+ 在非 IAM 身分的情況下，服務控制政策 (SCP) 將不適用或評估 （例如 Amazon OpenSearch Serverless & SAML 中的 SAML 和 Amazon OpenSearch Service 的基本內部使用者授權）。

## 必要許可
<a name="serverless-saml-permissions"></a>

OpenSearch Serverless 的 SAML 身分驗證使用下列 AWS Identity and Access Management (IAM) 許可：
+ `aoss:CreateSecurityConfig`：建立 SAML 提供者。
+ `aoss:ListSecurityConfig`：列出目前帳戶中的所有 SAML 提供者。
+ `aoss:GetSecurityConfig`：檢視 SAML 提供者資訊。
+ `aoss:UpdateSecurityConfig`：修改指定的 SAML 提供者組態，包括 XML 中繼資料。
+ `aoss:DeleteSecurityConfig`：刪除 SAML 提供者。

下列身分型存取政策讓使用者可以管理所有 IdP 組態：

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

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Action": [
                "aoss:CreateSecurityConfig",
                "aoss:DeleteSecurityConfig",
                "aoss:GetSecurityConfig",
                "aoss:UpdateSecurityConfig",
                "aoss:ListSecurityConfigs"
            ],
            "Effect": "Allow",
            "Resource": "*"
        }
    ]
}
```

------

請注意，`Resource` 元素必須是萬用字元。

## 建立 SAML 提供者 (主控台)
<a name="serverless-saml-creating"></a>

這些步驟說明如何建立 SAML 提供者。這可透過 OpenSearch Dashboards 的服務提供者 (SP) 啟動的身分驗證來啟用 SAML 身分驗證。不支援 IdP 啟動的身分驗證。

**啟用 OpenSearch Dashboards 的 SAML 身分驗證**

1. 登入 Amazon OpenSearch Service 主控台，網址為 https：//[https://console.aws.amazon.com/aos/home](https://console.aws.amazon.com/aos/home )。

1. 在左側導覽面板上，展開 **Serverless** (無伺服器)，然後選擇 **SAML authentication** (SAML 身分驗證)。

1. 選擇 **Add SAML provider** (新增 SAML 提供者)。

1. 提供提供者的名稱和描述。
**注意**  
您指定的名稱可公開存取，當使用者登入 OpenSearch Dashboards 時，該名稱會出現在下拉式選單中。確保名稱易於識別，並且不會洩露有關您身分提供者的敏感資訊。

1. 在 **Configure your IdP** (設定 IdP) 下，複製聲明消費者服務 (ACS) URL。

1. 使用剛才複製的 ACS URL 來設定身分提供者。術語和步驟因提供者而異。請咨詢供應商文件。

   例如，在 Okta 中，您可以建立「SAML 2.0 Web 應用程式」，並將 ACS URL 指定為 **Single Sign On URL** (單一登入 URL)、**Recipient URL** (收件者 URL) 和 **Destination URL** (目的地 URL)。對於 Auth0，您可以在 **Allowed Callback URLs** (允許的回呼 URL) 中加以指定。

1. 如果 IdP 有此值的欄位，請提供對象限制。對象限制是 SAML 聲明中的一個值，用於指定聲明的對象。使用 OpenSearch Serverless，您可以執行下列動作。請務必使用您自己的 AWS 帳戶 ID 取代下列程式碼範例中*的內容*：

   1. 使用預設對象限制 `:opensearch:111122223333`。

   1. （選用） 使用 設定自訂受眾限制 AWS CLI。如需詳細資訊，請參閱[建立 SAML 提供者 (AWS CLI)](#serverless-saml-creating-api)。

   對象限制欄位的名稱因提供者而異。對於 Okta，該名稱為 **Audience URI (SP Entity ID)** (對象 URI (SP 實體 ID))。對於 IAM 身分中心，該名稱為 **Application SAML audience** (應用程式 SAML 對象)。

1. 如果您使用的是 IAM 身分中心，您還需要指定下列[屬性映射](https://docs.aws.amazon.com/singlesignon/latest/userguide/attributemappingsconcept.html)：`Subject=${user:name}`，格式為 `unspecified`。

1. 設定身分提供者之後，會產生 IdP 中繼資料檔案。此 XML 檔案包含提供者的相關資訊，例如 TLS 憑證、單一登入端點以及身分提供者的實體 ID。

   複製 IdP 中繼資料檔案中的文字，並將其貼到 **Provide metadata from your IdP** (透過 IdP 提供中繼資料) 欄位下方。或者，選擇 **Import from XML file** (從 XML 檔案匯入)，然後上傳檔案。中繼資料檔案如下所示：

   ```
   <?xml version="1.0" encoding="UTF-8"?>
   <md:EntityDescriptor entityID="entity-id" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
     <md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
       <md:KeyDescriptor use="signing">
         <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
           <ds:X509Data>
             <ds:X509Certificate>tls-certificate</ds:X509Certificate>
           </ds:X509Data>
         </ds:KeyInfo>s
       </md:KeyDescriptor>
       <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
       <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
       <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="idp-sso-url"/>
       <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="idp-sso-url"/>
     </md:IDPSSODescriptor>
   </md:EntityDescriptor>
   ```

1. 將**自訂使用者 ID 屬性**欄位保持空白，以針對使用者名稱使用 SAML 聲明的 `NameID`元素。如果您的聲明不使用此標準元素，而是將使用者名稱作為自訂屬性，請在此處指定該屬性。屬性區分大小寫。僅支援單一使用者屬性。

   下列範例顯示 SAML 聲明中 `NameID` 的覆寫屬性：

   ```
   <saml2:Attribute Name="UserId" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
     <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" 
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xsi:type="xs:string">annie</saml2:AttributeValue>
   </saml2:Attribute>
   ```

1. (選用) 在 **Group attribute** (群組屬性) 欄位中指定自訂屬性，例如 `role` 或 `group`。僅支援單一群組屬性。沒有預設的群組屬性。如果未指定群組屬性，資料存取政策只能包含使用者主體。

   下列範例顯示 SAML 聲明中的群組屬性：

   ```
   <saml2:Attribute Name="department" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
       <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" 
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
       xsi:type="xs:string">finance</saml2:AttributeValue>
   </saml2:Attribute>
   ```

1. 依預設，OpenSearch Dashboards 會在 24 小時後將使用者登出。您可以指定 **OpenSearch Dashboards 逾時**，將此值設定為 1 到 12 小時 (15 到 720 分鐘） 之間的任何數字。如果您嘗試將逾時設定為等於或小於 15 分鐘，您的工作階段將重設為一小時。

1. 選擇 **Create SAML provider** (建立 SAML 提供者)。

## 存取 OpenSearch Dashboards
<a name="serverless-saml-dashboards"></a>

設定 SAML 提供者之後，與該提供者相關聯的所有使用者和群組都可以導覽至 OpenSearch Dashboards 端點。Dashboards URL 具有所有集合`collection-endpoint/_dashboards/`的格式。 **

如果您已啟用 SAML，選取 中的連結會 AWS 管理主控台 引導您前往 IdP 選擇頁面，您可以在其中使用您的 SAML 登入資料登入。首先，使用下拉式清單選取身分提供者：

![\[OpenSearch login page with dropdown menu for selecting SAML Identity Provider options.\]](http://docs.aws.amazon.com/zh_tw/opensearch-service/latest/developerguide/images/idpList.png)


然後使用 IdP 憑證登入。

如果您沒有啟用 SAML，選取 中的連結會 AWS 管理主控台 引導您以 IAM 使用者或角色身分登入，沒有 SAML 的選項。

## 授予 SAML 身分對集合資料的存取權
<a name="serverless-saml-policies"></a>

建立 SAML 提供者後，您仍然需要授予基礎使用者和群組對集合內資料的存取權。您可以透過[資料存取政策](serverless-data-access.md)授予存取權。在您提供使用者存取權之前，他們將無法讀取、寫入或刪除集合內的任何資料。

若要授予存取權，請建立資料存取政策，並在 `Principal` 陳述式中指定 SAML 使用者和/或群組 ID：

```
[
   {
      "Rules":[
       ...  
      ],
      "Principal":[
         "saml/987654321098/myprovider/user/Shaheen",
         "saml/987654321098/myprovider/group/finance"
      ]
   }
]
```

您可以授予對集合、索引或兩者的存取權。如果您希望不同的使用者擁有不同的許可，請建立多個規則。如需可用許可的清單，請參閱[支援的政策許可](serverless-data-access.md#serverless-data-supported-permissions)。如需有關如何格式化存取政策的資訊，請參閱[政策語法](serverless-data-access.md)。

## 建立 SAML 提供者 (AWS CLI)
<a name="serverless-saml-creating-api"></a>

若要使用 OpenSearch Serverless API 建立 SAML 提供者，請傳送 [CreateSecurityConfig](https://docs.aws.amazon.com/opensearch-service/latest/ServerlessAPIReference/API_CreateSecurityConfig.html) 請求：

```
aws opensearchserverless create-security-config \
    --name myprovider \
    --type saml \
    --saml-options file://saml-auth0.json
```

將包括中繼資料 XML 在內的 `saml-options` 指定為 .json 檔案中的鍵值映射。必須將中繼資料 XML 編碼為 [JSON 逸出字串](https://www.freeformatter.com/json-escape.html)。

```
{
   "sessionTimeout": 70,
   "groupAttribute": "department",
   "userAttribute": "userid",
   "openSearchServerlessEntityId": "aws:opensearch:111122223333:app1",
   "metadata": "EntityDescriptor xmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\" ... ... ... IDPSSODescriptor\r\n\/EntityDescriptor"
}
```

**注意**  
（選用） 使用 設定自訂受眾限制 AWS CLI。如需詳細資訊，請參閱[建立 SAML 提供者 (AWS CLI)](#serverless-saml-creating-api)。

## 檢視 SAML 提供者
<a name="serverless-saml-viewing"></a>

下列 [ListSecurityConfigs](https://docs.aws.amazon.com/opensearch-service/latest/ServerlessAPIReference/API_ListSecurityConfigs.html) 請求會列出您帳戶中的所有 SAML 提供者：

```
aws opensearchserverless list-security-configs --type saml
```

該請求會傳回所有現有 SAML 提供者的相關資訊，包括身分提供者產生的完整 IdP 中繼資料：

```
{
   "securityConfigDetails": [ 
      { 
         "configVersion": "MTY2NDA1MjY4NDQ5M18x",
         "createdDate": 1664054180858,
         "description": "Example SAML provider",
         "id": "saml/111122223333/myprovider",
         "lastModifiedDate": 1664054180858,
         "samlOptions": { 
            "groupAttribute": "department",
            "metadata": "EntityDescriptorxmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\" ...... ...IDPSSODescriptor\r\n/EntityDescriptor",
            "sessionTimeout": 120,
            "openSearchServerlessEntityId": "aws:opensearch:111122223333:app1",
            "userAttribute": "userid"
         }
      }
   ]
}
```

若要檢視特定提供者的相關詳細資訊 (包括未來更新的 `configVersion`)，請傳送 `GetSecurityConfig` 請求。

## 更新 SAML 提供者
<a name="serverless-saml-updating"></a>

若要使用 OpenSearch Serverless 主控台更新 SAML 提供者，請選擇 **SAML authentication** (SAML 身分驗證)、選取身分提供者，然後選擇 **Edit** (編輯)。您可以修改所有欄位，包括中繼資料和自訂屬性。

若要透過 OpenSearch Serverless API 更新提供者，請傳送 [UpdateSecurityConfig](https://docs.aws.amazon.com/opensearch-service/latest/ServerlessAPIReference/API_UpdateSecurityConfig.html) 請求，並包含要更新之政策的識別符。您還必須包含組態版本，您可以使用 `ListSecurityConfigs` 或 `GetSecurityConfig` 命令擷取該版本。將最新的版本納入其中，可確保您不會意外覆寫其他人所做的變更。

下列請求會更新提供者的 SAML 選項：

```
aws opensearchserverless update-security-config \
    --id saml/123456789012/myprovider \
    --type saml \
    --saml-options file://saml-auth0.json \
    --config-version MTY2NDA1MjY4NDQ5M18x
```

將 SAML 組態選項指定為 .json 檔案中的鍵值映射。

**重要**  
**SAML 選項的更新*不是*遞增處理的**。如果您在進行更新時未指定 `SAMLOptions` 物件中的參數值，則會以空白值覆寫現有值。例如，如果目前的組態包含 `userAttribute` 的值，然後您進行更新但不包含此值，則系統會將該值從組態中移除。透過呼叫 `GetSecurityConfig` 操作進行更新之前，請確保您知道現有值為何。

## 刪除 SAML 提供者
<a name="serverless-saml-deleting"></a>

刪除 SAML 提供者時，對資料存取政策中關聯使用者和群組的任何參考將不再有效。為避免混淆，建議您先移除存取政策中對端點的所有參考，然後再刪除該端點。

若要使用 OpenSearch Serverless 主控台刪除 SAML 提供者，請選擇 **Authentication** (身分驗證)、選取提供者，然後選擇 **Delete** (刪除)。

若要透過 OpenSearch Serverless API 刪除提供者，請傳送 [DeleteSecurityConfig](https://docs.aws.amazon.com/opensearch-service/latest/ServerlessAPIReference/API_DeleteSecurityConfig.html) 請求：

```
aws opensearchserverless delete-security-config --id saml/123456789012/myprovider
```