Configure Amazon Q Enterprise with AWS IAM Identification Heart trusted id propagation

Amazon Q Enterprise is a completely managed, permission conscious generative synthetic intelligence (AI)-powered assistant constructed with enterprise grade safety and privateness options. Amazon Q Enterprise may be configured to reply questions, present summaries, generate content material, and securely full duties based mostly in your enterprise information. The native information supply connectors offered by Amazon Q Enterprise can seamlessly combine and index content material from a number of repositories right into a unified index. Amazon Q Enterprise makes use of AWS IAM Identification Heart to document the workforce customers you assign entry to and their attributes, reminiscent of group associations. IAM Identification Heart is utilized by many AWS managed purposes reminiscent of Amazon Q. You join your current supply of identities to Identification Heart as soon as and may then assign customers to any of those AWS companies. As a result of Identification Heart serves as their widespread reference of your customers and teams, these AWS purposes can provide your customers a constant expertise as they navigate AWS. For instance, it permits consumer subscription administration throughout Amazon Q choices and consolidates Amazon Q billing from throughout a number of AWS accounts. Moreover, Q Enterprise dialog APIs make use of a layer of privateness safety by leveraging trusted id propagation enabled by IAM Identification Heart.

Amazon Q Enterprise comes with wealthy API help to carry out administrative duties or to construct an AI-assistant with custom-made consumer expertise to your enterprise. With administrative APIs you’ll be able to automate creating Q Enterprise purposes, arrange information supply connectors, construct customized doc enrichment, and configure guardrails. With dialog APIs, you’ll be able to chat and handle conversations with Q Enterprise AI assistant. Trusted id propagation supplies authorization based mostly on consumer context, which boosts the privateness controls of Amazon Q Enterprise.

On this weblog submit, you’ll be taught what trusted id propagation is and why to make use of it, automate configuration of a trusted token issuer in AWS IAM Identification Heart with offered AWS CloudFormation templates, and what APIs to invoke out of your software facilitate calling Amazon Q Enterprise identity-aware dialog APIs.

Why use trusted id propagation?

Trusted id propagation supplies a mechanism that allows purposes that authenticate exterior of AWS to make requests on behalf of their customers with the usage of a trusted token issuer. Contemplate a client-server software that makes use of an exterior id supplier (IdP) to authenticate a consumer to supply entry to an AWS useful resource that’s personal to the consumer. For instance, your net software would possibly use Okta as an exterior IdP to authenticate a consumer to view their personal conversations from Q Enterprise. On this situation, Q Enterprise is unable to make use of the id token generated by the third occasion supplier to supply direct entry to the consumer’s personal information since there isn’t any mechanism to belief the id token issued by the third occasion.

To unravel this, you should utilize IAM Identification Heart to get the consumer id out of your exterior IdP into an AWS Identification and Entry Administration (IAM) position session which lets you authorize requests based mostly on the human, their attributes, and their group memberships, quite than arrange fine-grained permissions in an IAM coverage. You possibly can alternate the token issued by the exterior IdP for a token generated by Identification Heart. The token generated by Identification Heart refers back to the corresponding Identification Heart consumer. The online software can now use the brand new token to provoke a request to Q Enterprise for the personal chat dialog. That token refers back to the corresponding consumer in Identification Heart, Q Enterprise can authorize the requested entry to the personal dialog based mostly on the consumer or their group membership as represented in Identification Heart.

Among the advantages of utilizing trusted id propagation are:

• Prevents consumer impersonation and protects in opposition to unauthorized entry to consumer personal information by spoofing consumer id.
• Facilitates auditability and fosters accountable use of sources as Q Enterprise mechanically logs API invocations to AWS CloudTrail together with consumer identifier.
• Promotes software program design ideas rooted in consumer privateness.

Overview of trusted id propagation deployment

The next determine is a mannequin of a client-server structure for trusted id propagation.

