Create a Private Workforce (OIDC IdP) - Amazon SageMaker

Create a Private Workforce (OIDC IdP)

Create a private workforce using an OpenID Connect (OIDC) Identity Provider (IdP) when you want to authenticate and manage workers using your own identity provider. Use this page to learn how to configure your IdP to communicate with Amazon SageMaker Ground Truth (Ground Truth) or Amazon Augmented AI (Amazon A2I) and to learn how to create a workforce using your own IdP.

To create a workforce using an OIDC IdP, your IdP must support groups because Ground Truth and Amazon A2I use one or more groups that you specify to create work teams. You use work teams to specify workers for your labeling jobs and human review tasks. Because groups are not a standard claim, your IdP may have a different naming convention for a group of users (workers). Therefore, you must identify one or more user groups to which a worker belongs using the custom claim sagemaker:groups that is sent to Ground Truth or Amazon A2I from your IdP. To learn more, see Send Required and Optional Claims to Ground Truth and Amazon A2I.

You create an OIDC IdP workforce using the SageMaker API operation CreateWorkforce. Once you create a private workforce, that workforce and all work teams and workers associated with it are available to use for all Ground Truth labeling job tasks and Amazon A2I human review workflows tasks. To learn more, see Create an OIDC IdP Workforce.

Configure your OIDC IdP

How you configure your OIDC IdP depends on the IdP you use, and your business requirements.

When you configure your IdP, you must to specify a callback or redirect URI. After Ground Truth or Amazon A2I authenticates a worker, this URI will redirect the worker to the worker portal where the workers can access labeling or human review tasks. To create a worker portal URL, you need to create a workforce with your OIDC IdP details using the CreateWorkforce API operation. Specifically, you must configure your OIDC IdP with required custom sagemaker claims (see the next section for more details). Therefore, it is recommended that you configure your OIDC with a place-holder redirect URI, and then update the URI after you create the workforce. See Create an OIDC IdP Workforce to learn how to create a workforce using this API.

You can view your worker portal URL in the SageMaker Ground Truth console, or using the SageMaker API operation, DescribeWorkforce. The worker portal URL is in the SubDomain parameter in the response.


Make sure you add the workforce subdomain to your OIDC IdP allow list.

To view your worker portal URL after creating a private workforce (Console):

  1. Open the SageMaker console at

  2. In the navigation pane, choose Labeling workforces.

  3. Select the Private tab.

  4. In Private workforce summary you will see Labeling portal sign-in URL. This is your worker portal URL.

To view your worker portal URL after creating a private workforce (API):

When you create a private workforce using CreateWorkforce, you specify a WorkforceName. Use this name to call DescribeWorkforce. The following table includes examples of requests using the AWS CLI and AWS SDK for Python (Boto3).

SDK for Python (Boto3)
response = client.describe_workforce(WorkforceName='string') print(f'The workforce subdomain is: {response['SubDomain']}')
$ C:\> describe-workforce --workforce-name 'string'

Send Required and Optional Claims to Ground Truth and Amazon A2I

When you use your own IdP, Ground Truth and Amazon A2I use your Issuer, ClientId, and ClientSecret to authenticate workers by obtaining an authentication CODE from your AuthorizationEndpoint.

Ground Truth and Amazon A2I will use this CODE to obtain a custom claim from either your IdP's TokenEndpoint or UserInfoEndpoint. You can either configure TokenEndpoint to return a JSON web token (JWT) or UserInfoEndpoint to return a JSON object. The JWT or JSON object must contain required and optional claims that you specify. A claim is a key-value pair that contains information about a worker or metadata about the OIDC service. The following table lists the claims that must be included, and that can optionally be included in the JWT or JSON object that your IdP returns.


Some of the parameters in the following table can be specified using a : or a -. For example, you can specify the groups a worker belongs to using sagemaker:groups or sagemaker-groups in your claim.

Name Required Accepted Format and Values Description Example

sagemaker:groups or sagemaker-groups


Data type:

If a worker belongs to a single group, identify the group using a string.

If a worker belongs to multiple groups, use a list of up to 10 strings.

Allowable characters:

Regex: [\p{L}\p{M}\p{S}\p{N}\p{P}]+


10 groups per worker

63 characters per group name

Assigns a worker to one or more groups. Groups are used to map the worker into work teams.

Example of worker that belongs to a single group: "work_team1"

Example of a worker that belongs to more than one groups: ["work_team1", "work_team2"]

sagemaker:sub or sagemaker-sub


Data type:


This is mandatory to track a worker identity inside the Ground Truth platform for auditing and to identify tasks worked on by that worker.

For ADFS: Customers must use the Primary Security Identifier (SID).


sagemaker:client_id or sagemaker-client_id


Data type:


Allowable characters:

Regex: [\w+-]+


128 characters

A client ID. All tokens must be issued for this client ID.


sagemaker:name or sagemaker-name


Data type:


The worker name to be displayed in the worker portal.

"Jane Doe"



Data type:


The worker email. Ground Truth uses this email to notify workers that they have been invited to work on labeling tasks. Ground Truth will also use this email to notify your workers when labeling tasks become available if you set up an Amazon SNS topic for a work team that this worker is on.




Data type:


Accepted Values:

True, False

Indicates if the user email was verified or not.


The following an example of the JSON object syntax your UserInfoEndpoint can return.

{ "sub":"122", "exp":"10000", "sagemaker-groups":["group1","group2"] "sagamaker-name":"name", "sagemkaer-sub":"122", "sagemaker-client_id":"123456" }

Ground Truth or Amazon A2I compares the groups listed in sagemaker:groups or sagemaker-groups to verify that your worker belongs to the work team specified in the labeling job or human review task. After the work team has been verified, labeling or human review tasks are sent to that worker.

Create an OIDC IdP Workforce

You can create a workforce using the SageMaker API operation CreateWorkforce and associated language-specific SDKs. Specify a WorkforceName and information about your OIDC IDP in the parameter OidcConfig. The following shows an example of the request. See CreateWorkforce to learn more about each parameter in this request.

CreateWorkforceRequest: { #required fields WorkforceName: "example-oidc-workforce", OidcConfig: { ClientId: "clientId", ClientSecret: "secret", Issuer: "", AuthorizationEndpoint: "", TokenEndpoint: "", UserInfoEndpoint: "", LogoutEndpoint: "", JwksUri: "" }, SourceIpConfig: { Cidrs: ["string", "string"] } }

Next Steps

After you create your OIDC IdP, make sure you add the workforce subdomain to your OIDC IdP allow list.

Once you've created a private workforce using your IdP, you can create work teams using your IdP groups. To learn more, see Manage a Private Workforce (OIDC IdP).

You can restrict worker access to tasks to specific IP addresses, and update or delete your workforce using the SageMaker API. To learn more, see Manage Private Workforce Using the Amazon SageMaker API.