[TT-13332] Update tyk docs with enhanced upstream authentication (OAuth CC&PW flows)

[andrei-tyk]

User description

For internal users - Please add a Jira DX PR ticket to the subject!

---

Preview Link

Description

Screenshots (if appropriate)

Checklist

• I have added a preview link to the PR description.
• I have reviewed the suggestions made by our AI (PR Agent) and updated them accordingly (spelling errors, rephrasing, etc.)
• I have reviewed the guidelines for contributing to this repository.
• I have read the technical guidelines for contributing to this repository.
• Make sure you have started your change off our latest master.
• I labeled the PR

---

PR Type

Documentation

---

Description

• Added new documentation page for configuring upstream OAuth authentication in Tyk.
• Detailed instructions for setting up client credentials and password grant types.
• Provided JSON configuration examples for both grant types.
• Updated the menu to include links to the new Upstream OAuth documentation.

---

Changes walkthrough 📝

Relevant files

Documentation

oauth.md Add documentation for upstream OAuth authentication setup tyk-docs/content/basic-config-and-security/security/upstream-authentication/oauth.md Added documentation for upstream OAuth authentication. Explained setup for client credentials and password grant types. Included JSON examples for configuration. Described usage of extraMetadata field in request context. +117/-0  menu.yaml Update menu to include Upstream OAuth documentation            tyk-docs/data/menu.yaml Added new menu entry for Upstream Authentication. Included sub-entry for Upstream OAuth documentation. +8/-0

---

💡 PR-Agent usage: Comment /help "your question" on any pull request to receive relevant information

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

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

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Configuration Duplication The configuration for OAuth authentication is duplicated for 'clientCredentials' and 'password' grant types. Consider refactoring to reduce redundancy and improve maintainability. Hardcoded Values The examples contain hardcoded values for 'clientId', 'clientSecret', 'tokenUrl', and other sensitive information. Ensure these are placeholders and advise users to secure their actual credentials.

[github-actions]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Score
Security	Replace hardcoded sensitive credentials with references to secure storage mechanisms Ensure that sensitive information such as clientSecret and password is not hardcoded in the documentation examples. Instead, suggest using environment variables or secure vault solutions to manage sensitive credentials. tyk-docs/content/basic-config-and-security/security/upstream-authentication/oauth.md [52-101] -"clientSecret": "secret123", -"password": "pass", +"clientSecret": "${CLIENT_SECRET}", +"password": "${USER_PASSWORD}", Suggestion importance[1-10]: 9 Why: This suggestion is crucial for security best practices, ensuring that sensitive data like client secrets and passwords are not exposed in documentation examples.	9
	Highlight security considerations for using the password grant type in OAuth Add a warning or note about the security implications of using the password grant type, as it involves sending user credentials directly and can be less secure than other OAuth flows. tyk-docs/content/basic-config-and-security/security/upstream-authentication/oauth.md [63-65] ### Password Grant +**Security Warning:** This grant type involves transmitting user credentials directly, which can be less secure. Consider other OAuth flows for enhanced security. Suggestion importance[1-10]: 7 Why: This suggestion is relevant as it adds important security warnings regarding the use of the password grant type, which is less secure compared to other OAuth flows.	7
Best practice	Recommend implementing error handling for OAuth token acquisition failures Suggest adding error handling advice for scenarios where the OAuth token acquisition fails, to improve the robustness of the integration. tyk-docs/content/basic-config-and-security/security/upstream-authentication/oauth.md [50] "tokenUrl": "http://salesforce.com", +"errorHandling": "Log and alert on token acquisition failure", Suggestion importance[1-10]: 6 Why: Adding error handling mechanisms for token acquisition failures is a practical improvement for robustness and reliability of the OAuth integration.	6
	Advise on validating OAuth scopes to adhere to the principle of least privilege Recommend validating the scopes array to ensure that only necessary permissions are requested to minimize security risks and adhere to the principle of least privilege. tyk-docs/content/basic-config-and-security/security/upstream-authentication/oauth.md [53] -"scopes": ["scope1"], +"scopes": ["necessary_scope"], Suggestion importance[1-10]: 5 Why: The suggestion to validate OAuth scopes is a good practice to ensure minimal permissions are granted, enhancing security but it's a moderate improvement.	5

[netlify]

✅ PS. Pls add /docs/nightly to the end of url

Name	Link
🔨 Latest commit	db5f5c8
🔍 Latest deploy log	https://app.netlify.com/sites/tyk-docs/deploys/672b3c5a6e65380008fd6bab
😎 Deploy Preview	https://deploy-preview-5695--tyk-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[netlify]

✅ PS. Pls add /docs/nightly to the end of url

Name	Link
🔨 Latest commit	db5f5c8
🔍 Latest deploy log	https://app.netlify.com/sites/tyk-docs/deploys/672b3c5a6e65380008fd6bab
😎 Deploy Preview	https://deploy-preview-5695--tyk-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[sharadregoti]

Marking it as draft. As @andyo-tyk will use this content to create a new PR.