Use Descope with KrakenD

KrakenD is an open-source API Gateway that allows you to create a fast, secure, and scalable API gateway. Securing your APIs and underlying microservices is crucial in modern development. Descope enables you to add advanced authentication capabilities to your KrakenD endpoints efficiently. KrakenD integrates with Descope via the JWT validation component.

The validation workflow

Whether you are trying to protect your API from end-users or machine-to-machine access, the workflow is the same:

• End Users use their applications to log in to Descope who provides an access token for the session.
• Machine-to-machine communication also uses a token from Descope after providing a client_id and a client_secret.
• With the token generated by Descope, the client passes it to KrakenD in each request inside an HTTP header or cookie
• KrakenD authorizes or not the usage of the specific endpoint according to the rules you have configured.

As KrakenD can validate the Descope signature by itself, it does not need to call the Descope server to validate the token every time. Instead, KrakenD queries Descope every 15 minutes (configurable) to ensure the key has not rotated.

Protecting endpoints with Descope tokens

We will create a simple KrakenD configuration with a single endpoint /descope-protected, ensuring only users with valid tokens can access it.

Create a krakend.json file and add the following configuration:

{
  "version": 3,
  "timeout": "3s",
  "endpoints":[
  {
    "endpoint": "/descope-protected",
    "extra_config": {
        "auth/validator": {
            "alg": "RS256",
            "jwk_url": "https://api.descope.com/v2/keys/__ProjectID__"
        }
    },
    "backend": [
        {
          "host":["http://localhost:8080"],
          "url_pattern": "/__health"
        }
    ]
  }]
}

That's all you need for the basic configuration! You can expand the structure now to include checking specific roles, claims, etc.

Testing the configuration

From the folder where we create our krakend.json file, start the gateway with:

docker run --rm -v "$PWD:/etc/krakend" -p "8080:8080"

Verify the gateway is running by checking the unprotected /__health endpoint:

curl -iG http://localhost:8080/__health
 
{"status":"ok"}

Now let's try to access the /descope-protected endpoint without a token:

curl -iG http://localhost:8080/descope-protected
 
HTTP/1.1 401 Unauthorized

Since no token is provided, KrakenD correctly denies access. If you check the KrakenD logs, you will also find a line Error #01: Token not found.

Let's get a valid M2M token now. Log in to your Descope Console and create an access key. Using your Descope Project Id and Access Key, you can then run the followin cURL command to exchange the access key for a JWT:

curl -X POST "https://api.descope.com/v1/auth/accesskey/exchange" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer __ProjectID__:<Access Key>"

The response of the call above will provide you with a sessionJwt.

Now you are ready to request protected resources from the gateway. Replace the sample URL with your gateway URL and <your-session-jwt> with the sessionJwt retrieved in the previous step:

curl --request GET \
  --url http://localhost:8080/descope-protected \
  --header 'authorization: Bearer <your-session-jwt>'
{"status":"ok"}

That's it! The {"status": "ok"} is the response you have from the /descope-protected endpoint after being validated as a legitimate user.

Advanced configurations

With that we have completed the basic setup that validates users using Descope access tokens.

Some possibilities are:

• Create Roles in Descope and add them as a condition to accessing an endpoint in KrakenD.
• Customize JWTs with Descope JWT templates for Users or Access Keys
• Propagate user claims to your backend services.

For more details, see KrakenD's JWT Validation documentation.

Conclusion

Integrating Descope with KrakenD enhances security while maintaining flexibility. You can designate protected and public endpoints, ensuring controlled access to your APIs.