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

Amazon Q Enterprise is a totally managed, permission conscious generative synthetic intelligence (AI)-powered assistant constructed with enterprise grade safety and privateness options. Amazon Q Enterprise could be configured to reply questions, present summaries, generate content material, and securely full duties primarily based in your enterprise knowledge. The native knowledge 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 file the workforce customers you assign entry to and their attributes, resembling group associations. IAM Identification Heart is utilized by many AWS managed functions resembling 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 functions can provide your customers a constant expertise as they navigate AWS. For instance, it allows person 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 identification 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 person expertise to your enterprise. With administrative APIs you’ll be able to automate creating Q Enterprise functions, arrange knowledge 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 identification propagation offers authorization primarily based on person context, which reinforces the privateness controls of Amazon Q Enterprise.

On this weblog publish, you’ll study what trusted identification propagation is and why to make use of it, learn how to 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 utility facilitate calling Amazon Q Enterprise identity-aware dialog APIs.

Why use trusted identification propagation?

Trusted identification propagation offers a mechanism that allows functions that authenticate outdoors of AWS to make requests on behalf of their customers with using a trusted token issuer. Think about a client-server utility that makes use of an exterior identification supplier (IdP) to authenticate a person to supply entry to an AWS useful resource that’s personal to the person. For instance, your internet utility may use Okta as an exterior IdP to authenticate a person to view their personal conversations from Q Enterprise. On this situation, Q Enterprise is unable to make use of the identification token generated by the third occasion supplier to supply direct entry to the person’s personal knowledge since there isn’t any mechanism to belief the identification token issued by the third occasion.

To resolve this, you should use IAM Identification Heart to get the person identification out of your exterior IdP into an AWS Identification and Entry Administration (IAM) function session which lets you authorize requests primarily based on the human, their attributes, and their group memberships, slightly than arrange fine-grained permissions in an IAM coverage. You possibly can trade 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 person. The online utility 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 person in Identification Heart, Q Enterprise can authorize the requested entry to the personal dialog primarily based on the person or their group membership as represented in Identification Heart.

A number of the advantages of utilizing trusted identification propagation are:

• Prevents person impersonation and protects in opposition to unauthorized entry to person personal knowledge by spoofing person identification.
• Facilitates auditability and fosters accountable use of assets as Q Enterprise robotically logs API invocations to AWS CloudTrail together with person identifier.
• Promotes software program design ideas rooted in person privateness.

Overview of trusted identification propagation deployment

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

To grasp how your utility could be built-in with IAM Identification Heart for trusted identification propagation, think about the mannequin client-server internet utility proven within the previous determine. On this mannequin structure, the online browser represents the person interface to your utility. This could possibly be an online web page rendered on an online browser, Slack, Microsoft Groups, or different functions. The appliance server may be an online server operating on Amazon Elastic Container Service (Amazon ECS), or a Slack or Microsoft Groups gateway carried out with AWS Lambda. Identification Heart itself may be deployed on a delegated admin account or Identification Heart (the Identification Account within the previous determine), or could possibly be deployed in the identical AWS account (the Utility Account within the previous determine) the place the applying server is deployed together with Amazon Q Enterprise. Lastly, you could have an OAuth 2.0 OpenID Join (OIDC) exterior IdP resembling Okta, Ping One, Microsoft Entra ID, or Amazon Cognito for authenticating and authorizing.

Deployment of trusted identification propagation includes 5 steps. As a greatest apply, we advocate that the safety proprietor manages IAM Identification Heart updates and the utility proprietor manages utility updates, offering clear separation of duties. The safety proprietor is answerable for administering the Identification Heart of a corporation or account. The appliance proprietor is answerable for creating an utility 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 Internet Token (JWT) identification token generated by the IdP after person authentication. That is configured as soon as for a given issuer URL.
2. The safety proprietor creates a buyer managed identification supplier utility in IAM Identification Heart and explicitly configures the precise viewers for a given trusted token issuer is being licensed to carry out token trade utilizing Identification Heart. As a result of there could possibly be multiple utility (or viewers) for which the exterior IdP could possibly be authenticating customers, explicitly specifying an viewers helps forestall an unauthorized functions from utilizing the token trade course of. It’s vital the viewers ID matches the aud declare attribute current within the JWT identification token generated by the IdP after person authentication.
3. The safety proprietor edits the applying coverage for the buyer managed identification supplier utility created within the earlier step so as to add or replace the IAM execution function utilized by the applying server or AWS Lambda. This helps forestall any unapproved customers or functions from invoking the CreateTokenWithIAM API in Identification Heart to provoke the token trade.
4. The appliance proprietor creates and provides an IAM coverage to the applying execution function to permit the applying to invoke a CreateTokenWithIAM API on Identification Heart to carry out a token trade and to create non permanent credentials utilizing AWS Safety Token Service (AWS STS) .
5. The appliance proprietor creates an IAM function 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 establishing trusted identification propagation. You may also use the AWS Command Line Interface (AWS CLI) setup course of in Making authenticated Amazon Q Enterprise API calls utilizing IAM Identification Heart.

