This quickstart is for developers familiar with Tyk who are looking for a quick intro into how they can add Approov into an existing project. Therefore this will guide you through the necessary steps for adding Approov to an existing Tyk API Gateway.
To lock down your API server to your mobile app. Please read the brief summary in the README at the root of this repo or visit our website for more details.
For more background, see the overview in the README at the root of this repo.
To complete this quickstart you will need to already have an Tyk API Gateway created, and the Approov CLI tool installed.
- Tyk API Gateway
- Approov CLI - Learn how to use it here
To use Approov with the Tyk API Gateway we need a small amount of configuration. First, Approov needs to know the API domain that will be protected. Second, the Tyk API Gateway needs the Approov Base64 encoded secret that will be used to verify the tokens generated by the Approov cloud service.
Approov needs to know the domain name of the API for which it will issue tokens.
Add it with:
approov api -add your.tyk-api-gateway.domain.comAdding the API domain also configures the dynamic certificate pinning setup, out of the box.
NOTE: By default the pin is extracted from the public key of the leaf certificate served by the domain, as visible to the box issuing the Approov CLI command and the Approov servers.
Approov tokens are signed with a symmetric secret. To verify tokens, we need to grab the secret using the Approov secret command and plug it into the Tyk API Gateway configuration to check the signatures of the Approov Tokens that it processes.
To retrieve the Approov secret you need to enable your admin role with:
eval `approov role admin`For the Windows powershell:
set APPROOV_ROLE=admin:___YOUR_APPROOV_ACCOUNT_NAME_HERE___Retrieve the Approov secret with:
approov secret -get base64Keep it at hand, because you will need it in the next step.
To verifyiu the Approov token in any existing Tyk API Gateway project we just need to enable the JWT check and to create a security policy for the API we want to protect with Approov.
First, create a new Tyk security policy for the Approov token check. Tyk supports several ways of creating a security policy, but all of them require the same fields to be given, therefore use the approach you are more comfortable with, and ensure that the following fields are set:
{
"approov": {
"access_rights": {
"___YOUR_API_ID_HERE___": {
"allowed_urls": [],
"api_id": "___YOUR_API_ID_HERE___",
"api_name": "___YOUR_API_NAME_HERE___}",
"versions": [
"Default"
]
}
},
"org_id": "___YOUR_ORG_ID_HERE___",
"active": true,
"name": "Approov",
"rate": 0,
"per": 1,
"quota_max": -1,
"state": "active",
"tags": ["Approov"]
}
}Next, you need to enable the JWT check with the approov security policy on the API you want to protect with Approov. Enabling the JWT check will disable your current API key check, therefore you may want to follow instead the Approov Token Python Plugin Quickstart, that checks the Approov token in the Tyk Middleware on a pre Hook, before user authentication or API Keys checks.
To update the API use the method of your preference and ensure that the API definition has the following fields set:
"auth": {
"auth_header_name": "Approov-Token"
},
"jwt_signing_method": "hmac",
"jwt_identity_base_field": "iss",
"jwt_default_policies": ["approov"],
"jwt_source": "vault://engine/path/to/secret.___APPROOV_BASE64_SECRET_VAR_NAME_HERE___"NOTE: Tyk supports more then one mechanism to securely retrieve secrets, therefore you you are free to use one of your preference to retrieve the Approov secret for the key jwt_source, but never provide it hard-coded in the JSON configuration. For more information visit their docs page: Key Value secrets storage for configuration in Tyk.
Finally, reload your Tyk API Gateway and confirm that only serves API requests with a correctly signed and not expired Approov-Token header. The next section has some guidance on how to test your Approov integration.
A full working example can be found at examples/TYK_GATEWAY_APPROOV_JWT_EXAMPLE.md.
The following examples below use cURL to perform the API requests.
For more testing scenarios see the full working example for a Tyk API Gateway at Testing the Approov Integration.
Generate a valid token example from the Approov Cloud service:
approov token -genExample your.tyk-api-gateway.domain.comThen make the request with the generated token:
curl https://your.tyk-api-gateway.domain.com \
-i \
--header 'Approov-Token: APPROOV_TOKEN_EXAMPLE_HERE'The request should be accepted. For example:
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: *
Content-Length: 53
Content-Type: application/json
Date: Wed, 31 Aug 2022 16:11:33 GMT
Server: gunicorn/19.9.0
X-Ratelimit-Limit: -1
X-Ratelimit-Remaining: 0
X-Ratelimit-Reset: 0
{
"uuid": "35168518-b391-40ff-82c7-4ed2743837d6"
}
Generate an invalid token example from the Approov Cloud service:
approov token -type invalid -genExample your.tyk-api-gateway.domain.comThen make the request with the generated token:
curl https://your.tyk-api-gateway.domain.com \
-i \
--header 'Api-Key: YOUR_API_KEY_HERE' \
--header 'Approov-Token: APPROOV_INVALID_TOKEN_EXAMPLE_HERE'The above request should fail with an Unauthorized error. For example:
HTTP/1.1 401 Unauthorized
Content-Type: application/json
X-Generator: tyk.io
Date: Wed, 31 Aug 2022 16:10:44 GMT
Content-Length: 56
{
"error": "Key not authorized: token has expired"
}
If you find any issue while following our instructions then just report it here, with the steps to reproduce it, and we will sort it out and/or guide you to the correct path.
If you wish to explore the Approov solution in more depth, then why not try one of the following links as a jumping off point: