From ee9f9e283e0bde3918bc0b27569c3e5c0fc46f4d Mon Sep 17 00:00:00 2001 From: Andrei Date: Wed, 6 Nov 2024 11:39:08 +0200 Subject: [PATCH 1/2] TT-13332, added docs for upstream OAuth --- .../security/upstream-authentication/oauth.md | 118 ++++++++++++++++++ tyk-docs/data/menu.yaml | 8 ++ 2 files changed, 126 insertions(+) create mode 100644 tyk-docs/content/basic-config-and-security/security/upstream-authentication/oauth.md diff --git a/tyk-docs/content/basic-config-and-security/security/upstream-authentication/oauth.md b/tyk-docs/content/basic-config-and-security/security/upstream-authentication/oauth.md new file mode 100644 index 0000000000..8f2ac21368 --- /dev/null +++ b/tyk-docs/content/basic-config-and-security/security/upstream-authentication/oauth.md @@ -0,0 +1,118 @@ +--- +title: Upstream OAuth Authentication +tags: ["upstream-oauth-auth"] +description: "How to authenticate upstream requests with OAuth authentication" +menu: + main: + parent: "Upstream Authentication" +weight: 3 +--- + +If your upstream API is protected with OAuth authentication, you can configure Tyk to send requests with OAuth authentication credentials. + +## How To Set Up + +### Via API Definition + +Inside your OAS API definition you should configure `x-tyk-api-gateway.upstream.authentication.oauth` field. + +### Client Credentials Grant + +To use the client credentials grant type, configure the following fields: + +- `enabled` needs to be true to enable OAuth authentication. +- `allowedAuthorizeTypes` should include `clientCredentials`. +- `clientCredentials` should be configured with: + - `header.enabled` set to true. + - `header.name` is the header to be used. + - `tokenUrl` is the URL to obtain the token. + - `clientId` is the client ID to be used. + - `clientSecret` is the client secret to be used. + - `scopes` is an array of scopes to be requested. + - `extraMetadata` is an array of additional fields to be read from the OAuth provider response and saved to the request context. + +Example: +```json +{ + "x-tyk-api-gateway": { + "upstream": { + "authentication": { + "enabled": true, + "oauth": { + "enabled": true, + "allowedAuthorizeTypes": [ + "clientCredentials" + ], + "clientCredentials": { + "header": { + "enabled": true, + "name": "Authorization" + }, + "tokenUrl": "http://salesforce.com", + "clientId": "client123", + "clientSecret": "secret123", + "scopes": ["scope1"], + "extraMetadata": ["instance_url"] + } + } + } + } + } +} +``` + +### Password Grant + +To use the password grant type, configure the following fields: +- `enabled` needs to be true to enable OAuth authentication. +- `allowedAuthorizeTypes` should include `password`. +- `password` should be configured with: + - `header.enabled` set to true. + - `header.name` is the header to be used. + - `tokenUrl` is the URL to obtain the token. + - `clientId` is the client ID to be used. + - `clientSecret` is the client secret to be used. + - `scopes` is an array of scopes to be requested. + - `username` is the username to be used. + - `password` is the password to be used. + - `extraMetadata` is an array of additional fields to read from the OAuth provider response and saved to the request context. + + +Example: +```json +{ + "x-tyk-api-gateway": { + "upstream": { + "authentication": { + "oauth": { + "enabled": true, + "allowedAuthorizeTypes": [ + "password" + ], + "password": { + "header": { + "enabled": true, + "name": "Authorization" + }, + "tokenUrl": "http://salesforce.com", + "clientId": "client123", + "clientSecret": "secret123", + "scopes": ["scope1"], + "username": "user", + "password": "pass", + "extraMetadata": ["instance_url"] + } + } + } + } + } +} +``` + +**Note** +If the `extraMetadata` field is configured, the response from the OAuth provider will be parsed and the fields specified in the `extraMetadata` array will be saved to the request context. +Those fields can be accessed in the middlewares (e.g. URL Rewrite) via the $tyk_context object. +In our use case, the `instance_url` field will be saved to the request context and can be accessed in the URL Rewrite middleware as `$tyk_context.instance_url`. +However, when creating a matching rule based on Request Context in the URL Rewrite middleware, the field identifier is just `instance_url` as $tyk_context is implied. + + diff --git a/tyk-docs/data/menu.yaml b/tyk-docs/data/menu.yaml index bc72b70a57..6ac3911efa 100644 --- a/tyk-docs/data/menu.yaml +++ b/tyk-docs/data/menu.yaml @@ -1380,6 +1380,14 @@ menu: path: /basic-config-and-security/security/authentication-authorization/json-web-tokens/jwt-keycloak category: Page show: True + - title: "Upstream Authentication" + category: Directory + show: True + menu: + - title: "Upstream OAuth" + path: /basic-config-and-security/security/upstream-authentication/oauth + category: Page + show: True - title: "MTLS" category: Directory show: True From db5f5c85becb3882f415ce955a865ccd882d352d Mon Sep 17 00:00:00 2001 From: Andrei Date: Wed, 6 Nov 2024 11:51:51 +0200 Subject: [PATCH 2/2] TT-13332, fixed small mistake --- .../security/upstream-authentication/oauth.md | 1 - 1 file changed, 1 deletion(-) diff --git a/tyk-docs/content/basic-config-and-security/security/upstream-authentication/oauth.md b/tyk-docs/content/basic-config-and-security/security/upstream-authentication/oauth.md index 8f2ac21368..562120367f 100644 --- a/tyk-docs/content/basic-config-and-security/security/upstream-authentication/oauth.md +++ b/tyk-docs/content/basic-config-and-security/security/upstream-authentication/oauth.md @@ -39,7 +39,6 @@ Example: "authentication": { "enabled": true, "oauth": { - "enabled": true, "allowedAuthorizeTypes": [ "clientCredentials" ],