To grasp how your software may be built-in with IAM Identification Heart for trusted id propagation, think about the mannequin client-server net software proven within the previous determine. On this mannequin structure, the online browser represents the consumer interface to your software. This might be an internet web page rendered on an internet browser, Slack, Microsoft Groups, or different purposes. The appliance server is likely to be an internet server working on Amazon Elastic Container Service (Amazon ECS), or a Slack or Microsoft Groups gateway carried out with AWS Lambda. Identification Heart itself is likely to be deployed on a delegated admin account or Identification Heart (the Identification Account within the previous determine), or might be deployed in the identical AWS account (the Software Account within the previous determine) the place the appliance server is deployed together with Amazon Q Enterprise. Lastly, you’ve an OAuth 2.0 OpenID Join (OIDC) exterior IdP reminiscent of Okta, Ping One, Microsoft Entra ID, or Amazon Cognito for authenticating and authorizing.

Deployment of trusted id propagation includes 5 steps. As a finest follow, we advocate that the safety proprietor manages IAM Identification Heart updates and the software proprietor manages software updates, offering clear separation of duties. The safety proprietor is liable for administering the Identification Heart of a corporation or account. The appliance proprietor is liable for creating an software on AWS.

1. The safety proprietor provides the exterior OIDC IdP’s issuer URL to the IAM Identification Heart occasion’s trusted token issuer. It’s vital that the issuer URL matches the iss declare attribute current within the JSON Net Token (JWT) id token generated by the IdP after consumer authentication. That is configured as soon as for a given issuer URL.
2. The safety proprietor creates a buyer managed id supplier software in IAM Identification Heart and explicitly configures the particular viewers for a given trusted token issuer is being licensed to carry out token alternate utilizing Identification Heart. As a result of there might be multiple software (or viewers) for which the exterior IdP might be authenticating customers, explicitly specifying an viewers helps forestall an unauthorized purposes from utilizing the token alternate course of. It’s vital the viewers ID matches the aud declare attribute current within the JWT id token generated by the IdP after consumer authentication.
3. The safety proprietor edits the appliance coverage for the buyer managed id supplier software created within the earlier step so as to add or replace the IAM execution position utilized by the appliance server or AWS Lambda. This helps forestall any unapproved customers or purposes from invoking the CreateTokenWithIAM API in Identification Heart to provoke the token alternate.
4. The appliance proprietor creates and provides an IAM coverage to the appliance execution position to permit the appliance to invoke a CreateTokenWithIAM API on Identification Heart to carry out a token alternate and to create non permanent credentials utilizing AWS Safety Token Service (AWS STS) .
5. The appliance proprietor creates an IAM position with a coverage permitting entry to the Q Enterprise Dialog API to be used with STS to create a short lived credential to invoke Q Enterprise APIs.

You should use AWS CloudFormation templates, mentioned later on this weblog, to automate the previous deployment steps. See the IAM Identification Heart documentation for detailed step-by-step directions on organising trusted id propagation. You may as well use the AWS Command Line Interface (AWS CLI) setup course of in Making authenticated Amazon Q Enterprise API calls utilizing IAM Identification Heart.

Vital: Selecting so as to add a trusted token issuer is a safety choice that requires cautious consideration. Solely select trusted token issuers that you simply belief to carry out the next duties:

• Authenticate the consumer who’s specified within the token. Management the viewers declare, a declare you configure because the consumer identifier.
• Generate a token that IAM Identification Heart can alternate for an Identification Heart-created token. Management the Identification Heart buyer managed software coverage so as to add solely IAM customers, roles, and execution roles that may carry out the alternate.

Authorization stream

For a typical net software, the trusted id propagation course of will contain 5 steps as proven within the following stream diagram.

1. Signal-in and procure an authorization code from the IdP.
2. Use the authorization code and shopper secret to retrieve the ID token from the IdP.
3. Change the IdP generated JWT ID token with the IAM Identification Heart token that features the AWS STS context id.
4. Use the STS context id to acquire non permanent entry credentials from AWS STS.
5. Use non permanent entry credentials to entry Q Enterprise APIs.

