AWS bedrock-agentcore high security documentation change
Summary
Added documentation for automatic refresh token handling, resource indicators in OAuth2 flows, and restructured content. Includes provider-specific configurations for refresh tokens and security considerations for token validity.
Security assessment
The changes introduce security documentation about refresh token storage/rotation and resource indicators (RFC 8707 implementation). The 'Important' note about token revocation detection and forceAuthentication parameter addresses a security gap where invalid tokens might be used. Resource indicators enforce least-privilege access to specific resource servers.
Diff
diff --git a/bedrock-agentcore/latest/devguide/identity-authentication.md b/bedrock-agentcore/latest/devguide/identity-authentication.md index f752694c6..ffe186bb6 100644 --- a//bedrock-agentcore/latest/devguide/identity-authentication.md +++ b//bedrock-agentcore/latest/devguide/identity-authentication.md @@ -5,3 +5 @@ -Streaming authorization URLs to application callers - -Amazon Bedrock AgentCore is in preview release and is subject to change. +Refresh token storageStreaming authorization URLs to application callersResource indicators in AgentCore OAuth2 flows @@ -11 +9 @@ Amazon Bedrock AgentCore is in preview release and is subject to change. -AgentCore Identity enables developers to obtain OAuth tokens for either user-delegated access or machine-to-machine authentication based on the configured OAuth 2.0 credential providers. The service will orchestrate the authentication process between the user or application to the downstream authorization server, and it will retrieve and store the resulting token. Once the token is available in the AgentCore Identity vault, authorized agents can retrieve it and use it to authorize calls to resource servers. For example, the sample code below will retrieve a token to interact with Google Drive on behalf of an end user. For more information, see [Getting started with Amazon Bedrock AgentCore Identity](./identity-getting-started.html) for the complete example. +AgentCore Identity enables developers to obtain OAuth tokens for either user-delegated access or machine-to-machine authentication based on the configured OAuth 2.0 credential providers. The service will orchestrate the authentication process between the user or application to the downstream authorization server, and it will retrieve and store the resulting token. Once the token is available in the AgentCore Identity vault, authorized agents can retrieve it and use it to authorize calls to resource servers. For example, the sample code below will retrieve a token to interact with Google Drive on behalf of an end user. For more information, see [Integrate with Google Drive using OAuth2](./identity-getting-started-google.html) for the complete example. @@ -38,0 +37,52 @@ The process is similar to obtain a token for machine-to-machine calls, as shown +###### Topics + + * Automatic refresh token storage and usage + + * Streaming authorization URLs to application callers + + * Resource indicators in AgentCore OAuth2 flows + + + + +## Automatic refresh token storage and usage + +AgentCore automatically stores and uses refresh tokens when available from OAuth2 providers, reducing the frequency of user reauthorization prompts. When users initially grant consent through a standard OAuth2 authorization code flow, the system stores both access tokens and refresh tokens (if provided) in the secure token vault. This enables agents to obtain fresh access tokens automatically when the original tokens expire, improving user experience by minimizing repeated consent requests. + +###### Important + +Access tokens returned by AgentCore are not guaranteed to be valid. Tokens can be revoked by customers on the federated provider side, which AgentCore cannot detect. If a token is invalid, use `forceAuthentication: true` to force a new authentication flow and obtain a valid access token. + +Refresh tokens typically have longer lifespans than access tokens, with a default validity period of approximately 30 days compared to the shorter lifespan of access tokens (often 1-2 hours). When an access token expires, AgentCore automatically uses the stored refresh token to request a new access token from the provider. **If a valid refresh token is stored, AgentCore skips the user federation flow and directly returns a new access token**. If the refresh token is also expired or invalid, the system falls back to prompting the user for full reauthorization. + +This feature requires no configuration within AgentCore - it operates automatically when refresh tokens are present in the OAuth2 provider's token response. However, you must configure your OAuth2 provider to include refresh tokens in the authorization flow. The specific configuration depends on your provider: + +Provider | Configuration Required +---|--- +**Google** | Include `access_type=offline` in `customParameters` when calling `GetResourceOauth2Token` + + + "customParameters": { "access_type": "offline" } + +**Microsoft** | Include `offline_access` in `scopes` parameter when calling `GetResourceOauth2Token` + + + "scopes": ["openid", "profile", "offline_access"] + +**Salesforce** | Include `refresh_token` in `scopes` parameter when calling `GetResourceOauth2Token` + + + "scopes": ["api", "refresh_token"] + +**Atlassian** | Include `offline_access` in `scopes` parameter when calling `GetResourceOauth2Token` + + + "scopes": ["read:jira-user", "offline_access"] + +**GitHub** | No extra AgentCore configuration required. Enable User-to-server token expiration feature in your GitHub app settings. Refresh tokens are stored automatically when this feature is enabled. +**Slack** | No extra AgentCore configuration required. Enable "token rotation" feature in your Slack app settings. Refresh tokens are returned automatically when this feature is enabled. +**LinkedIn** | No extra AgentCore configuration required. Enable refresh token settings in your LinkedIn app configuration. +**Other providers** | Some providers require configuration in their provider settings rather than API parameters. Consult your provider's documentation for refresh token requirements. + +If your provider supports refresh tokens and is properly configured, AgentCore will automatically store and manage them without additional setup. To clear stored refresh tokens and force users to reauthenticate, set `forceAuthentication=true` when calling GetResourceOauth2Token. This clears the refresh token and forces a complete federation flow. For information about configuring OAuth2 providers, see [Provider setup and configuration](./identity-idps.html). + @@ -43 +93 @@ For three-legged OAuth (3LO) flows, your agent needs to provide the authorizatio -**Common implementation patterns:** +**Common implementation patterns** @@ -45 +95 @@ For three-legged OAuth (3LO) flows, your agent needs to provide the authorizatio -**Streaming response pattern:** For applications that support streaming responses, you can send the authorization URL as part of the response stream: +**Streaming response pattern** – For applications that support streaming responses, you can send the authorization URL as part of the response stream: @@ -73 +123 @@ For three-legged OAuth (3LO) flows, your agent needs to provide the authorizatio -**Callback pattern:** For applications using callbacks or webhooks, store the authorization URL and notify the caller: +**Callback pattern** – For applications using callbacks or webhooks, store the authorization URL and notify the caller: @@ -105 +155 @@ For three-legged OAuth (3LO) flows, your agent needs to provide the authorizatio -**Polling pattern:** For applications that prefer polling, store the authorization URL in a retrievable location: +**Polling pattern** – For applications that prefer polling, store the authorization URL in a retrievable location: @@ -132,0 +183,8 @@ Choose the pattern that best fits your application architecture. Streaming respo +## Resource indicators in AgentCore OAuth2 flows + +Resource indicators provide a standardized way to specify which resource server should accept an OAuth2 access token. AgentCore uses Cognito as its authentication provider, which supports RFC 8707-compliant resource indicators that allow you to specify the intended resource server during token requests. To use resource indicators, you must first configure the authorization server to recognize specific resource servers using Cognito's CreateResourceServer API. Once configured, when you specify a resource indicator in your token request, Cognito includes the corresponding resource server identifier in the aud claim of the resulting token, enabling the resource server to verify that the token is intended for its specific use. This provides several important benefits: resource servers can validate that tokens are specifically intended for them (principle of least privilege), improved auditability by clearly identifying which resource server each token targets, and reduced risk of token misuse across different services within your application environment. + +Through Cognito's [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html) implementation, AgentCore enables clients to specify a resource server directly in authorization and token requests, overriding the default audience parameter. In Cognito, the 'resource indicator' referred to in the RFC corresponds to the [ResourceServer's](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateResourceServer.html) 'identifier' value. Resource indicators are particularly important for Model Context Protocol (MCP) implementations, where they help mitigate specific security risks outlined in the MCP authorization specification. The resource indicator corresponds to the RFC 9728 resource parameter, ensuring proper token scoping for MCP server interactions. Note that the current implementation supports single-resource binding, meaning you can specify one resource server per token request. + +Use resource indicators when your agents need to access resource servers with specific security requirements, or when you need fine-grained control over token audience validation. Resource indicators are particularly useful for multi-tenant applications where tokens should be restricted to specific customer resources. + @@ -141 +199 @@ Get workload access token -Scope credential access +OAuth 2.0 authorization URL session binding