[TT-17611] IAM authentication for Google Cloud

[andyo-tyk]

User description

Added GCP IAM authentication guide for Redis/Valkey

---

PR Type

Documentation, Enhancement

---

Description

• Document Redis IAM authentication for Google Cloud

• Add config fields, versions, examples

• Extend coverage to MDCB and TIB

• Add Google IAM troubleshooting guidance

---

Diagram Walkthrough

flowchart LR
  tyk["Tyk components"]
  adc["Google ADC identity discovery"]
  iam["Google Cloud IAM"]
  token["Short-lived access token"]
  redis["Memorystore Redis or Valkey"]

  tyk -- "discovers identity via" --> adc
  adc -- "requests token from" --> iam
  iam -- "issues" --> token
  tyk -- "uses token to connect" --> redis

Loading

File Walkthrough

Relevant files

Documentation

redis-cluster-sentinel.mdx Add Redis IAM auth configuration guidance                                tyk-configuration-reference/redis-cluster-sentinel.mdx Expand Redis config scope to include Tyk MDCB Add IAM authentication overview and minimum versions Document iam_auth fields, GCP setup, and examples Add Google Cloud IAM troubleshooting guidance +115/-4  standalone-tib.mdx Document TIB IAM auth Redis settings                                          tyk-identity-broker/standalone-tib.mdx Add IAMAuth configuration for TIB Redis backend Link TIB setup to shared IAM guidance Provide JSON example using Provider: gcp Document enablement, impersonation, and refresh fields +27/-0

---

[probelabs]

This pull request introduces documentation for a new feature that enables IAM-based authentication for Tyk components connecting to Google Cloud Memorystore for Redis and Valkey. This provides a more secure, passwordless authentication method using short-lived tokens based on workload identity, aligning with modern cloud security best practices.

The documentation covers the configuration process, prerequisites, and troubleshooting steps for Tyk Gateway, Dashboard, Pump, MDCB, and the Tyk Identity Broker (TIB).

Files Changed Analysis

The changes are primarily additive, introducing new documentation for the IAM authentication feature across four files:

• tyk-configuration-reference/redis-cluster-sentinel.mdx: This is the core of the update, with +212 additions. It adds a new, detailed section on IAM authentication, covering the concept, minimum version requirements for each component, the new iam_auth configuration block, Google Cloud-specific prerequisites (like Application Default Credentials), and a new troubleshooting guide. It also expands its scope to officially include Tyk MDCB.
• tyk-identity-broker/standalone-tib.mdx: This file is updated (+27 additions) to document the corresponding IAMAuth configuration for the Tyk Identity Broker, ensuring documentation is consistent across all components.
• snippets/redis-versions-include.mdx & tyk-self-managed/install.mdx: These files received minor updates to remove outdated information and add a link to the new production configuration guidance.

The changes consist almost entirely of new content, reflecting the documentation of a new cross-component feature.

Architecture & Impact Assessment

• What this PR accomplishes: It documents a new, more secure method for Tyk components to authenticate with Google Cloud Memorystore. This shifts from static passwords to short-lived, auto-refreshed tokens, which is a significant security improvement.

• Key technical changes introduced: The documentation describes new configuration blocks:

  • iam_auth for Tyk Gateway, Pump, and MDCB.
  • redis_iam_auth for Tyk Dashboard.
  • IAMAuth for Tyk Identity Broker.
    These blocks enable IAM authentication, specify the cloud provider as gcp, and allow for service account impersonation.

• Affected system components: The documentation impacts the configuration and operation of:

  • Tyk Gateway
  • Tyk Dashboard
  • Tyk Pump
  • Tyk MDCB
  • Tyk Identity Broker (TIB)

• Authentication Flow: The documentation describes how Tyk components interact with Google Cloud IAM to obtain OAuth2 tokens and use them for connecting to Google Memorystore.

  flowchart LR
    tyk["Tyk components"]
    adc["Google ADC identity discovery"]
    iam["Google Cloud IAM"]
    token["Short-lived access token"]
    redis["Memorystore Redis or Valkey"]
  
    tyk --|discovers identity via|--> adc
    adc --|requests token from|--> iam
    iam --|issues|--> token
    tyk --|uses token to connect|--> redis
  
  

  Loading