An end-to-end implementation of the id propagation is accessible for reference in /webapp/foremost.py of AWS Samples – foremost.py.

Pattern JWT tokens

Within the previous authorization stream, one of many key steps is step 3, the place the JWT ID token from the OAuth IdP is exchanged with IAM Identification Heart for an AWS identity-aware JWT token. Key attributes of the respective JWT tokens are explored within the subsequent part. An understanding of the tokens will assist with troubleshooting authorization stream errors.

OpenID Join JWT ID token

A pattern JWT ID token generated by an OIDC OAuth IdP is proven within the following code pattern. OIDC’s ID tokens take the type of a JWT, which is a JSON payload that’s signed with the personal key of the issuer and may be parsed and verified by the appliance. In distinction to entry tokens, ID tokens are supposed to be understood by the OAuth shopper and embody a handful of outlined property names that present data to the appliance. Vital properties embody aud, e mail, iss, and jti, that are utilized by IAM Identification Heart to validate the token issuer, match the consumer listing, and challenge a brand new Identification Heart token. The next code pattern exhibits a JWT id token issued by an OIDC exterior IdP (reminiscent of Okta).

{
    'amr': ['pwd'],
    'at_hash': '3fMsKeFGoem************',
    'aud': '0oae4epmqqa************',
    'auth_time': 1715792363,
    'e mail': 'john_doe@******.com',
    'exp': 1715795964,
    'iat': 1715792364,
    'idp': '00oe36vc7kj7************',
    'iss': 'https://*******.okta.com/oauth2/default',
    'jti': 'ID.7l6jFX3KO9M7***********************',
    'title': 'John Doe',
    'nonce': 'SampleNonce',
    'preferred_username': 'john_doe@******.com',
    'sub': '00ue36ou4gCv************',
    'ver': 1
}

IAM Identification Heart JWT token with id context

A pattern JWT token generated by CreateTokenWithIAM is proven within the following code pattern. This token features a property known as sts:identity_context which lets you create an identity-enhanced IAM position session utilizing an AWS STS AssumeRole API. The improved STS session permits the receiving AWS service to authorize the IAM Identification Heart consumer to carry out an motion and log the consumer id to CloudTrail for auditing.

{
    'act':{
        'sub': 'arn:aws:sso::*********:trustedTokenIssuer/ssoins-*********/74******-7***-7***-d***-fd9*********'
    },
    'aud': 'BTHY************-c9Ed3V************',
    'auth_time': '2024-05-15T16:59:27Z',
    'aws:application_arn': 'arn:aws:sso::************:software/ssoins-************/apl-************',
    'aws:credential_id': 'AAAAAGZE9_8Y******_Zj******',
    'aws:identity_store_arn': 'arn:aws:identitystore::************:identitystore/d-**********',
    'aws:identity_store_id': 'd-**********',
    'aws:instance_account': '************',
    'aws:instance_arn': 'arn:aws:sso:::occasion/ssoins-************',
    'exp': 1715795967,
    'iat': 1715792367,
    'iss': 'https://identitycenter.amazonaws.com/ssoins-************',
    'sts:audit_context': 'AQoJb3Jp*********************************Bg==',
    'sts:identity_context': 'AQoJb3Jp********************************************gY=',
    'sub': '34******-d***-7***-b***-e2*********'
}

Automate configuration of a trusted token issuer utilizing AWS CloudFormation

A broad vary of prospects exists to combine your software with Amazon Q Enterprise utilizing IAM Identification Heart and your enterprise IdP. For all integration tasks, Identification Heart must be configured to make use of a trusted token issuer. The pattern CloudFormation templates mentioned on this submit focuses on serving to you automate the core trusted token issuer setup. In case you’re new to Amazon Q Enterprise and don’t have all of the inputs required to deploy the CloudFormation template, the conditions part consists of hyperlinks to sources that may aid you get began. You may as well comply with a tutorial on Configuring pattern net software with Okta included within the accompanying AWS Samples repository.

Observe: The total supply code of the answer utilizing AWS CloudFormation templates and pattern net software is accessible in AWS Samples Repository.

