Configure Amazon Q Enterprise with AWS IAM Id 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 based mostly in your enterprise knowledge. The native knowledge supply connectors supplied 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 Id Heart to document the workforce customers you assign entry to and their attributes, reminiscent of group associations. IAM Id Heart is utilized by many AWS managed functions reminiscent of Amazon Q. You join your present supply of identities to Id Heart as soon as and might then assign customers to any of those AWS providers. As a result of Id 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 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 identification propagation enabled by IAM Id 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 on your enterprise. With administrative APIs you may automate creating Q Enterprise functions, arrange knowledge supply connectors, construct customized doc enrichment, and configure guardrails. With dialog APIs, you may chat and handle conversations with Q Enterprise AI assistant. Trusted identification propagation gives authorization based mostly on consumer context, which boosts the privateness controls of Amazon Q Enterprise.

On this weblog submit, you’ll study what trusted identification propagation is and why to make use of it, the best way to automate configuration of a trusted token issuer in AWS IAM Id Heart with supplied 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 gives a mechanism that permits functions that authenticate exterior 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 consumer to offer entry to an AWS useful resource that’s non-public to the consumer. For instance, your internet utility may use Okta as an exterior IdP to authenticate a consumer to view their non-public conversations from Q Enterprise. On this situation, Q Enterprise is unable to make use of the identification token generated by the third get together supplier to offer direct entry to the consumer’s non-public knowledge since there is no such thing as a mechanism to belief the identification token issued by the third get together.

To resolve this, you need to use IAM Id Heart to get the consumer identification out of your exterior IdP into an AWS Id and Entry Administration (IAM) function session which lets you authorize requests based mostly on the human, their attributes, and their group memberships, reasonably than arrange fine-grained permissions in an IAM coverage. You’ll be able to change the token issued by the exterior IdP for a token generated by Id Heart. The token generated by Id Heart refers back to the corresponding Id Heart consumer. The online utility can now use the brand new token to provoke a request to Q Enterprise for the non-public chat dialog. That token refers back to the corresponding consumer in Id Heart, Q Enterprise can authorize the requested entry to the non-public dialog based mostly on the consumer or their group membership as represented in Id Heart.

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

• Prevents consumer impersonation and protects in opposition to unauthorized entry to consumer non-public knowledge by spoofing consumer identification.
• Facilitates auditability and fosters accountable use of assets as Q Enterprise robotically logs API invocations to AWS CloudTrail together with consumer identifier.
• Promotes software program design ideas rooted in consumer 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 Id Heart for trusted identification propagation, take into account the mannequin client-server internet utility proven within the previous determine. On this mannequin structure, the online browser represents the consumer interface to your utility. This may very well be an online web page rendered on an online browser, Slack, Microsoft Groups, or different functions. The appliance server may be an online server working on Amazon Elastic Container Service (Amazon ECS), or a Slack or Microsoft Groups gateway carried out with AWS Lambda. Id Heart itself may be deployed on a delegated admin account or Id Heart (the Id Account within the previous determine), or may very well be deployed in the identical AWS account (the Software Account within the previous determine) the place the applying server is deployed together with Amazon Q Enterprise. Lastly, you’ve got 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 identification propagation includes 5 steps. As a greatest apply, we advocate that the safety proprietor manages IAM Id Heart updates and the utility proprietor manages utility updates, offering clear separation of duties. The safety proprietor is accountable for administering the Id Heart of a corporation or account. The appliance proprietor is accountable for creating an utility on AWS.

1. The safety proprietor provides the exterior OIDC IdP’s issuer URL to the IAM Id Heart occasion’s trusted token issuer. It’s necessary that the issuer URL matches the iss declare attribute current within the JSON Internet Token (JWT) identification 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 identification supplier utility in IAM Id Heart and explicitly configures the particular viewers for a given trusted token issuer is being licensed to carry out token change utilizing Id Heart. As a result of there may very well be a couple of utility (or viewers) for which the exterior IdP may very well be authenticating customers, explicitly specifying an viewers helps stop an unauthorized functions from utilizing the token change course of. It’s necessary the viewers ID matches the aud declare attribute current within the JWT identification token generated by the IdP after consumer 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 stop any unapproved customers or functions from invoking the CreateTokenWithIAM API in Id Heart to provoke the token change.
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 Id Heart to carry out a token change and to create short-term 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 brief 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 Id Heart documentation for detailed step-by-step directions on organising trusted identification propagation. You can too use the AWS Command Line Interface (AWS CLI) setup course of in Making authenticated Amazon Q Enterprise API calls utilizing IAM Id Heart.

