Descope Authorization

Securing your APIs and underlying microservices is crucial in modern development. Descope enables you to add advanced authentication capabilities to your KrakenD endpoints efficiently.

Descope is a passwordless authentication and user management service designed for developers. KrakenD integrates with Descope via the JWT validation component.

Descope integration

JSON web tokens (JWT) are an open standard (RFC 7519) that define a way for securely transmitting information between parties. JWT tokens are compact, secure (digitally signed), and have become an industry-standard used at internet scale. KrakenD supports any system using this open standard, including Descope.

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/<your_project_id>"
        }
    },
    "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" krakend/krakend-ee:2.9

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

$curl -iG http://localhost:8080/__health
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Sun, 23 May 2021 15:32:32 GMT
Content-Length: 15

{"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
Date: Wed, 29 Jan 2025 00:13:29 GMT
Content-Length: 0

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 <Project ID: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

We have completed a basic setup that validates users using access tokens. With this simple configuration, we introduce a highly secure ecosystem that protects your business from undesired access. Now you might want to add additional checks to your system and take advantage of all the powerful features of Descope.

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. Descope’s seamless integration with KrakenD streamlines authentication and improves user experience, making it an excellent choice for secure API management