Stipulations and concerns

• IAM Identification Heart is deployed with customers and teams provisioned.
  • For data on enabling completely different IAM Identification Heart situations, see Configure an IAM Identification Heart occasion.
  • For tutorials on organising customers and teams, see the Identification HeartGetting began tutorials. The tutorials embody syncing customers and teams from Okta, Microsoft Entra ID, Google WorkSpace, Ping Identification, OneLogin, JumpCloud, and CyberArk.
• Amazon Q Enterprise software built-in with Identification Heart.
• An online software that requires entry to Q Enterprise APIs.
  • A pattern net software is accessible within the AWS Samples – Webapp. Verify the READ.md file within the /webapp folder for added directions to arrange the pattern.
• An exterior OIDC IdP is deployed.

Template for configuring AWS IAM Identification Heart by a safety proprietor

A safety proprietor can use this CloudFormation template to automate configuration of the trusted token issuer in your IAM Identification Heart. Deploy this stack within the AWS account the place your Identification Heart occasion is situated. This might be in the identical AWS account the place your software is deployed as a standalone or account occasion, or may be in a delegated admin account managed as a part of AWS Organizations.

1. To launch the stack, select:
   

You possibly can obtain the most recent model of the CloudFormation template from AWS Samples – TTI CFN.

The next determine exhibits the stack enter for the template

2. The stack creation requires 4 parameters:

• AuthorizedAudiences: The licensed viewers is an auto generated UUID by a third-party IdP service or a pseudo-ID configured by the administrator of the third-party IdP to uniquely determine the shopper (your software) for which the ID token is generated. The worth should match the aud attribute worth included within the JWT ID token generated by the third-party id supplier.
• ClientAppExecutionArn: The Amazon Useful resource Title (ARN) of the IAM consumer, group or execution position that’s used to run your software, which can invoke Identification Heart for token alternate and AWS STS service for producing non permanent credentials. For instance, this might be the execution position ARN of the Lambda operate the place your code is run.
• IDCInstanceArn: The occasion ARN of the IAM Identification Heart occasion utilized by your software.
• TokenIssuerUrl: The URL of the trusted token issuer. The trusted token issuer is a third-party id supplier that can authenticate a consumer and generate an ID token for authorization functions. The token URL should match the iss attribute worth included within the JWT ID token generated by the third-party id supplier.

The next determine exhibits the output of the CloudFormation stack to configure a trusted token issuer with IAM Identification Heart

The stack creation produces the next output:

• IDCApiAppArn: The ARN for the IAM Identification Heart customized software auth supplier. You’ll use this software to name the Identification Heart CreateTokenWithIAM API to alternate the third-party JWT ID token with the Identification Heart token.

Validate the configuration

1. From the AWS Administration Console the place your IAM Identification Heart occasion is situated, go to the AWS IAM Identification Heart console to confirm if the trusted token issuer is configured correctly.
2. From the left navigation pane, select Functions and select the Buyer Managed tab to see an inventory of purposes as proven within the following determine. The newly created buyer managed IdP software would be the similar because the CloudFormation stack title. Select software title to open the appliance configuration web page.
3. In your software configuration web page, as proven within the following determine, confirm the next:
   1. Consumer and group assignments are set to Don’t require assignments.
   2. Trusted purposes for id propagation lists Amazon Q and consists of the appliance scope qbusiness:conversations:entry.
   3. Authentication with the trusted token issuer is ready to configured.
      
4. Subsequent, to confirm trusted token issuer configuration, select Actions on the highest proper of the web page and choose Edit configurations from the drop-down menu.
   
5. On the backside of the web page, broaden Authentication with trusted token issuer and confirm:
6. That your Issuer URL is chosen by default and is listed underneath .
7. The viewers ID (Aud declare) is configured correctly for the issuer URL, as proven within the following determine. Subsequent broaden Software credentials to confirm in case your software execution IAM position is listed.
   