Necessary: Selecting so as to add a trusted token issuer is a safety determination 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 Id Heart can change for an Id Heart-created token. Management the Id Heart buyer managed utility coverage so as to add solely IAM customers, roles, and execution roles that may carry out the change.

Authorization movement

For a typical internet utility, the trusted identification propagation course of will contain 5 steps as proven within the following movement diagram.

1. Signal-in and acquire an authorization code from the IdP.
2. Use the authorization code and shopper secret to retrieve the ID token from the IdP.
3. Trade the IdP generated JWT ID token with the IAM Id Heart token that features the AWS STS context identification.
4. Use the STS context identification to acquire short-term entry credentials from AWS STS.
5. Use short-term entry credentials to entry Q Enterprise APIs.

An end-to-end implementation of the identification propagation is on the market for reference in <project_home>/webapp/most important.py of AWS Samples – main.py.

Pattern JWT tokens

Within the previous authorization movement, one of many key steps is step 3, the place the JWT ID token from the OAuth IdP is exchanged with IAM Id 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 movement 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 non-public key of the issuer and could be parsed and verified by the applying. In distinction to entry tokens, ID tokens are meant 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 Id Heart to validate the token issuer, match the consumer listing, and subject a brand new Id Heart token. The next code pattern reveals a JWT identification 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***********************',
    'identify': 'John Doe',
    'nonce': 'SampleNonce',
    'preferred_username': 'john_doe@******.com',
    'sub': '00ue36ou4gCv************',
    'ver': 1
}

IAM Id 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 Id Heart consumer to carry out an motion and log the consumer 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 prospects exists to combine your utility with Amazon Q Enterprise utilizing IAM Id Heart and your enterprise IdP. For all integration initiatives, Id 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. For those who’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 assets that may assist you to get began. You can too comply with a tutorial on Configuring sample web application 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 on the market in AWS Samples Repository.

Conditions and issues

• IAM Id Heart is deployed with customers and teams provisioned.
  • For data on enabling completely different IAM Id Heart cases, see Configure an IAM Id Heart occasion.
  • For tutorials on organising customers and teams, see the Id CenterGetting began tutorials. The tutorials embrace syncing customers and teams from Okta, Microsoft Entra ID, Google WorkSpace, Ping Id, OneLogin, JumpCloud, and CyberArk.
• Amazon Q Enterprise utility built-in with Id Heart.
• An internet utility that requires entry to Q Enterprise APIs.
  • A pattern internet utility is on the market within the AWS Samples – Webapp. Examine the READ.md file within the <project_home>/webapp folder for added directions to arrange the pattern.
• An exterior OIDC IdP is deployed.

Template for configuring AWS IAM Id Heart by a safety proprietor

A safety proprietor can use this CloudFormation template to automate configuration of the trusted token issuer in your IAM Id Heart. Deploy this stack within the AWS account the place your Id Heart occasion is situated. This may very well 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’ll be able to obtain the newest 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 establish 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 consumer, group or execution function that’s used to run your utility, which is able to invoke Id Heart for token change and AWS STS service for producing short-term credentials. For instance, this may very well be the execution function ARN of the Lambda operate the place your code is run.
• IDCInstanceArn: The occasion ARN of the IAM Id 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 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 identification supplier.

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

The stack creation produces the next output:

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

Validate the configuration

1. From the AWS Administration Console the place your IAM Id Heart occasion is situated, go to the AWS IAM Id 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 identify. Select utility identify 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 consists of 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, increase 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 increase Software credentials to confirm in case your utility execution IAM function is listed.
   

