Introduction

Descope employs JSON Web Token (JWT) to ensure safe data transfer, authentication, and authorization. In web applications, it's essential to parse and confirm these tokens to guarantee their integrity and authenticity. Validating tokens mitigates potential security threats arising from token manipulation or expiration.

Here's how to use Descope's backend SDKs to validate JWTs:

Install SDK

NodeJSPythonGoJavaRuby 
npm i --save @descope/node-sdk
pip3 install descope
go get github.com/descope/go-sdk
// Include the following in your `pom.xml` (Maven)
<dependency>
    <artifactId>java-sdk</artifactId>
    <groupId>com.descope</groupId>
    <version>sdk-version</version> // Check https://github.com/descope/descope-java/releases for the latest versions
</dependency>
gem install descope

Import and initialize SDK

NodeJSPythonGoJavaRuby 
import DescopeClient from '@descope/node-sdk';
try{
    //  baseUrl="<URL>" // When initializing the Descope clientyou can also configure the baseUrl ex: https://auth.company.com  - this is useful when you utilize CNAME within your Descope project.
    const descopeClient = DescopeClient({ projectId: '__ProjectID__' });
} catch (error) {
    // handle the error
    console.log("failed to initialize: " + error)
}

// Note that you can handle async operation failures and capture specific errors to customize errors.
//     An example can be found here: https://github.com/descope/node-sdk?tab=readme-ov-file#error-handling
from descope import (
    REFRESH_SESSION_TOKEN_NAME,
    SESSION_TOKEN_NAME,
    AuthException,
    DeliveryMethod,
    DescopeClient,
    AssociatedTenant,
    RoleMapping,
    AttributeMapping,
    LoginOptions
)
try:
    # You can configure the baseURL by setting the env variable Ex: export DESCOPE_BASE_URI="https://auth.company.com  - this is useful when you utilize CNAME within your Descope project."
    descope_client = DescopeClient(project_id='__ProjectID__')
except Exception as error:
    # handle the error
    print ("failed to initialize. Error:")
    print (error)
import "github.com/descope/go-sdk/descope"
import "github.com/descope/go-sdk/descope/client"

// Utilizing the context package allows for the transmission of context capabilities like cancellation
//      signals during the function call. In cases where context is absent, the context.Background()
//      function serves as a viable alternative.
//      Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
import (
	"context"
)

// DescopeBaseURL // within the client.Config, you can also configure the baseUrl ex: https://auth.company.com  - this is useful when you utilize CNAME within your Descope project.

descopeClient, err := client.NewWithConfig(&client.Config{ProjectID:"__ProjectID__"})
if err != nil {
    // handle the error
    log.Println("failed to initialize: " + err.Error())
}
import com.descope.client.Config;
import com.descope.client.DescopeClient;

var descopeClient = new DescopeClient(Config.builder().projectId("__ProjectID__").build());
require 'descope'

@project_id = ENV['DESCOPE_PROJECT_ID']
@client = Descope::Client.new({ project_id: @project_id})

Call the Validate JWT Function

After passing in the JWT from the frontend, you can simply call the validate JWT function.

NodeJSPythonGo 
await descopeClient.validateJwt("<jwt>");
jwt_response = descope_client._validate_session("<session-jwt>")
// Args:
//    ctx: context.Context - Application context for the transmission of context capabilities like
//        cancellation signals during the function call. In cases where context is absent, the context.Background()
//        function serves as a viable alternative.
//        Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
ctx := context.Background()

if authorized, sessionToken, err := descopeClient.Auth.validateJWT(ctx, "<session-jwt>"); !authorized {
    // unauthorized error
}

Offline

Validating JSON Web Tokens (JWTs) offline is crucial in situations where the server running the SDK does not have access to the internet. Descope SDKs allow you to handle this scenario with ease. This article explains how to validate JWTs offline by providing a custom public key.

Providing a Custom Public Key

Finding Your Public Key

Your public key can be located at https://api.descope.com/v2/keys/<your_project_id>. Refer to the Descope Documentation and API reference page for additional details on locating and handling public keys.

Initializing the SDK with a Custom Public Key

To provide your own public key, you can do so by including the publicKey option when initializing the SDK. Below is a step-by-step guide:

  1. First, install the SDK for your language of choice.
NodeJSPythonGo 
npm i --save @descope/node-sdk
pip3 install descope
go get github.com/descope/go-sdk

  1. Then, you'll then need to import DescopeClient via SDK.
NodeJSPythonGo 
import DescopeClient from '@descope/node-sdk';
from descope import DescopeClient
import "github.com/descope/go-sdk/descope/client"

// Utilizing the context package allows for the transmission of context capabilities like cancellation
//      signals during the function call. In cases where context is absent, the context.Background()
//      function serves as a viable alternative.
//      Utilizing context within the Descope GO SDK is supported within versions 1.6.0 and higher.
import (
	"context"
)

  1. Next, you can initialize the DescopeClient with your project ID and public key. The public key must be a JSON object containing the appropriate algorithm and other details.
NodeJSPythonGo 
const descopeClient = DescopeClient({
  projectId: "__ProjectID__",
  publicKey: '{"alg":"RS256", ... }',
});
descope_client = DescopeClient(project_id="__ProjectID__", public_key='{"alg":"RS256", ... }')
descopeClient := client.NewWithConfig(&client.Config{ProjectID: "__ProjectID__", PublicKey: `{"alg":"RS256", ... }`,})

  1. Finally, validate the JWT with the provided public key.
NodeJSPythonGo 
await descopeClient.validateJwt("<session-jwt>");
jwt_response = descope_client._validate_session("<session-jwt>")
if authorized, sessionToken, err := descopeClient.Auth.validateJWT(ctx, "<session-jwt>"); !authorized {
    // unauthorized error
}

Conclusion

Validating JWTs offline via SDK by providing a custom public key enhances security and functionality, especially when working in environments without internet access.

If you have any other questions about Descope, feel free to reach out to us!