Relying in your IAM Identification Heart occasion sort, you may not be capable to entry the console buyer managed purposes web page. In such instances, you should utilize the AWS CLI or SDK to view the configuration. Here’s a checklist of helpful AWS CLI instructions: list-applications, list-application-access-scopes, get-application-assignment-configuration, describe-trusted-token-issuer, and list-application-grants.

Template for configuring your software by the software proprietor

To propagate consumer identities, your software might want to:

• Invoke the IAM Identification Heart occasion to alternate a third-party JWT ID token and procure an Identification Heart ID token
• Invoke AWS STS to generate a short lived credential with an IAM assumed position.

The appliance proprietor can use a CloudFormation template to generate the required IAM coverage, which may be connected to your software execution position and the assumed position with the required Q Enterprise chat API privileges to be used with AWS STS to generate non permanent credentials.

Keep in mind to incorporate the add-on coverage generated to your software’s IAM execution position to permit the purposes to invoke Identification Heart and AWS STS APIs.

1. To launch the stack, select:
   

You possibly can obtain the most recent model of the CloudFormation template from AWS Samples – App Roles CFN.

The next determine exhibits the CloudFormation stack configuration to put in IAM roles and insurance policies required for the appliance to propagate identities

2. The stack creation takes 4 parameters, as proven within the previous determine:

• ClientAppExecutionArn: The ARN of an IAM consumer, group, or execution position that’s used to run your software and can invoke IAM Identification Heart for token alternate and AWS STS for producing non permanent credentials. For instance, this might be the execution position ARN of Lambda the place your code is run.
• IDCApiAppArn: ARN for the IAM Identification Heart customized software auth supplier. This shall be created as a part of the trusted token issuer configuration.
• KMSKeyId: [Optional] The AWS Key Administration Server (AWS KMS) ID, if the Q Enterprise Software is encrypted with a buyer managed encryption key.
• QBApplicationID: Q Enterprise software ID, which your software will use to invoke chat APIs. The STS assume position shall be restricted to this software ID.

The next determine exhibits the output of the CloudFormation stack to put in IAM roles and insurance policies required for the appliance to propagate identities.

The stack creation produces the next outputs:

• ClientAppExecutionAddOnPolicyArn: It is a buyer managed IAM coverage created with the required permissions to your software to invoke the IAM Identification Heart CreateTokenWithIAM API and name the STS AssumeRole API to generate non permanent credentials to name Q Enterprise chat APIs. You possibly can embody this coverage in your software IAM execution position to permit entry for the APIs.
• QBusinessSTSAssumeRoleArn: This IAM position will embody the required permissions to name Q Enterprise chat APIs, to be used with the STS AssumeRole API name.

Validate the configuration

1. From the AWS account the place your software is deployed, open the AWS IAM console, confirm if the IAM position for STS AssumeRole and the consumer managed IAM coverage for the appliance execution position are created.
   • To confirm if the IAM Position for STS AssumeRole, acquire the position title QBusinessSTSAssumeRoleArn stack output worth, select theRoles hyperlink on the left panel of the IAM console and use the search bar to enter the position title and proven within the following determine.
     
2. Select the hyperlink to the position to open the position and broaden the inline coverage to evaluate the permissions, as proven within the following determine.
   
3. To confirm if the IAM coverage for add-on to an software execution position is created, acquire the IAM coverage title from the ClientAppExecutionAddOnPolicyArn stack output worth, go the Insurance policies within the IAM console, and seek for the coverage, as proven within the following determine.
   
4. Select the hyperlink to the coverage title to open the coverage and evaluate the permissions, as proven within the following determine.
   

Replace the appliance for invoking the Q Enterprise API with id propagation

Most net purposes utilizing OAuth 2.0 with an IdP can have carried out a sign-in mechanism and invoke the IdPs ID endpoint to retrieve a JWT ID token. Nevertheless, earlier than invoking Amazon Q Enterprise APIs that require id propagation, your software must be up to date to incorporate calls to CreateTokenWithIAM and AssumeRole to facilitate trusted token propagation.

