You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
The new heading "Custom Authentication Golang Plugins" replaces previous guidance about using the "auth_check" middleware and Post Authentication Hook; ensure readers still understand the need to bind the middleware correctly and when to set session persistence.
## Custom Authentication Golang Plugins
You can implement your own authentication method, written in Golang.
Let's have a look at the code example. Imagine we need to implement a very trivial authentication method when only one key is supported (in the real world you would want to store your keys in some storage or have some more complex logic).
The note states that providing "rate_limit_pattern" becomes the new identity for both rate-limit and quota; verify this behavior across Gateway versions and note any version constraints or caveats (e.g., analytics identity, key hashing).
### Custom Rate Limiting- By default, Tyk derives the rate limiter key from `session.KeyID`.
- If you want a custom limiter key, set `session.MetaData["rate_limit_pattern"]` to a string. Tyk will evaluate it (supports `$tyk_meta.*` and `$tyk_context.*`) and use the resulting value as both the rate-limit key and quota key.
```go// Custom limiter/quota key example
sessionObject = &user.SessionState{
OrgID: requestedAPI.OrgID,
Rate: 2,
Per: 5,
MetaData: map[string]interface{}{
// A counter is created for each "rate_limit_pattern".// This becomes your new identity."rate_limit_pattern": realIp,
},
}
Notes:
If you provide rate_limit_pattern, Tyk uses that value directly (no auto-hashing). If you need hashing, hash it in your plugin before assigning.
</details>
<details><summary><a href='https://github.com/TykTechnologies/tyk-docs/pull/6963/files#diff-0c36572e2685d145460b6acda22c4249165e6b52ccb9736e3e4a28974d7fc6eeR1094-R1105'><strong>Persistence Scope</strong></a>
The statement about SetSession(..., true) persisting only to local Data Plane Redis could confuse multi-DP setups; consider clarifying implications for sharded/clustered Redis and key lifecycle/cleanup.
</summary>
```markdown
### Persisting the key
By default -- custom auth keys aren't persisted beyond what's necessary to track rate limits, quotas, analytics, and so on.
However -- you may choose to persist the keys in the custom plugin.
```go
// Set session state using session object
ctx.SetSession(r, sessionObject, true)
The third argument in the parameter instructs the Gateway to save/persist the key. Note -- this isn't a global operation -- this would be scoped to the local Data Plane's redis.
Warn that leaving KeyID empty applies limits globally across requestors. Add a guard to ensure identity is non-empty before setting the session to avoid accidental global throttling.
+if identity == "" {+ http.Error(rw, "unauthorized", http.StatusUnauthorized)+ return+}
s := &user.SessionState{
OrgID: "default",
- // This is the default way that Tyk will track your identities.- // Using "KeyID".- // Usually, this should be set, otherwise, the below - // rate limits will be applied globally across all API requestors.- KeyID: identity, // identity used for bucketing (via hash)- Rate: 100, // 100 requests- Per: 60, // per 60 seconds- // Optional quotas+ KeyID: identity,+ Rate: 100,+ Per: 60,
// QuotaMax: 10000,
// QuotaRenewalRate: 86400,
}
Suggestion importance[1-10]: 7
__
Why: The guard against empty identity aligns with the snippet's warning that empty KeyID applies limits globally; adding a simple check improves correctness and avoids unintended global throttling. It's a meaningful but straightforward improvement.
Medium
General
Document backward-compatible call
The SetSession signature shown omits the API key parameter that may be required on older Gateway versions. Add a brief note showing the alternative call for backward compatibility to prevent runtime mismatches.
+// For Gateway >= 4.0.1
ctx.SetSession(r, s, false)
+// For older Gateways, use:+// ctx.SetSession(r, s, identity, true)
Suggestion importance[1-10]: 6
__
Why: The note about older Gateway SetSession signature is accurate given prior docs removed such guidance; adding the alternative prevents runtime mismatches on older versions. Impact is moderate since it's a documentation clarification rather than a functional fix.
Low
Enforce string type for limiter key
Clarify that rate_limit_pattern must be a string; passing non-string types (like net.IP) can lead to unexpected keys. Show explicit conversion to string for safety.
sessionObject = &user.SessionState{
OrgID: requestedAPI.OrgID,
Rate: 2,
Per: 5,
MetaData: map[string]interface{}{
- // A counter is created for each "rate_limit_pattern".- // This becomes your new identity.- "rate_limit_pattern": realIp,+ "rate_limit_pattern": realIp.String(), // ensure string
},
}
Suggestion importance[1-10]: 6
__
Why: Clarifying rate_limit_pattern should be a string and showing realIp.String() helps prevent subtle bugs from non-string types being stored, improving reliability. The change is correct and useful but not critical.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
User description
Contributor checklist
New Contributors
masterPR Type
Documentation
Description
Revamp custom auth plugin section
Add identity and session usage notes
Document custom rate limiting pattern
Explain key persistence with SetSession
Diagram Walkthrough
File Walkthrough
golang.md
Expanded guidance for Golang custom authentication pluginstyk-docs/content/api-management/plugins/golang.md