## Scope Discovery & Context Expansion

- The scope of this PR is limited to documentation, but it provides essential context for a significant underlying feature enhancement across multiple Tyk products. The specified minimum version requirements (e.g., Gateway 5.15.0) confirm this is tied to a new feature release.
- The documentation is specific to Google Cloud (`provider: "gcp"`), which implies a potential architectural pattern for future integrations with other cloud providers' IAM services (e.g., AWS IAM for ElastiCache).
- To further understand the implementation, an engineer would need to investigate the source code of the affected components (Tyk Gateway, Tyk Pump, etc.), searching for terms like `iam_auth`, `gcp`, and `Application Default Credentials` to see how the token acquisition and Redis connection logic were implemented.


<details>
  <summary>Metadata</summary>

  - Review Effort: 2 / 5
  - Primary Label: documentation


</details>
<!-- visor:section-end id="overview" -->

<!-- visor:thread-end key="TykTechnologies/tyk-docs#2766@cf526af" -->

---

*Powered by [Visor](https://probelabs.com/visor) from [Probelabs](https://probelabs.com)*

*Last updated: 2026-08-26T14:16:12.275Z | Triggered by: pr_updated | Commit: cf526af*

💡 **TIP:** You can chat with Visor using `/visor ask <your question>`
<!-- /visor-comment-id:visor-thread-overview-TykTechnologies/tyk-docs#2766 -->

[probelabs]

✅ Security Check Passed

No security issues found – changes LGTM.

Architecture Issues (2)

Severity	Location	Issue
🟠 Error	tyk-identity-broker/standalone-tib.mdx:212-224	The IAM authentication configuration for Tyk Identity Broker (TIB) uses a different naming convention (PascalCase for the `IAMAuth` block and its fields) compared to all other Tyk components, which use snake_case (`iam_auth`). Introducing a conflicting naming convention for the same feature within the same product suite is a significant architectural inconsistency. This violates the principle of consistency, increases cognitive load, and makes automation and configuration management more complex and error-prone.
🟡 Warning	tyk-configuration-reference/redis-cluster-sentinel.mdx:353	The configuration for IAM authentication on Tyk Dashboard (`redis_iam_auth` at the top level) is architecturally inconsistent with other components (Gateway, Pump, MDCB) where it is a nested `iam_auth` block. While this may follow an existing pattern for Dashboard configuration, extending this pattern for a new, cross-component feature introduces unnecessary special-casing and complexity for operators managing a full Tyk stack. A unified configuration structure would be simpler and less error-prone.

✅ Security Check Passed

No security issues found – changes LGTM.

\n\n

Architecture Issues (2)

Severity	Location	Issue
🟠 Error	tyk-identity-broker/standalone-tib.mdx:212-224	The IAM authentication configuration for Tyk Identity Broker (TIB) uses a different naming convention (PascalCase for the `IAMAuth` block and its fields) compared to all other Tyk components, which use snake_case (`iam_auth`). Introducing a conflicting naming convention for the same feature within the same product suite is a significant architectural inconsistency. This violates the principle of consistency, increases cognitive load, and makes automation and configuration management more complex and error-prone.
🟡 Warning	tyk-configuration-reference/redis-cluster-sentinel.mdx:353	The configuration for IAM authentication on Tyk Dashboard (`redis_iam_auth` at the top level) is architecturally inconsistent with other components (Gateway, Pump, MDCB) where it is a nested `iam_auth` block. While this may follow an existing pattern for Dashboard configuration, extending this pattern for a new, cross-component feature introduces unnecessary special-casing and complexity for operators managing a full Tyk stack. A unified configuration structure would be simpler and less error-prone.

\n\n ### Performance Issues (2)

Severity	Location	Issue
🟡 Warning	tyk-configuration-reference/redis-cluster-sentinel.mdx:350	The documentation for `token_refresh_before_expiry` lacks guidance on choosing a safe and efficient value. A very small value (e.g., under a minute) is risky as it leaves little time for the refresh operation to complete, potentially causing connection failures. A very large value (e.g., `30m`) will cause more frequent token refreshes than necessary, increasing load on the IAM provider and potentially leading to rate limiting. 💡 Suggestion Add guidance on the trade-offs of this setting and recommend a safe range. For example: 'The default of `5m` is recommended for most use cases. This value should be large enough to accommodate network latency and retries during the refresh process. Setting it below one minute is not recommended. Values larger than `15m` may result in excessive API calls to the identity provider.'
🟡 Warning	tyk-identity-broker/standalone-tib.mdx:227	The documentation for `IAMAuth.TokenRefreshBeforeExpiry` lacks guidance on choosing a safe and efficient value. A very small value (e.g., under a minute) is risky as it leaves little time for the refresh operation to complete, potentially causing connection failures. A very large value (e.g., `30m`) will cause more frequent token refreshes than necessary, increasing load on the IAM provider and potentially leading to rate limiting. 💡 Suggestion Add guidance on the trade-offs of this setting and recommend a safe range. For example: 'The default of `5m` is recommended for most use cases. This value should be large enough to accommodate network latency and retries during the refresh process. Setting it below one minute is not recommended. Values larger than `15m` may result in excessive API calls to the identity provider.'

Quality Issues (1)

Severity	Location	Issue
🟡 Warning	tyk-identity-broker/standalone-tib.mdx:208	The documentation for IAM authentication in Tyk Identity Broker (TIB) does not specify the minimum TIB version required to use this feature. The main Redis documentation (`redis-cluster-sentinel.mdx`) provides a table of minimum versions for Tyk Gateway, Dashboard, Pump, and MDCB, but TIB is not included. This omission makes it difficult for users to know if their TIB version supports this new authentication method. 💡 Suggestion Add a note specifying the minimum version of TIB that supports IAM authentication with Redis. For example: "Note: IAM authentication requires TIB version X.Y.Z or later."

---

Powered by Visor from Probelabs

Last updated: 2026-08-26T14:15:28.015Z | Triggered by: pr_updated | Commit: cf526af

💡 TIP: You can chat with Visor using /visor ask <your question>

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 1 🔵⚪⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ No major issues detected

[github-actions]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Fix MDCB config location This list contradicts the earlier statement that iam_auth is nested under storage for Tyk MDCB. If storage is omitted here, users can place the block in the wrong location and end up with IAM auth silently not being applied to MDCB's primary Redis connection. tyk-configuration-reference/redis-cluster-sentinel.mdx [366] -- **Tyk MDCB:** `analytics_storage` (used when `enable_separate_analytics_store` is set) +- **Tyk MDCB:** `storage` and `analytics_storage` (used when `enable_separate_analytics_store` is set) Suggestion importance[1-10]: 7 __ Why: This correctly identifies an internal contradiction: the earlier text says iam_auth is nested under storage for Tyk MDCB, but the later list omits storage. Clarifying the valid MDCB locations would prevent users from placing iam_auth in the wrong config block.	Medium
	Restrict supported service scope This wording overstates support and implies IAM works with any cloud-managed Redis or Valkey service. Narrow it to the currently supported Google Cloud services so operators do not attempt unsupported AWS, Azure, or legacy Memorystore setups that will fail at runtime. tyk-identity-broker/standalone-tib.mdx [205] -As an alternative to `Password`, TIB can authenticate to a cloud-managed Redis or Valkey instance with short-lived IAM tokens instead. See [IAM Authentication](/tyk-configuration-reference/redis-cluster-sentinel#iam-authentication) for how this works and the Google Cloud prerequisites. TIB's equivalent fields are nested under `IAMAuth`: +As an alternative to `Password`, TIB can authenticate to Google Cloud Memorystore for Valkey and Memorystore for Redis Cluster with short-lived IAM tokens instead. Legacy (non-cluster) Memorystore for Redis is not supported with IAM authentication. See [IAM Authentication](/tyk-configuration-reference/redis-cluster-sentinel#iam-authentication) for how this works and the Google Cloud prerequisites. TIB's equivalent fields are nested under `IAMAuth`: Suggestion importance[1-10]: 6 __ Why: This suggestion is accurate because the broader Redis guide explicitly limits IAM support to Google Cloud Memorystore for Valkey and Memorystore for Redis Cluster. Narrowing the wording in standalone-tib.mdx improves correctness and avoids implying unsupported providers or legacy services will work.	Low

[sharadregoti]

Merging this PR into the docs 5.15 base branch to maintain the PR queue.