The CreateTokenWithIAM API permits exchanging the JWT ID token acquired from the OIDC IdP with an IAM id Heart generated JWT token. The newly generated token is then handed on to AssumeRole API to create an id conscious non permanent safety credentials that you should utilize to entry AWS sources.

Observe: Keep in mind so as to add permissions to your IAM position and consumer coverage to permit invoking these APIs. Alternatively, you’ll be able to connect the pattern coverage referenced by ClientAppExecutionAddOnPolicyArn that was created by the CloudFormation template for configuring your software.

A pattern entry helper methodology utilizing  get_oidc_id_token, get_idc_sts_id_context, or get_sts_credential is accessible in /src/qbapi_tools/access_helpers.py  (AWS Samples – access_helpers.py). An end-to-end pattern implementation of the entire sequence of steps as depicted within the end-to-end authentication sequence is offered in /webapp/foremost.py (AWS Samples – foremost.py).

Restrictions and limitations

Beneath are some widespread limitations and restrictions that you could be encounter whereas configuring trusted token propagation together with suggestions on mitigate them.

Group membership propagation

Enterprises sometimes handle group membership of their exterior IdP. Nevertheless, when utilizing trusted token propagation, the online id token generated by the exterior IdP is exchanged with an ID token generated by IAM Identification Heart. Thus, when invoking the Q Enterprise API from an STS session enhanced with Identification Heart id context, solely the group membership data accessible for the consumer in Identification Heart is handed to the Q Enterprise API, not the group membership from the exterior IdP. To mitigate this challenge, it’s really useful that each one related customers and teams are synchronized to Identification Heart from the exterior IdP utilizing System for Cross-domain Identification Administration (SCIM). For extra data, see automated provisioning (synchronization) of customers and groups.

Caching credentials to forestall invalid grant varieties

You should use an internet id token solely as soon as with the CreateTokenWithIAM API. That is to forestall token replay assaults, the place an attacker can intercept a JWT and reuse it a number of instances, permitting them to bypass authentication and authorization controls. As a result of it isn’t sensible to generate a brand new ID token for each Q Enterprise API, it’s really useful that the non permanent credentials generated by a Q Enterprise API session utilizing AWS STS AssumeRole is cached and reused for subsequent API calls.

Clear up

To keep away from incurring further expenses, ensure you delete any sources created on this submit.

1. Comply with the directions in Deleting a stack on the AWS CloudFormation console to delete any CloudFormation stacks created utilizing templates offered on this submit.
2. In case you enabled an IAM Identification Heart occasion, comply with the directions to delete your IAM Identification Heart occasion.
3. Make sure you unregister or delete any IdP companies reminiscent of Okta, Entra ID, Ping Identification, or Amazon Cognito that you’ve got created for this submit.
4. Lastly, delete any pattern code repositories you’ve cloned or downloaded, and any related sources deployed as a part of organising the atmosphere for working the samples within the code repository.

Conclusion

Trusted id propagation is a vital mechanism for securely integrating Amazon Q Enterprise APIs into enterprise purposes that use exterior IdPs. By implementing trusted id propagation with AWS IAM Identification Heart, organizations can confidently construct AI-powered purposes and instruments utilizing Amazon Q Enterprise APIs, realizing that consumer identities are correctly verified and guarded all through the method. This strategy permits enterprises to harness the total potential of generative AI whereas sustaining the best requirements of safety and privateness. To get began with Amazon Q Enterprise, discover the Getting began information. To be taught extra about how trusted token propagation works, see Learn how to develop a user-facing information software with IAM Identification Heart and S3 Entry Grants.

Concerning the Creator

Rajesh Kumar Ravi is a Senior Options Architect at Amazon Net Providers specializing in constructing generative AI options with Amazon Q Enterprise, Amazon Bedrock, and Amazon Kendra. He’s an completed know-how chief with expertise in constructing revolutionary AI merchandise, nurturing the builder group, and contributes to the event of latest concepts. He enjoys strolling and likes to go on quick climbing journeys exterior of labor.