翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# プライベートワークフォースを作成する (OIDC IdP)
<a name="sms-workforce-create-private-oidc"></a>

独自の ID プロバイダーを使用してワーカーを認証および管理する場合は、OpenID Connect (OIDC) ID プロバイダー (IdP) を使用してプライベートワーカーを作成します。このページを使用して、Amazon SageMaker Ground Truth (Ground Truth) または Amazon Augmented AI (Amazon A2I) と通信するように IdP を設定する方法と、独自の IdP を使用してワークフォースを作成する方法を学びます。

OIDC IdP を使用して従業員を作成するには、IdP が*グループ*をサポートしている必要があります。Ground Truth と Amazon A2I が作業チームを作成するために、指定した 1 つ以上のグループを使用するためです。作業チームを使用して、ラベル付けジョブと人間によるレビュータスクのワーカーを指定します。グループが[スタンダードクレーム](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims)ではないため、IdP に、ユーザー (ワーカー) のグループに対する異なる命名規則がある場合があります。そのため、IdP からGround Truth または Amazon A2I に送信されるカスタムのクレーム `sagemaker:groups` を使用して、ワーカーが属する 1 つ以上のユーザーグループを特定する必要があります。詳細については、「[必須およびオプションのクレームを 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 に送信する
<a name="sms-workforce-create-private-oidc-configure-idp"></a>

独自の 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` を使用して、ワーカーが属するグループを指定できます。


|  名前  | 必須 | 受け入れられるフォーマットと値 | 説明 | 例 | 
| --- | --- | --- | --- | --- | 
| `sagemaker:groups` または `sagemaker-groups` | はい | **データ型**:<br />ワーカーが単一のグループに属している場合は、文字列を使用してグループを特定します。<br />ワーカーが複数のグループに属している場合は、最大 10 個の文字列のリストを使用します。<br />**使用できる文字**:<br />正規表現: [\\p{L}\\p{M}\\p{S}\\p{N}\\p{P}]\+<br />**クォータ**:<br />ワーカーにつき 10 グループ<br />グループ名あたり 63 文字 | ワーカーを 1 つ以上のグループに割り当てます。グループは、ワーカーを作業チームにマッピングするために使用されます。 | 1 つのグループに属するワーカーの例: `"work_team1"`<br />複数のグループに属するワーカーの例: `["work_team1", "work_team2"]`  | 
| `sagemaker:sub` または `sagemaker-sub` | はい | **データ型**:<br />String | これは、監査のために Ground Truth プラットフォーム内でワーカー ID を追跡し、そのワーカーによって処理されたタスクを特定するために必須です。<br />ADFS の場合: お客様は、プライマリセキュリティ識別子 (SID) を使用する必要があります。 | `"111011101-123456789-3687056437-1111"` | 
| `sagemaker:client_id` または `sagemaker-client_id` | はい | **データ型**:<br />String<br />**使用できる文字**:<br />正規表現: [\\w\+-]\+<br />**クォータ**:<br />128 文字  | クライアント ID。このクライアント ID に対してすべてのトークンを発行する必要があります。 | `"00b600bb-1f00-05d0-bd00-00be00fbd0e0"` | 
| `sagemaker:name` または `sagemaker-name` | はい | **データ型**:<br />String | ワーカーポータルに表示されるワーカー名。 | `"Jane Doe"` | 
| `email` | いいえ | **データ型**:<br />String | ワーカーのメール。Ground Truth は、このメールを使用して、ラベル付けタスクの作業に招待されたことをワーカーに通知します。Ground Truth は、このワーカーがいる作業チームの Amazon SNS トピックを設定する場合に、ラベル付けタスクが利用可能になったことをワーカーに通知するためにも、このメールを使用します。 | `"example-email@domain.com"` | 
| `email_verified` | いいえ | **データ型**:<br />Bool<br />**使用できる値**:<br />`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 ワークフォースを作成する
<a name="sms-workforce-create-private-oidc-createworkforce"></a>

SageMaker API オペレーション `CreateWorkforce` と関連する言語固有の SDK を使用してワークフォースを作成できます。`WorkforceName` とパラメータ `OidcConfig` 内の 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 を設定する
<a name="sms-workforce-create-private-oidc-configure-url"></a>

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 を更新することをお勧めします。この API を使用してワークフォースを作成する方法については、「[OIDC IdP ワークフォースを作成する](#sms-workforce-create-private-oidc-createworkforce)」を参照してください。

ワーカーポータル URL は SageMaker Ground Truth コンソールで、または 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. SageMaker AI コンソール ([https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/)) を開きます。

1. ナビゲーションペインで、**[Labeling workforces]** (ラベル付けワークフォース) を選択します。

1. **[Private]** タブを選択します。

1. **プライベートワークフォースの概要**に、**ラベル付けポータルのサインイン URL** があります。これが、ワーカーポータル URL です。

**プライベートワークフォース (API) を作成した後にワーカーポータル URL を表示するには、次の手順に従います (API)。**

`[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 および を使用したリクエストの例を示します AWS SDK for Python (Boto3)。

------
#### [ 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 ワークフォース認証レスポンスを検証する
<a name="sms-workforce-create-private-oidc-validate"></a>

OIDC IdP ワークフォースを作成したら、次の手順に従って、cURL を使用して認証ワークフローを検証できます。この手順では、ターミナルへのアクセス権があり、cURL がインストールされていることを前提としています。

**OIDC IdP 認可レスポンスを検証するには、次の手順を実行します。**

1. 次のように構成された URI を使用して認可コードを取得します。

   ```
   {{{AUTHORIZE ENDPOINT}}}?client_id={{{CLIENT ID}}}&redirect_uri={{{REDIRECT URI}}}&scope={{{SCOPE}}}&response_type=code
   ```

   1. {{`{AUTHORIZE ENDPOINT}`}} を、OIDC IdP の認可エンドポイントに置き換えます。

   1. `{{{CLIENT ID}}}` を、OAuth クライアントのクライアント ID に置き換えます。

   1. {{`{REDIRECT URI}`}} を、ワーカーポータル URL に置き換えます。存在しない場合は、URL の末尾に `/oauth2/idpresponse` を追加する必要があります。

   1. カスタムスコープがある場合は、それを `{{{SCOPE}}}` に置き換えます。カスタムスコープがない場合は、`{{{SCOPE}}}` を `openid` で置き換えます。

   以下は、上記の変更が行われた後の 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. `{{{TOKEN ENDPOINT}}}` を、OIDC IdP のトークンエンドポイントに置き換えます。

   1. `{{{CLIENT ID}}}` を、OAuth クライアントのクライアント ID に置き換えます。

   1. `{{{CLIENT SECRET}}}` を、OAuth クライアントからのクライアントシークレットに置き換えます。

   1. `{{{CODE}}}` を、ステップ 4 でコピーした認証コードクエリパラメータに置き換えます。

   1. {{`{REDIRECT URI}`}} を、ワーカーポータル URL に置き換えます。

   以下に、上記の変更を加えた後の 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 を **[Encoded]** (エンコード済み) ボックスに貼り付けてデコードします。

     デコードされたレスポンスに以下が含まれていることを確認します。
     + **必須**の SageMaker AI クレーム ([必須およびオプションのクレームを Ground Truth と Amazon A2I に送信する](#sms-workforce-create-private-oidc-configure-idp) にある表)。含まれていない場合は、これらのクレームを含めるように 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. `{{{USERINFO ENDPOINT}}}` を、OIDC IdP のユーザー情報エンドポイントに置き換えます。

   1. `{{{ACCESS TOKEN}}}` を、ステップ 7 で受信したレスポンスにアクセストークンに置き換えます。これは、`"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"
   }
   ```

## 次のステップ
<a name="sms-workforce-create-private-oidc-next-steps"></a>

IdP を使用してプライベートワークフォースを作成し、IdP 認証レスポンスを確認したら、IdP グループを使用してワークチームを作成できます。詳細については[プライベートワークフォースを管理する (OIDC IdP)](sms-workforce-manage-private-oidc.md)を参照してください。

タスクへのワーカーアクセスを特定の IP アドレスに制限し、SageMaker API を使用してワークフォースを更新または削除できます。詳細については[Amazon SageMaker API を使用したプライベートワークフォース管理](sms-workforce-management-private-api.md)を参照してください。