Configure Amazon Q Enterprise with AWS IAM Id Middle trusted identification propagation

Amazon Q Business is a completely managed, permission conscious generative synthetic intelligence (AI)-powered assistant constructed with enterprise grade safety and privateness options. Amazon Q Enterprise might 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 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 Identity Center to report the workforce customers you assign entry to and their attributes, akin to group associations. IAM Id Middle is utilized by many AWS managed functions akin to Amazon Q. You join your current supply of identities to Id Middle as soon as and might then assign customers to any of those AWS providers. As a result of Id Middle serves as their frequent reference of your customers and teams, these AWS functions may give your customers a constant expertise as they navigate AWS. For instance, it allows 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 Middle.

Amazon Q Enterprise comes with wealthy API help to carry out administrative duties or to construct an AI-assistant with personalized consumer expertise to your enterprise. With administrative APIs you’ll be able to automate creating Q Enterprise functions, 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 identification propagation offers authorization based mostly on consumer context, which reinforces the privateness controls of Amazon Q Enterprise.

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

Why use trusted identification propagation?

Trusted identity propagation offers a mechanism that allows functions that authenticate exterior of AWS to make requests on behalf of their customers with the usage of a trusted token issuer. Think about a client-server software that makes use of an exterior identification 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 state of affairs, Q Enterprise is unable to make use of the identification token generated by the third get together supplier to supply direct entry to the consumer’s personal information since there is no such thing as a mechanism to belief the identification token issued by the third get together.

To resolve this, you should utilize IAM Id Middle to get the consumer identification out of your exterior IdP into an AWS Identity and Access Management (IAM) function 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 Id Middle. The token generated by Id Middle refers back to the corresponding Id Middle consumer. The net 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 Id Middle, Q Enterprise can authorize the requested entry to the personal dialog based mostly on the consumer or their group membership as represented in Id Middle.

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

