External OAuth Middleware
Introduction
Tyk offers two types of OAuth authentication flow; Tyk itself as the identity provider (IdP) and Tyk connecting to an external 3rd party IdP. ‘External OAuth’ is what we call this second mechanism. To call an API that is protected by OAuth, you need to have an access token from the third party IDP (it could be an opaque token or a JWT).
For subsequent calls the access token is provided alongside the API call and needs to be validated. With JWT, Tyk can confirm the validity of the JWT with the secret provided in your config. The secret signs the JWT when created and confirms that none of its contents has changed.
For this reason, information like the expiry date which are often set within the JWT cannot be changed after the JWT has been initially created and signed. This means you are not able to revoke a token before the expiry set in the JWT with the standard JWT flow. With OAuth you can use OAuth introspection to overcome this. With introspection, you can validate the access token via an introspection endpoint that validates the token.
Let’s see how external OAuth middleware is configured.
OAS contract
externalOAuthServer:
enabled: true,
providers: # only one item in the array for now (we're going to support just one IDP config in the first iteration)
- jwt: #validate JWTs generated by 3rd party Oauth servers (like Okta)
enabled: true
signingMethod: HMAC/RSA/ECDSA # to verify signing method used in jwt
source: key # secret to verify signature
issuedAtValidationSkew: 0
notBeforeValidationSkew: 0
expiresAtValidationSkew: 0
identityBaseField: # identity claimName
introspection: # array for introspection details
enabled: true/false
clientID: # for introspection request
clientSecret: # for introspection request, if empty will use oAuth.secret
url: # token introspection endpoint
cache: # Tyk will cache the introspection response when `cache.enabled` is set to `true`
enabled: true/false,
timeout: 0 # The duration (in seconds) for which Tyk will retain the introspection outcome in its cache. If the value is "0", it indicates that the introspection outcome will be stored in the cache until the token's expiration.
identityBaseField: # identity claimName
Tyk Classic API definition contract
"external_oauth": {
"enabled": true,
"providers": [
{
"jwt": {
"enabled": false,
"signing_method": rsa/ecdsa/hmac,
"source": # jwk url/ base64 encoded static secret / base64 encoded jwk url
"identity_base_field": # identity claim name
"expires_at_validation_skew": # validation skew config for exp
"not_before_validation_skew": # validation skew config for nbf
"issued_at_validation_skew" : # validation skew config for iat
},
"introspection": {
"enabled": true,
"url": # introspection endpoint url
"client_id": # client id used for introspection
"client_secret": # client secret to be filled here (plain text for now, TODO: decide on a more secure mechanism)
"identity_base_field": # identity claim name
"cache": {
"enabled": true,
"timeout": # timeout in seconds
}
}
}
]
}
externalOAuthServer
setenabled
totrue
to enable the middleware.providers
is an array of multiple IDP configurations, with each IDP config being an element in theproviders
array.- You can use this config to use JWT self validation using
jwt
or use introspection viainstropection
in theproviders
section .
Note
For now, you’ll be limiting providers
to have only one element, ie one IDP configured.
JWT
There could be cases when you don’t need to introspect a JWT access token from a third party IDP, and instead you can just validate the JWT. This is similar to existing JWT middleware, adding it in External OAuth middleware for semantic reasons.
enabled
- enables JWT validation.signingMethod
- specifies the signing method used to sign the JWT.source
- the secret source, it can be one of:- a base64 encoded static secret
- a valid JWK url in plain text
- a valid JWK url in base64 encoded format
issuedAtValidationSkew
,notBeforeValidationSkew
,expiresAtValidationSkew
can be used to configure clock skew for json web token validation.identityBaseField
- the identity key name for claims. If empty it will default tosub
.
Example: Tyk OAS API definition with JWT validation enabled
"securitySchemes": {
"external_jwt": {
"enabled": true,
"header": {
"enabled": true,
"name": "Authorization"
},
"providers": [
{
"jwt": {
"enabled": true,
"signingMethod": "hmac",
"source": "dHlrLTEyMw==",
"identityBaseField": "sub"
}
}
]
}
}
Example: Tyk Classic API definition with JWT validation enabled
"external_oauth": {
"enabled": true,
"providers": [
{
"jwt": {
"enabled": true,
"signing_method": "hmac",
"source": "dHlrLTEyMw==",
"issued_at_validation_skew": 0,
"not_before_validation_skew": 0,
"expires_at_validation_skew": 0,
"identity_base_field": "sub"
},
"introspection": {
"enabled": false,
"url": "",
"client_id": "",
"client_secret": "",
"identity_base_field": "",
"cache": {
"enabled": false,
"timeout": 0
}
}
}
]
}
Introspection
For cases where you need to introspect the OAuth access token, Tyk uses the information in the provider.introspection
section of the contract. This makes a network call to the configured introspection endpoint with the provided clientID
and clientSecret
to introspect the access token.
enabled
- enables OAuth introspectionclientID
- clientID used for OAuth introspection, available from IDPclientSecret
- secret used to authenticate introspection call, available from IDPurl
- endpoint URL to make the introspection callidentityBaseField
- the identity key name for claims. If empty it will default tosub
.
Caching
Introspection via a third party IdP is a network call. Sometimes it may be inefficient to call the introspection endpoint every time an API is called. Caching is the solution for this situation. Tyk caches the introspection response when enabled
is set to true
inside the cache
configuration of introspection
. Then it retrieves the value from the cache until the timeout
value finishes. However, there is a trade-off here. When the timeout is long, it may result in accessing the upstream with a revoked access token. When it is short, the cache is not used as much resulting in more network calls.
The recommended way to handle this balance is to never set the timeout
value beyond the expiration time of the token, which would have been returned in the exp
parameter of the introspection response.
See the example introspection cache configuration:
"introspection": {
...
"cache": {
"enabled": true,
"timeout": 60 // in seconds
}
}
Example: Tyk OAS API definition external OAuth introspection enabled
"securitySchemes": {
"keycloak_oauth": {
"enabled": true,
"header": {
"enabled": true,
"name": "Authorization"
},
"providers": [
{
"introspection": {
"enabled": true,
"url": "http://localhost:8080/realms/tyk/protocol/openid-connect/token/introspect",
"clientId": "introspection-client",
"clientSecret": "DKyFN0WXu7IXWzR05QZOnnSnK8uAAZ3U",
"identityBaseField": "sub",
"cache": {
"enabled": true,
"timeout": 3
}
}
}
]
}
}
Example: Tyk Classic API definition with external OAuth introspection enabled
"external_oauth": {
"enabled": true,
"providers": [
{
"jwt": {
"enabled": false,
"signing_method": "",
"source": "",
"issued_at_validation_skew": 0,
"not_before_validation_skew": 0,
"expires_at_validation_skew": 0,
"identity_base_field": ""
},
"introspection": {
"enabled": true,
"url": "http://localhost:8080/realms/tyk/protocol/openid-connect/token/introspect",
"client_id": "introspection-client",
"client_secret": "DKyFN0WXu7IXWzR05QZOnnSnK8uAAZ3U",
"identity_base_field": "sub",
"cache": {
"enabled": true,
"timeout": 3
}
}
}
]
}