Necessary: 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 person who’s specified within the token. Management the viewers declare, a declare you configure because the person identifier.
• Generate a token that IAM Identification Heart can trade for an Identification Heart-created token. Management the Identification Heart buyer managed utility coverage so as to add solely IAM customers, roles, and execution roles that may carry out the trade.

Authorization circulation

For a typical internet utility, the trusted identification propagation course of will contain 5 steps as proven within the following circulation 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 identification.
4. Use the STS context identification 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 identification propagation is obtainable for reference in <project_home>/webapp/principal.py of AWS Samples – principal.py.

Pattern JWT tokens

Within the previous authorization circulation, 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 circulation 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 could be parsed and verified by the applying. In distinction to entry tokens, ID tokens are supposed to be understood by the OAuth shopper and embrace a handful of outlined property names that present data to the applying. Necessary properties embrace aud, e mail, iss, and jti, that are utilized by IAM Identification Heart to validate the token issuer, match the person listing, and difficulty a brand new Identification Heart token. The next code pattern reveals a JWT identification token issued by an OIDC exterior IdP (resembling 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 identification context

A pattern JWT token generated by CreateTokenWithIAM is proven within the following code pattern. This token features a property referred to as sts:identity_context which lets you create an identity-enhanced IAM function session utilizing an AWS STS AssumeRole API. The improved STS session permits the receiving AWS service to authorize the IAM Identification Heart person to carry out an motion and log the person identification 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::************:utility/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 potentialities exists to combine your utility with Amazon Q Enterprise utilizing IAM Identification Heart and your enterprise IdP. For all integration initiatives, Identification Heart must be configured to make use of a trusted token issuer. The pattern CloudFormation templates mentioned on this publish focuses on serving to you automate the core trusted token issuer setup. Should you’re new to Amazon Q Enterprise and don’t have all of the inputs required to deploy the CloudFormation template, the conditions part contains hyperlinks to assets that may enable you to get began. You may also observe a tutorial on Configuring pattern internet utility with Okta included within the accompanying AWS Samples repository.

Notice: The complete supply code of the answer utilizing AWS CloudFormation templates and pattern internet utility is obtainable in AWS Samples Repository.

Conditions and concerns

• IAM Identification Heart is deployed with customers and teams provisioned.
  • For data on enabling completely different IAM Identification Heart cases, see Configure an IAM Identification Heart occasion.
  • For tutorials on establishing customers and teams, see the Identification HeartGetting began tutorials. The tutorials embrace syncing customers and teams from Okta, Microsoft Entra ID, Google WorkSpace, Ping Identification, OneLogin, JumpCloud, and CyberArk.
• Amazon Q Enterprise utility built-in with Identification Heart.
• An internet utility that requires entry to Q Enterprise APIs.
  • A pattern internet utility is obtainable within the AWS Samples – Webapp. Test the READ.md file within the <project_home>/webapp folder for extra 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 could possibly be in the identical AWS account the place your utility is deployed as a standalone or account occasion, or could 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 reveals 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 utility) 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 identification supplier.
• ClientAppExecutionArn: The Amazon Useful resource Identify (ARN) of the IAM person, group or execution function that’s used to run your utility, which can invoke Identification Heart for token trade and AWS STS service for producing non permanent credentials. For instance, this could possibly be the execution function ARN of the Lambda operate the place your code is run.
• IDCInstanceArn: The occasion ARN of the IAM Identification Heart occasion utilized by your utility.
• TokenIssuerUrl: The URL of the trusted token issuer. The trusted token issuer is a third-party identification supplier that may authenticate a person 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 identification supplier.

The next determine reveals 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 utility auth supplier. You’ll use this utility to name the Identification Heart CreateTokenWithIAM API to trade 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 Purposes and select the Buyer Managed tab to see an inventory of functions as proven within the following determine. The newly created buyer managed IdP utility would be the identical because the CloudFormation stack title. Select utility title to open the applying configuration web page.
3. In your utility configuration web page, as proven within the following determine, confirm the next:
   1. Person and group assignments are set to Don’t require assignments.
   2. Trusted functions for identification propagation lists Amazon Q and contains the applying scope qbusiness:conversations:entry.
   3. Authentication with the trusted token issuer is about 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, develop 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 develop Utility credentials to confirm in case your utility execution IAM function is listed.
   