Prevents consumer impersonation and protects in opposition to unauthorized entry to consumer personal information by spoofing consumer identification.
Facilitates auditability and fosters accountable use of assets as Q Enterprise routinely logs API invocations to AWS CloudTrail together with consumer identifier.
Promotes software program design rules 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 know how your software might be built-in with IAM Id Middle for trusted identification propagation, take into account the mannequin client-server net software proven within the previous determine. On this mannequin structure, the net browser represents the consumer interface to your software. 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 operating on Amazon Elastic Container Service (Amazon ECS), or a Slack or Microsoft Groups gateway applied with AWS Lambda. Id Middle itself may be deployed on a delegated admin account or Identity Center (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 will have an OAuth 2.0 OpenID Join (OIDC) exterior IdP akin to Okta, Ping One, Microsoft Entra ID, or Amazon Cognito for authenticating and authorizing.

Deployment of trusted identification propagation entails 5 steps. As a greatest observe, we advocate that the safety proprietor manages IAM Id Middle updates and the software proprietor manages software updates, offering clear separation of duties. The safety proprietor is accountable for administering the Id Middle of a corporation or account. The appliance proprietor is accountable for creating an software on AWS.

The safety proprietor provides the exterior OIDC IdP’s issuer URL to the IAM Id Middle occasion’s trusted token issuer. It’s vital that the issuer URL matches the iss declare attribute current within the JSON Net Token (JWT) identification token generated by the IdP after consumer authentication. That is configured as soon as for a given issuer URL.
The safety proprietor creates a buyer managed identification supplier software in IAM Id Middle and explicitly configures the precise viewers for a given trusted token issuer is being licensed to carry out token alternate utilizing Id Middle. As a result of there may very well be a couple of software (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 alternate course of. It’s vital the viewers ID matches the aud declare attribute current within the JWT identification token generated by the IdP after consumer authentication.
The safety proprietor edits the applying coverage for the buyer managed identification supplier software 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 Middle to provoke the token alternate.
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 Middle to carry out a token alternate and to create momentary credentials utilizing AWS Security Token Service (AWS STS) .
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 utilize AWS CloudFormation templates, mentioned later on this weblog, to automate the previous deployment steps. See the IAM Id Middle documentation for detailed step-by-step directions on setting up trusted identity propagation. You may as well use the AWS Command Line Interface (AWS CLI) setup course of in Making authenticated Amazon Q Business API calls using IAM Identity Center.

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 just 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 Middle can alternate for an Id Middle-created token. Management the Id Middle buyer managed software coverage so as to add solely IAM customers, roles, and execution roles that may carry out the alternate.

Authorization movement

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

Signal-in and acquire an authorization code from the IdP.
Use the authorization code and consumer secret to retrieve the ID token from the IdP.
Change the IdP generated JWT ID token with the IAM Id Middle token that features the AWS STS context identification.
Use the STS context identification to acquire momentary entry credentials from AWS STS.
Use momentary entry credentials to entry Q Enterprise APIs.

An end-to-end implementation of the identification propagation is out there for reference in <project_home>/webapp/principal.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 Middle 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 personal key of the issuer and might be parsed and verified by the applying. In distinction to entry tokens, ID tokens are meant to be understood by the OAuth consumer 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 Middle to validate the token issuer, match the consumer listing, and difficulty a brand new Id Middle token. The next code pattern reveals a JWT identification token issued by an OIDC exterior IdP (akin to 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 Id Middle 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 Middle 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::************: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 potentialities exists to combine your software with Amazon Q Enterprise utilizing IAM Id Middle and your enterprise IdP. For all integration initiatives, Id Middle 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. If you happen to’re new to Amazon Q Enterprise and don’t have all of the inputs required to deploy the CloudFormation template, the stipulations part consists of hyperlinks to assets that may aid you get began. You may as well observe a tutorial on Configuring sample web application with Okta included within the accompanying AWS Samples repository.

Be aware: The complete supply code of the answer utilizing AWS CloudFormation templates and pattern net software is out there in AWS Samples Repository.

Stipulations and issues

IAM Id Middle is deployed with customers and teams provisioned.
- For data on enabling totally different IAM Id Middle situations, see Configure an IAM Identity Center instance.
- For tutorials on establishing customers and teams, see the Id MiddleGetting started tutorials. The tutorials embrace syncing customers and teams from Okta, Microsoft Entra ID, Google WorkSpace, Ping Id, OneLogin, JumpCloud, and CyberArk.
Amazon Q Enterprise software built-in with Id Middle.
An internet software that requires entry to Q Enterprise APIs.
- A pattern net software is out there within the AWS Samples – Webapp. Verify 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 Middle by a safety proprietor

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

To launch the stack, select:

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

The next determine reveals the stack enter for the template

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 consumer (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 identification supplier.
ClientAppExecutionArn: The Amazon Useful resource Title (ARN) of the IAM consumer, group or execution function that’s used to run your software, which can invoke Id Middle for token alternate and AWS STS service for producing momentary 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 Middle occasion utilized by your software.
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 Middle

The stack creation produces the next output:

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

Validate the configuration

From the AWS Administration Console the place your IAM Id Middle occasion is situated, go to the AWS IAM Identity Center console to confirm if the trusted token issuer is configured correctly.
From the left navigation pane, select Functions and select the Buyer Managed tab to see a listing of functions 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 applying configuration web page.
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 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.
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.
On the backside of the web page, increase Authentication with trusted token issuer and confirm:
That your Issuer URL is chosen by default and is listed beneath .
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 software execution IAM function is listed.

Relying in your IAM Id Middle occasion kind, you won’t be capable of entry the console buyer managed functions web page. In such circumstances, 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 Id Middle occasion to alternate a third-party JWT ID token and acquire an Id Middle 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 might be hooked up to your software execution function and the assumed function with the required Q Enterprise chat API privileges to be used with AWS STS to generate momentary credentials.

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

To launch the stack, select:

You possibly can 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

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 software and can invoke IAM Id Middle for token alternate and AWS STS for producing momentary 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 Middle customized software auth supplier. This will likely be created as a part of the trusted token issuer configuration.
KMSKeyId: [Optional] The AWS Key Management 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 function will likely be restricted to this software 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: This can be a buyer managed IAM coverage created with the required permissions to your software to invoke the IAM Id Middle CreateTokenWithIAM API and name the STS AssumeRole API to generate momentary credentials to name Q Enterprise chat APIs. You possibly can embrace this coverage in your software 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

From the AWS account the place your software 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 Function for STS AssumeRole, get hold of 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.
Select the hyperlink to the function to open the function and increase the inline coverage to evaluation the permissions, as proven within the following determine.
To confirm if the IAM coverage for add-on to an software execution function is created, get hold of 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.
Select the hyperlink to the coverage title to open the coverage and evaluation the permissions, as proven within the following determine.

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

Most net functions utilizing OAuth 2.0 with an IdP can have applied 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 software 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 obtained from the OIDC IdP with an IAM identification Middle generated JWT token. The newly generated token is then handed on to AssumeRole API to create an identification conscious momentary safety credentials that you should utilize to entry AWS assets.

Be aware: Bear in mind so as to add permissions to your IAM function 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 technique utilizing get_oidc_id_token, get_idc_sts_id_context, or get_sts_credential is out there in <project_home>/src/qbapi_tools/access_helpers.py (AWS Samples – access_helpers.py). An end-to-end pattern implementation of the whole sequence of steps as depicted within the end-to-end authentication sequence is supplied in <project_home>/webapp/principal.py (AWS Samples – main.py).

Restrictions and limitations

Under are some frequent limitations and restrictions that you could be encounter whereas configuring trusted token propagation together with suggestions on the right way to mitigate them.

Group membership propagation

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

Caching credentials to stop invalid grant sorts

You should utilize 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 really useful that the momentary 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 costs, be sure to delete any assets created on this submit.

Observe the directions in Deleting a stack on the AWS CloudFormation console to delete any CloudFormation stacks created utilizing templates supplied on this submit.
If you happen to enabled an IAM Id Middle occasion, observe the directions to delete your IAM Identity Center instance.
Make sure you unregister or delete any IdP providers akin to Okta, Entra ID, Ping Id, or Amazon Cognito that you’ve got created for this submit.
Lastly, delete any pattern code repositories you will have cloned or downloaded, and any related assets deployed as a part of establishing the surroundings 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 Id Middle, organizations can confidently construct AI-powered functions and instruments utilizing Amazon Q Enterprise APIs, figuring out 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 started information. To be taught extra about how trusted token propagation works, see How to develop a user-facing data application with IAM Identity Center and S3 Access Grants.

Concerning the Writer

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

Configure Amazon Q Enterprise with AWS IAM Id Middle trusted identification propagation

Why use trusted identification propagation?

Overview of trusted identification propagation deployment

Authorization movement