diff --git a/site/sigmaguides/src/embedding_16_JWT/assets/jwt6.png b/site/sigmaguides/src/embedding_16_JWT/assets/jwt6.png new file mode 100644 index 00000000..692861a3 Binary files /dev/null and b/site/sigmaguides/src/embedding_16_JWT/assets/jwt6.png differ diff --git a/site/sigmaguides/src/embedding_16_JWT/embedding_16_JWT.md b/site/sigmaguides/src/embedding_16_JWT/embedding_16_JWT.md index 9e1b9c52..fd73696d 100644 --- a/site/sigmaguides/src/embedding_16_JWT/embedding_16_JWT.md +++ b/site/sigmaguides/src/embedding_16_JWT/embedding_16_JWT.md @@ -6,7 +6,7 @@ environments: web status: published feedback link: https://github.com/sigmacomputing/sigmaquickstarts/issues tags: default -lastUpdated: 2024-09-27 +lastUpdated: 2024-10-24 # Embedding 16: Secure Embedding with JWT @@ -15,9 +15,10 @@ Duration: 5 Many customers want a simple, but secure way to embed content that can be accessed by both external (users who do not have a registered account in Sigma) and internal user (users who access Sigma only through an embed, inside a parent application). -To enable this, Sigma supports authenticating secure embeds using JSON Web Tokens (JWTs). Signing your secure embed URLs with JWTs has several advantages, but a few limitations too: +To enable this, Sigma supports authenticating secure embeds using JSON Web Tokens (JWT). ### Benefits of JWT +Signing your secure embed URLs with JWTs has several advantages: - JWTs are compact, URL-safe tokens that can be digitally signed, ensuring that the data they contain is tamper-proof. @@ -27,28 +28,100 @@ To enable this, Sigma supports authenticating secure embeds using +REPLAY ATTACK PREVENTION:
Existing embed customers are likely familiar with Sigma’s "signed URL" embed-API, which uses a nonce to ensure that the constructed URL is for one-time use only. Similarly, JWTs are also for one-time use. -- Only admins will be able to impersonate other users (including embed users). Non-admins can only login as themselves. + -- You cannot test an JWTs in the embed sandbox. - + +### Target Audience +Developers evaluating Sigma embedding and the security options. + +### Prerequisites + + + + -### What is JWT? -JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted. + + +![Footer](assets/sigma_footer.png) + +## How JWT Works +Duration: 5 + +JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. It is a product of the Internet Engineering Task Force (IETF) [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519). + +The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted. The remaining discussion in this section is intended for those less familiar with JWT, how it is structured, the transaction flow and benefits. Feel free to jump to the next section if you just want a demonstration of JWT in Sigma. +In the typical workflow, a client requests embedded content using a JSON Web Token (JWT), and the server processes, validates, and serves the embedded content based on user credentials and environment variables. + +#### Step-by-Step JWT Flow: + +**1. Client Request (ie: end user's web browser):**
+The client (e.g., a web application or another service) sends a request to the server to obtain a URL for accessing embedded Sigma content. This request may include user-related information, such as identity or a general request for access to Sigma content. + +**2. Server-Side JWT Generation (ie: customer created embed-API):** +***Credential Handling:***
+The server securely manages the necessary credentials to generate the JWT, such as the secret key (EMBED_SECRET) and client ID (EMBED_CLIENT_ID). These credentials ensure that the JWT is properly signed and trusted by Sigma. + +***User Claims:***
+The server retrieves or determines relevant claims about the user, such as their email (sub), roles, or team memberships. These claims are vital for defining what the user can do in the embedded Sigma content and ensure that permissions are enforced correctly. + +***JWT Creation:***
+The server combines these user claims with the necessary credentials to create a JWT. The JWT is signed using the server’s secret key, ensuring its integrity and authenticity. The JWT contains claims that specify key information, including: + +- Who the user is (email, user roles) +- What permissions they have +- How long the JWT is valid (expiry or exp claim) + +This process ensures that each JWT is unique, secure, and reflects the user's specific access rights. + +**3. Response with Signed URL:**
+The server responds to the client with a signed URL, which contains the JWT as a query parameter. For example, the URL might look like: +```code +https://app.sigmacomputing.com/?jwt= +``` + +This URL includes the signed JWT that will be used to authenticate and authorize the user when they access the embedded Sigma content. + +**4. Client Accesses the Signed URL:**
+When the client (e.g., the end-user's browser or a web app) loads the signed URL, Sigma verifies the JWT. Sigma ensures that: + +- The JWT signature is valid, confirming that the token hasn’t been tampered with. +- The claims (like sub, roles, exp) are still valid, checking whether the user is authorized and whether the token is within its allowed time frame. +- Replay protection is enforced by validating the jti (JWT ID) claim, ensuring that the token is not reused maliciously. + +**5. Sigma Provides Embedded Content:**
+If the JWT passes all verification checks (valid claims, signature, jti uniqueness, etc.), Sigma serves the requested embedded content. The content provided matches the user’s permissions and scope, ensuring that users can only access what they are authorized to view. + +This workflow ensures secure, one-time use access to Sigma’s embedded content, protecting both user data and application integrity. + ### Structure of JWT: -A JWT is composed of three parts: `Header`, `Payload`, and `Signature`, which are concatenated with dots (.) to form a single string: +An actual JWT is composed of three parts: `Header`, `Payload`, and `Signature`, which are concatenated with dots (.) to form a single string: -**Header:** Typically consists of two parts: the type of token (JWT) and the signing algorithm (e.g., HMAC SHA256). +**Header:** Typically consists of two parts: the type of token (JWT) and the signing algorithm (e.g., [HMAC SHA256](https://en.wikipedia.org/wiki/HMAC)). **Payload:** Contains the claims. Claims are statements about an entity (typically, the user) and additional data. There are three types of claims: registered, public, and private claims. @@ -78,67 +151,22 @@ Examples:
- custom user attributes - eval_connection_id - - For more information on JWT claims in Sigma, [see here.](https://help.sigmacomputing.com/docs/create-an-embed-api-with-json-web-tokens) -### How JWT Works in Sigma - -Let’s walk through a typical workflow where a client requests an embedded content using a JSON Web Token (JWT) and how the server handles this request, validates it, and serves the embedded content based on the credentials and environment variables. -Upon receiving a request from the client for a URL to access embedded Sigma content, the server securely generates a JWT by combining the configured embed client credentials with known user claims (such as email, account type, and team). This signed and encrypted JWT is then embedded into the URL returned to the client, enabling secure and authorized access to the content. - -Expanding on this description a bit more: - -#### 1: Client Request: -The client (e.g., a web application or another service) sends a request to the server to obtain a URL for accessing embedded Sigma content. -This request might include minimal information, such as the user’s identity or a general request for access. - -#### 2: Server-Side JWT Generation: -**Credential Handling:** The server securely manages the necessary credentials, such as the secret key (EMBED_SECRET) and client ID (EMBED_CLIENT_ID), that are required to generate the JWT. - -**User Claims:** The server retrieves or determines relevant claims about the user, such as their email address (sub), roles, or teams. These claims are crucial for defining the user’s permissions and the scope of access within the embedded content. - -**JWT Creation:** The server uses the credentials and claims to create a JWT. This JWT is signed with the secret key, ensuring its authenticity. The JWT includes claims that specify who the user is, what they are allowed to do, and how long their access is valid. - -#### 3: Response with Signed URL: -The server constructs a signed URL that includes the JWT as a query parameter. This URL is then sent back to the client. - -**Authorization:** When the client uses this URL to access the embedded content, the JWT is used by the Sigma server to verify the user’s identity and permissions, granting or denying access accordingly. - - -### Target Audience -Developers evaluating Sigma embedding and the security options. - -### Prerequisites - -
    -
  • A computer with a current browser. It does not matter which browser you want to use.
    • -
  • Access to your Sigma environment.
    • -
  • Some familiarity with Sigma is assumed. Not all steps will be shown as the basics are assumed to be understood.
    • -
  • A development environment of choice. We will demonstrate with Microsoft VSCode and related extensions
    • -
- - - - - ![Footer](assets/sigma_footer.png) -## Clone the Git Repository Project Folder +## Making it Work In Sigma Duration: 5 +### Clone the Git Repository Project Folder +We have made sample project code available in a public GitHub repository to save time. + While you may clone the entire repository (it is not that large), we want to avoid cloning sections of the repository that are not of immediate interest. Instead, we will use VSCode and terminal to perform a git `sparse-checkout` of the specific project folder we are interested in. A few extra steps, but cleaner local project folder. @@ -201,6 +229,31 @@ We can now see the project called `embedding_JWT` with the files stored in the ` +### Additional node.js packages +We need to install two additional node packages that provide us some additional "convenience functionality". + +**1: nodemon:**
+This package is a development tool that automatically restarts our Node.js application whenever it detects changes in specific code files. This helps streamline development by eliminating the need to manually restart the server after each change we make. + +**2: jsonwebtoken**
+We use this package to decode a JWT in the VSCode console. This allows us to read the payload and header data from the token without verifying its authenticity. This is helpful when you need to access the information embedded within the token for non-secure contexts or for inspection/debugging purposes. + +To install these two packages, open a new terminal window in VSCode in the project folder. + +Run the command: +```code +npm install jsonwebtoken +``` + +and +```code +npm install nodemon +``` + +The expected output is: + + + The project has almost everything we need, but we will need some embedded content and credentials from Sigma before we can test this out. ![Footer](assets/sigma_footer.png) @@ -233,7 +286,7 @@ Remember to keep your credentials in a secure location, as losing them requires If you lose your credentials, you must regenerate new credentials. -If this happens, your existing embeds will be rendered invalid until the API is updated with the new embed credentials. +If this happens, your existing embeds will be rendered invalid until the embed API is updated with the new credentials. ### Client Credentials Creation @@ -275,14 +328,14 @@ Paste the credentials into a text file for now, we will use them later. ![Footer](assets/sigma_footer.png) -## Select Something to Embed +## Something to Embed Duration: 5 This embedding method allows you to use any Sigma URL to embed, assuming the proper permissions are passed along with it as parameters. Sigma is very flexible and has different workflows for creating content, based on source data. -For example, we could first create a [data model](https://help.sigmacomputing.com/docs/intro-to-data-models), set permission on it, and then save it off for later use in a workbook(s). We would then create a workbook with a table, that shows data from the data model we saved earlier. +For example, we could first create a [data model](https://help.sigmacomputing.com/docs/intro-to-data-models), set permission on it, and then save it off for later use in a workbook. We would then create a workbook with a table, that shows data from the data model we saved earlier.