Relying in your IAM Identification Heart occasion sort, you won’t be capable of entry the console buyer managed functions web page. In such instances, you should use the AWS CLI or SDK to view the configuration. Here’s a listing 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 utility by the utility proprietor

To propagate person identities, your utility might want to:

• Invoke the IAM Identification Heart occasion to trade 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 function.

The appliance proprietor can use a CloudFormation template to generate the required IAM coverage, which could be connected to your utility execution function and the assumed function 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 utility’s IAM execution function to permit the functions 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 reveals the CloudFormation stack configuration to put in IAM roles and insurance policies required for the applying to propagate identities

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

• ClientAppExecutionArn: The ARN of an IAM person, group, or execution function that’s used to run your utility and can invoke IAM Identification Heart for token trade and AWS STS for producing non permanent credentials. For instance, this could possibly be the execution function ARN of Lambda the place your code is run.
• IDCApiAppArn: ARN for the IAM Identification Heart customized utility auth supplier. This can 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 Utility is encrypted with a buyer managed encryption key.
• QBApplicationID: Q Enterprise utility ID, which your utility will use to invoke chat APIs. The STS assume function can be restricted to this utility ID.

The next determine reveals the output of the CloudFormation stack to put in IAM roles and insurance policies required for the applying 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 utility 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 embrace this coverage in your utility IAM execution function to permit entry for the APIs.
• QBusinessSTSAssumeRoleArn: This IAM function will embrace the mandatory 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 utility is deployed, open the AWS IAM console, confirm if the IAM function for STS AssumeRole and the person managed IAM coverage for the applying execution function are created.
   • To confirm if the IAM Function for STS AssumeRole, receive the function title QBusinessSTSAssumeRoleArn stack output worth, select theRoles hyperlink on the left panel of the IAM console and use the search bar to enter the function title and proven within the following determine.
     
2. Select the hyperlink to the function to open the function and develop the inline coverage to assessment the permissions, as proven within the following determine.
   
3. To confirm if the IAM coverage for add-on to an utility execution function is created, receive 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 assessment the permissions, as proven within the following determine.
   

Replace the applying for invoking the Q Enterprise API with identification propagation

Most internet functions utilizing OAuth 2.0 with an IdP may 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 identification propagation, your utility must be up to date to incorporate calls to CreateTokenWithIAM and AssumeRole to facilitate trusted token propagation.

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

Notice: Keep in mind so as to add permissions to your IAM function and person 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 utility.

A pattern entry helper technique utilizing  get_oidc_id_token, get_idc_sts_id_context, or get_sts_credential is obtainable in <project_home>/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 <project_home>/webapp/principal.py (AWS Samples – principal.py).

Restrictions and limitations

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

Group membership propagation

Enterprises sometimes handle group membership of their exterior IdP. Nevertheless, when utilizing trusted token propagation, the online identification 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 identification context, solely the group membership data accessible for the person in Identification Heart is handed to the Q Enterprise API, not the group membership from the exterior IdP. To mitigate this difficulty, it’s advisable 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 stop invalid grant sorts

You should use an online identification token solely as soon as with the CreateTokenWithIAM API. That is to stop token replay assaults, the place an attacker can intercept a JWT and reuse it a number of occasions, 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 advisable 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 extra fees, ensure you delete any assets created on this publish.

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 publish.
2. Should you enabled an IAM Identification Heart occasion, observe the directions to delete your IAM Identification Heart occasion.
3. Make sure you unregister or delete any IdP companies resembling Okta, Entra ID, Ping Identification, or Amazon Cognito that you’ve got created for this publish.
4. Lastly, delete any pattern code repositories you could have cloned or downloaded, and any related assets deployed as a part of establishing the setting for operating the samples within the code repository.

Conclusion

Trusted identification propagation is a crucial mechanism for securely integrating Amazon Q Enterprise APIs into enterprise functions that use exterior IdPs. By implementing trusted identification propagation with AWS IAM Identification Heart, organizations can confidently construct AI-powered functions and instruments utilizing Amazon Q Enterprise APIs, understanding that person 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 study extra about how trusted token propagation works, see Learn how to develop a user-facing knowledge utility with IAM Identification Heart and S3 Entry Grants.

In regards to the Writer

Rajesh Kumar Ravi is a Senior Options Architect at Amazon Internet Providers specializing in constructing generative AI options with Amazon Q Enterprise, Amazon Bedrock, and Amazon Kendra. He’s an achieved expertise chief with expertise in constructing modern AI merchandise, nurturing the builder neighborhood, and contributes to the event of recent concepts. He enjoys strolling and likes to go on brief mountaineering journeys outdoors of labor.