本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 建立私有人力資源 (OIDC IdP) 您想要使用自己的身份提供者驗證和管理工作者時，請使用 OpenID Connect (OIDC) 身份提供者 (IdP) 建立私有人力資源。使用此頁面了解如何設定 IdP，與 Amazon SageMaker Ground Truth (Ground Truth) 或 Amazon 增強版 AI (Amazon A2I) 通訊，並學習如何使用自己的 IdP 建立人力資源。 若要使用 OIDC IdP 建立人力資源，IdP 必須支援*群組*，因為 Ground Truth 和 Amazon A2I 會使用您指定的一或多個群組建立工作團隊。您可以使用工作團隊為標籤工作和人工審核任務指定工作者。由於群組不是[標準宣告](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims)，因此您的 IdP 針對使用者群組 (工作者) 可能有不同的命名慣例。因此，您必須使用從您的 IdP 傳送至 Ground Truth 或 Amazon A2I 的自訂宣告 `sagemaker:groups`，識別工作者所屬的一或多個使用者群組。如需詳細資訊，請參閱 [將必要和選用申告傳送到 Ground Truth 和 Amazon A2I](#sms-workforce-create-private-oidc-configure-idp)。 您可以使用 SageMaker API 作業 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateWorkforce.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateWorkforce.html) 建立 OIDC IdP 人力資源。建立私有人力資源之後，該人力資源及其相關的所有工作團隊和工作者，將可用於所有 Ground Truth 標籤工作任務和 Amazon A2I 人工審核工作流程任務。如需詳細資訊，請參閱 [建立 OIDC IdP 人力資源](#sms-workforce-create-private-oidc-createworkforce)。 ## 將必要和選用申告傳送到 Ground Truth 和 Amazon A2I 使用自己的 IdP 時，Ground Truth 和 Amazon A2I 會使用您的 `Issuer`、`ClientId` 和 `ClientSecret` 驗證工作者，亦即從您的 `AuthorizationEndpoint` 取得驗證代碼。 Ground Truth 和 Amazon A2I 將使用此代碼從您 IdP 的 `TokenEndpoint` 或 `UserInfoEndpoint` 取得自訂宣告。您可以將 `TokenEndpoint` 設定為回傳 JSON 網頁標記 (JWT)，或將 `UserInfoEndpoint` 設定為回傳 JSON 物件。JWT 或 JSON 物件必須包含您指定的必要和選用宣告。[宣告](https://openid.net/specs/openid-connect-core-1_0.html#Terminology)是鍵值對，其中包含工作者相關資訊，或是 OIDC 服務的相關中繼資料。下表列出了必須包含的宣告，而且 IdP 回傳的 JWT 或 JSON 物件也可以選擇性包含這些宣告。 **注意** 下表中的某些參數可以使用 `:` 或 `-` 指定。例如，您可以在宣告中使用 `sagemaker:groups` 或 `sagemaker-groups` 指定工作者所屬的群組。 | 名稱 | 必要 | 接受的格式和值 | Description | 範例 | | --- | --- | --- | --- | --- | | `sagemaker:groups` 或 `sagemaker-groups` | 是 | **資料類型**： 如果工作者屬於單一群組，請使用字串識別群組。 如果工作者屬於多個群組，請使用最多 10 個字串的清單。 **允許的字元**： 正規表示式：[\$1p\$1L\$1\$1p\$1M\$1\$1p\$1S\$1\$1p\$1N\$1\$1p\$1P\$1]\$1 **配額**： 每名工作者 10 組 每個群組名稱 63 個字元 | 將工作者指派給一個或多個群組。群組可用來將工作者對應至工作團隊。 | 屬於單一群組的工作者範例：`"work_team1"` 屬於一個以上群組的工作者範例：`["work_team1", "work_team2"]` | | `sagemaker:sub` 或 `sagemaker-sub` | 是 | **資料類型**： String | 強制必須追蹤 Ground Truth 平台內的工作者身份進行稽核，也必須識別該工作者工作過的任務。 針對 ADFS：客戶必須使用主要安全性識別碼 (SID)。 | `"111011101-123456789-3687056437-1111"` | | `sagemaker:client_id` 或 `sagemaker-client_id` | 是 | **資料類型**： String **允許的字元**： 正規表示式：[\$1w\$1-]\$1 **引述**： 128 個字元 | 用戶端 ID。所有標記都必須針對此用戶端 ID 發行。 | `"00b600bb-1f00-05d0-bd00-00be00fbd0e0"` | | `sagemaker:name` 或 `sagemaker-name` | 是 | **資料類型**： String | 要在工作者入口網站顯示的工作者名稱。 | `"Jane Doe"` | | `email` | 否 | **資料類型**： String | 工作者電子郵件。Ground Truth 使用此電子郵件通知工作者，他們已獲邀負責標籤任務。如果您為此工作者所屬的工作團隊設定 Amazon SNS 主題，Ground Truth 也會在標籤任務可用時，使用此電子郵件通知您的工作者。 | `"example-email@domain.com"` | | `email_verified` | 否 | **資料類型**： Bool **接受的值**： `True`, `False` | 指出使用者電子郵件是否已驗證。 | `True` | 下面是您的 `UserInfoEndpoint` 可以回傳之 JSON 物件語法的範例。 ``` { "sub":"122", "exp":"10000", "sagemaker-groups":["group1","group2"] "sagemaker-name":"name", "sagemaker-sub":"122", "sagemaker-client_id":"123456" } ``` Ground Truth 或 Amazon A2I 會比較 `sagemaker:groups` 或 `sagemaker-groups` 列出的群組，確認您的工作者屬於標籤工作或人工審核任務指定的工作團隊。驗證工作團隊後，會將標籤或人工審核任務傳送給該工作者。 ## 建立 OIDC IdP 人力資源 您可以使用 SageMaker API 作業 `CreateWorkforce` 和關聯的特定語言 SDK 建立人力資源。在參數 `OidcConfig` 指定 `WorkforceName` 和 OIDC IDP 相關資訊。建議您使用預留位置重新導向 URI 設定 OIDC，然後在建立人力資源之後，使用工作者入口網站 URL 更新 URI。如需詳細資訊，請參閱 [設定 OIDC IdP](#sms-workforce-create-private-oidc-configure-url)。 請求範例如下所示。請參閱 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateWorkforce.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateWorkforce.html)，進一步了解有關此請求中的每個參數。 ``` CreateWorkforceRequest: { #required fields WorkforceName: "example-oidc-workforce", OidcConfig: { ClientId: "clientId", ClientSecret: "secret", Issuer: "https://example-oidc-idp.com/adfs", AuthorizationEndpoint: "https://example-oidc-idp.com/adfs/oauth2/authorize", TokenEndpoint: "https://example-oidc-idp.com/adfs/oauth2/token", UserInfoEndpoint: "https://example-oidc-idp.com/adfs/oauth2/userInfo", LogoutEndpoint: "https://example-oidc-idp.com/adfs/oauth2/log-out", JwksUri: "https://example-oidc-idp.com/adfs/discovery/keys" }, SourceIpConfig: { Cidrs: ["string", "string"] } } ``` ### 設定 OIDC IdP 如何設定 OIDC IdP 取決於您使用的 IdP 以及您的業務需求。 設定 IdP 時，您必須指定回呼或重新導向 URI。Ground Truth 或 Amazon A2I 驗證工作者之後，此 URI 會將工作者重新導向至工作者入口網站，工作者可以在這裡存取標籤或人工審核任務。若要建立工作者入口網站 URL，您必須使用 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateWorkforce.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateWorkforce.html) API 作業，建立有 OIDC IdP 詳細資料的人力資源。具體來說，您必須使用必要的自訂 SageMaker 宣告設定 OIDC IdP (如需詳細資訊，請參閱下一節)。因此，建議您使用預留位置重新導向 URI 設定 OIDC，然後在建立人力資源之後更新 URI。請參閱[建立 OIDC IdP 人力資源](#sms-workforce-create-private-oidc-createworkforce)，了解如何使用這個 API 建立人力資源。 您可以在 SageMaker Ground Truth 主控台檢視您的工作者入口網站 URL，或使用 SageMaker API 作業 `DescribeWorkforce`。工作者入口網站 URL 位於回應中的 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_Workforce.html#sagemaker-Type-Workforce-SubDomain](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_Workforce.html#sagemaker-Type-Workforce-SubDomain) 參數中。 **重要** 請務必將人力資源子網域新增至您的 OIDC IdP 允許清單。將子網域新增至允許清單時，該網域必須以結尾 `/oauth2/idpresponse`。 **若要在建立私有人力資源 (主控台) 之後檢視您的工作者入口網站 URL：** 1. 開啟位在 [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/) 的 SageMaker AI 主控台。 1. 在瀏覽窗格中，選擇**標籤人力資源**。 1. 選取 **Private (私有)** 索引標籤。 1. 在**私有人力資源摘要**中，您會看到**標籤入口網站登入 URL**。這是您的工作者入口網站 URL。 **若要在建立私有人力資源 (API) 之後檢視您的工作者入口網站 URL：** 使用 `[CreateWorkforce](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateWorkforce.html)` 建立私有人力資源時，請指定 `WorkforceName`。使用此名稱呼叫 [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeWorkforce.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeWorkforce.html)。下表包含使用 AWS CLI 和 的請求範例 適用於 Python (Boto3) 的 AWS SDK。 ------ #### [ SDK for Python (Boto3) ] ``` response = client.describe_workforce(WorkforceName='string') print(f'The workforce subdomain is: {response['SubDomain']}') ``` ------ #### [ AWS CLI ] ``` $ C:\> describe-workforce --workforce-name 'string' ``` ------ ## 驗證您的 OIDC IdP 人力資源驗證回應 建立 OIDC IdP 人力資源之後，您可以使用下列程序以 cURL 驗證其身份驗證工作流程。此程序假設您可以存取終端機，並且已安裝 cURL。 **若要驗證您的 OIDC IdP 授權回應：** 1. 使用下列設定方式的 URI 取得授權碼： ``` {AUTHORIZE ENDPOINT}?client_id={CLIENT ID}&redirect_uri={REDIRECT URI}&scope={SCOPE}&response_type=code ``` 1. 以 OIDC IdP 的授權端點取代 *`{AUTHORIZE ENDPOINT}`*。 1. 以 OAuth 用戶端的用戶端 ID 取代 `{CLIENT ID}`。 1. 以工作者入口網站 URL 取代 *`{REDIRECT URI}`*。如果它不存在，則必須將 `/oauth2/idpresponse` 加到 URL 結尾。 1. 如果您有自訂範圍，請使用它取代 `{SCOPE}`。如果您沒有自訂範圍，請使用 `openid` 取代 `{SCOPE}`。 以下是進行上述修改之後的 URI 範例： ``` https://example.com/authorize?client_id=f490a907-9bf1-4471-97aa-6bfd159f81ac&redirect_uri=https%3A%2F%2F%2Fexample.labeling.sagemaker.aws%2Foauth2%2Fidpresponse&response_type=code&scope=openid ``` 1. 將步驟 1 中修改的 URI 複製並貼到瀏覽器中，然後按鍵盤上的 Enter 鍵。 1. 使用您的 IdP 進行驗證。 1. 複製 URI 中的驗證碼查詢參數。此參數開頭是 `code=`。以下為回應可能形式的範例。在此範例中，複製 `code=MCNYDB...` 以及之後的所有內容。 ``` https://example.labeling.sagemaker.aws/oauth2/idpresponse?code=MCNYDB.... ``` 1. 在進行下列必要修改後，開啟終端機並輸入以下指令： ``` curl --request POST \ --url '{TOKEN ENDPOINT}' \ --header 'content-type: application/x-www-form-urlencoded' \ --data grant_type=authorization_code \ --data 'client_id={CLIENT ID}' \ --data client_secret={CLIENT SECRET} \ --data code={CODE} \ --data 'redirect_uri={REDIRECT URI}' ``` 1. 以 OIDC IdP 的記號端點取代 `{TOKEN ENDPOINT}`。 1. 以 OAuth 用戶端的用戶端 ID 取代 `{CLIENT ID}`。 1. 使用 OAuth 用戶端的用戶端密碼取代 `{CLIENT SECRET}`。 1. 以您在步驟 4 中複製的驗證碼查詢參數取代 `{CODE}`。 1. 以工作者入口網站 URL 取代 *`{REDIRECT URI}`*。 以下是進行上述修改後 cURL 請求的範例： ``` curl --request POST \ --url 'https://example.com/token' \ --header 'content-type: application/x-www-form-urlencoded' \ --data grant_type=authorization_code \ --data 'client_id=f490a907-9bf1-4471-97aa-6bfd159f81ac' \ --data client_secret=client-secret \ --data code=MCNYDB... \ --data 'redirect_uri=https://example.labeling.sagemaker.aws/oauth2/idpresponse' ``` 1. 此步驟取決於 IdP 回傳的 `access_token` 類型，是純文字存取權杖或 JWT 存取權杖。 + 如果您的 IdP 不支援 JWT 存取權杖，`access_token` 可能是純文字 (例如 UUID)。您會看到類似下方的回應。這樣的話，請移至步驟 7。 ``` { "access_token":"179c144b-fccb-4d96-a28f-eea060f39c13", "token_type":"Bearer", "expires_in":3600, "refresh_token":"ef43e52e-9b4f-410c-8d4c-d5c5ee57631a", "scope":"openid" } ``` + 如果您的 IdP 支援 JWT 存取權杖，則步驟 5 應產生 JWT 格式的存取權杖。舉例而言，回應形式可能如下： ``` { "access_token":"eyJh...JV_adQssw5c", "refresh_token":"i6mapTIAVSp2oJkgUnCACKKfZxt_H5MBLiqcybBBd04", "refresh_token_expires_in":6327, "scope":"openid", "id_token":"eyJ0eXAiOiJK9...-rDaQzUHl6cQQWNiDpWOl_lxXjQEvQ" } ``` 複製 JWT 並將它解碼。您可以使用 python 指令碼或第三方網站將它解碼。例如，您可以前往網站 [https://jwt.io/](https://jwt.io/)，將 JWT 貼到**編碼**方塊中將它解碼。 確定解碼的回應包含以下內容： + 在 [將必要和選用申告傳送到 Ground Truth 和 Amazon A2I](#sms-workforce-create-private-oidc-configure-idp) 找到之表格中的**必要** SageMaker AI 宣告。如果沒有，您必須重新設定 OIDC IdP，包含這些宣告。 + 您在設定 IdP 人力資源時指定的[發行者](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_OidcConfig.html#sagemaker-Type-OidcConfig-Issuer)。 1. 在終端機中，並在進行下列必要修改後輸入以下命令： ``` curl -X POST -H 'Authorization: Bearer {ACCESS TOKEN}' -d '' -k -v {USERINFO ENDPOINT} ``` 1. 以 OIDC IdP 的使用者資訊端點取代 `{USERINFO ENDPOINT}`。 1. 以您在步驟 7 收到之回應中的存取權杖取代 `{ACCESS TOKEN}`。這是 `"access_token"` 參數的項目。 以下是進行上述修改後 cURL 請求的範例： ``` curl -X POST -H 'Authorization: Bearer eyJ0eX...' -d '' -k -v https://example.com/userinfo ``` 1. 上述程序中最後一個步驟的回應，形式可能與下列程式碼區塊類似。 如果步驟 6 回傳的 `access_token` 是純文字，您必須驗證此回應是否包含必要的資訊。在此情況下，回應必須包含在 [將必要和選用申告傳送到 Ground Truth 和 Amazon A2I](#sms-workforce-create-private-oidc-configure-idp) 找到之表格中的**必要** SageMaker AI 宣告。例如 `sagemaker-groups` 和 `sagamaker-name`。 ``` { "sub":"122", "exp":"10000", "sagemaker-groups":["group1","group2"] "sagemaker-name":"name", "sagemaker-sub":"122", "sagemaker-client_id":"123456" } ``` ## 後續步驟 使用 IdP 建立私有人力資源並確認 IdP 驗證回應後，您就可以使用 IdP 群組建立工作團隊。如需詳細資訊，請參閱 [管理私有人力資源 (OIDC IdP)](sms-workforce-manage-private-oidc.md)。 您可以限制工作者對特定 IP 位址的任務存取權限，還可使用 SageMaker API 更新或刪除人力資源。如需進一步了解，請參閱[使用 Amazon SageMaker API 管理私有人力資源](sms-workforce-management-private-api.md)。