Relying in your IAM Id Heart occasion kind, you may not have the ability to entry the console buyer managed functions web page. In such circumstances, you need to use the AWS CLI or SDK to view the configuration. Here’s a record 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 consumer identities, your utility might want to:

• Invoke the IAM Id Heart occasion to change a third-party JWT ID token and acquire an Id Heart ID token
• Invoke AWS STS to generate a brief credential with an IAM assumed function.

The appliance proprietor can use a CloudFormation template to generate the required IAM coverage, which could be hooked up 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 short-term credentials.

Bear in mind to incorporate the add-on coverage generated to your utility’s IAM execution function to permit the functions to invoke Id Heart and AWS STS APIs.

1. To launch the stack, select:
   

You’ll be able to obtain the newest 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 consumer, group, or execution function that’s used to run your utility and can invoke IAM Id Heart for token change and AWS STS for producing short-term credentials. For instance, this may very well be the execution function ARN of Lambda the place your code is run.
• IDCApiAppArn: ARN for the IAM Id Heart customized utility auth supplier. This might 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 utility ID, which your utility will use to invoke chat APIs. The STS assume function might 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 on your utility to invoke the IAM Id Heart CreateTokenWithIAM API and name the STS AssumeRole API to generate short-term credentials to name Q Enterprise chat APIs. You’ll be able to embrace this coverage in your utility IAM execution function to permit entry for the APIs.
• QBusinessSTSAssumeRoleArn: This IAM function will embrace 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 utility is deployed, open the AWS IAM console, confirm if the IAM function for STS AssumeRole and the consumer managed IAM coverage for the applying execution function are created.
   • To confirm if the IAM Position for STS AssumeRole, receive the function identify QBusinessSTSAssumeRoleArn stack output worth, select theRoles hyperlink on the left panel of the IAM console and use the search bar to enter the function identify and proven within the following determine.
     
2. Select the hyperlink to the function to open the function and increase 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 utility execution function is created, receive the IAM coverage identify 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 identify to open the coverage and evaluate 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. Nonetheless, 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 permits exchanging the JWT ID token obtained 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 short-term safety credentials that you need to use to entry AWS assets.

Notice: Bear in mind so as to add permissions to your IAM function and consumer coverage to permit invoking these APIs. Alternatively, you may 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 on the market 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 supplied in <project_home>/webapp/most important.py (AWS Samples – main.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 the best way to mitigate them.

Group membership propagation

Enterprises sometimes handle group membership of their exterior IdP. Nonetheless, when utilizing trusted token propagation, the online identification token generated by the exterior IdP is exchanged with an ID token generated by IAM Id Heart. Thus, when invoking the Q Enterprise API from an STS session enhanced with Id Heart identification context, solely the group membership data out there for the consumer in Id Heart is handed to the Q Enterprise API, not the group membership from the exterior IdP. To mitigate this subject, it’s advisable that every one related customers and teams are synchronized to Id Heart from the exterior IdP utilizing System for Cross-domain Id Administration (SCIM). For extra data, see computerized provisioning (synchronization) of customers and teams.

Caching credentials to forestall invalid grant varieties

You should use an online identification 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 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 short-term 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, be sure you delete any assets 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 supplied on this submit.
2. For those who enabled an IAM Id Heart occasion, comply with the directions to delete your IAM Id Heart occasion.
3. Make sure you unregister or delete any IdP providers reminiscent of Okta, Entra ID, Ping Id, or Amazon Cognito that you’ve created for this submit.
4. Lastly, delete any pattern code repositories you’ve got cloned or downloaded, and any related assets deployed as a part of organising the setting for working 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 Id Heart, organizations can confidently construct AI-powered functions and instruments utilizing Amazon Q Enterprise APIs, realizing that consumer identities are correctly verified and guarded all through the method. This method permits enterprises to harness the total potential of generative AI whereas sustaining the very 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 Methods to develop a user-facing knowledge utility with IAM Id Heart and S3 Entry Grants.

Concerning the Creator

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