Skip to main content

JWT-Based Authentication in Native Frame

JSON Web Tokens (JWTs) are the cornerstone of authentication in the Native Frame ecosystem. This guide will walk you through how we leverage JWTs to secure API requests and manage user sessions effectively. We'll cover service account JWTs, user-based JWTs, and important concepts like JWKs and external issuers.

The Role of JWTs in Native Frame​

Native Frame employs JWTs for two primary purposes:

  1. Authenticating API calls to backends using service account JWTs
  2. Providing short-lived tokens for end-user (streamers and viewers) authentication

Understanding and implementing JWT-based authentication allows you to seamlessly integrate Native Frame's streaming capabilities while maintaining full control over user access and permissions.

Understanding JWKs (JSON Web Key Sets)​

Before diving into JWT types, it's crucial to understand JWKs. These are sets of keys containing the public keys used to verify JWTs issued by the authorization server. Native Frame utilizes JWKs to manage and rotate keys used for signing JWTs securely.

JWKs offer several advantages:

  • Enhanced security through key rotation
  • Seamless key updates without service interruption
  • Simplified key management
Managed JWKs

Native Frame provides JWK management for you via the dashboard and API. The rest of this document discusses Native Frame managed JWKs. Go here to understand how to use External Issuers if you wish to manage your own JWKs.

Two Flavors of JWTs​

Native Frame supports two main types of JWTs, each serving a distinct purpose in your authentication strategy.

Service Account JWTs: For Server-side Authentication​

Service Account JWTs are designed for server-to-server communication and automation tasks. Think of them as your application's digital identity.

Key features:

  • Long-lived (can be set to expire after months or years)
  • Typically have broad permissions
  • Ideal for backend services, CI/CD pipelines, or administrative scripts

Creating a Service Account JWT​

For manual projects, you can generate a Service Account JWT through the Native Frame dashboard:

  1. Navigate to your manual project
  2. Access the "API Keys" section
  3. Under "JSON Web Key Sets (JWKS)", click "Generate JWT" in the Service Account JWK

For programmatic generation, use the following API call:

curl -X POST https://platform.nativeframe.com/auth/v1/jwt \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {{token}}' \
-d '{
  "kid": "{{kid}}",
  "roles": [
    "service-account"
  ]
}'

Replace {{token}} with your Keycloak JWT and {{kid}} with the appropriate JWK KID. You can find these values if you have a manually configured project in the "API Keys" section of the project in the dashboard.

💡 Note

Checkout the Auth API for more details on generating JWTs.

User-based JWTs: Tailored for End-Users​

User-based JWTs represent individual end-users of your application. They're perfect for authenticating viewers to watch a live stream or broadcasters to initiate streaming.

Key features:

  • Short-lived (typically expire in minutes or hours)
  • Permissions specific to the user
  • Used primarily in client-side applications

Generating a User JWT​

For manual projects, follow these steps in the Native Frame dashboard:

  1. Navigate to your project
  2. Click on "API Keys"
  3. Under "JSON Web Key Sets (JWKS)", select "Generate JWT" in the User JWK
  4. Click "Create"

For programmatic generation:

curl -X POST https://platform.nativeframe.com/auth/v1/video-jwt \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {{token}}' \
-d '{
  "kid": "{{kid}}",
  "organizationSlug": "{{your organization name}}",
  "projectId": "{{project id}}",
  "videoToken": {
    "scopes": [
      "broadcaster"
    ],
    "userId": "{{user id}}",
    "ttl": {{expiration time in seconds, e.g., 3600}},
    "data": {
      "displayName": {{stream name in kebab case, e.g., "my-stream-name"}},
      "mirrors": [
        {
          "id": {{stream id}},
          "streamName": {{stream name in kebab case}},
          "kind": "pipe",
          "clientEncoder": "SaaS",
          "streamKey": {{stream id}},
          "clientReferrer": "{{client referrer}}"
        }
      ]
    }
  }
}'

Ensure you replace all placeholders with your specific data.

💡 Note

Checkout the Auth API for more details on generating JWTs.

Best Practices for JWT Implementation​

To ensure the security and efficiency of your JWT-based authentication:

  1. Use service account JWTs exclusively for server-side operations; never expose them to clients
  2. Keep user JWTs short-lived and implement a robust refresh mechanism
  3. Regularly rotate your JWKs to enhance security
  4. When using external issuers, ensure your identity provider adheres to OAuth 2.0 and OpenID Connect standards
  5. Always transmit JWTs over HTTPS to prevent interception

Limitations of JWTs: When to Consider Alternatives​

While JWTs are versatile, they may not be ideal for every scenario. Consider alternatives in the following cases:

Dynamic Access Control for Viewing​

JWTs work well for authentication in scenarios with relatively static viewing permissions, such as:

  • Ticketed live events (e.g., concerts, webinars)
  • Subscription-based content

However, JWTs may be less suitable for situations requiring real-time, dynamic access control, like:

  • Pay-per-view events with minute-by-minute billing
  • Content with frequently changing access rights

In these cases, the persistence of a valid JWT until expiration can make it challenging to revoke or adjust viewing permissions quickly.

tip

For use cases requiring real-time access control, consider using Native Frame's webhook authentication feature. This allows for real-time decisions about user access for each viewing session, providing finer-grained control.

By choosing the right authentication method for your specific use case, you can ensure both security and flexibility in managing user access to your streams.