How does the /api/v1/security/guest_token/ works

[anuragsingh-prospera]

How does the /api/v1/security/guest_token/ end point works in superset? What is the exact detailed flow of generating a guest_token in superset ? The general access_token passed in the header of this request, what happens to that, how does everything exactly works?

[dosubot[bot]]

The /api/v1/security/guest_token/ endpoint in Superset is used to generate a guest token that allows users to access embedded resources without logging into Superset directly. Here is the detailed flow of generating a guest token, including the handling of the general access token passed in the header of this request:

1. Authentication: The agent making the POST request to /api/v1/security/guest_token must be authenticated and have the can_grant_guest_token permission. This is typically done by passing an access token in the request header.

2. Request Payload: The request payload includes parameters that define what the guest token will grant access to. This can include user information, resources (such as dashboards), and Row Level Security (RLS) rules.

3. Creating the Guest Token: The backend sends a POST request to /api/v1/security/guest_token with the payload. The payload might look like this:

   {
     "user": {
       "username": "stan_lee",
       "first_name": "Stan",
       "last_name": "Lee"
     },
     "resources": [{
       "type": "dashboard",
       "id": "abc123"
     }],
     "rls": [
       { "clause": "publisher = 'Nintendo'" }
     ]
   }

4. Token Generation: The create_guest_access_token function is called to generate the guest token. This function uses the JWT secret, algorithm, and expiration settings from the configuration to create the token. The token includes claims for the user, resources, RLS rules, and standard JWT claims like issued at (iat), expiration time (exp), audience (aud), and type (guest).

5. Response: If the request is successful, Superset returns a guest token. This token can then be used by the frontend to authenticate and access the specified resources.

6. Using the Guest Token: The frontend uses the guest token to embed a dashboard. The token is passed to the embedDashboard function of the Superset Embedded SDK, which handles the embedding process.

Here is an example of how the guest token is used in the frontend:

import { embedDashboard } from "@superset-ui/embedded-sdk";

embedDashboard({
  id: "abc123", // given by the Superset embedding UI
  supersetDomain: "https://superset.example.com",
  mountPoint: document.getElementById("my-superset-container"), // any html element that can contain an iframe
  fetchGuestToken: () => fetchGuestTokenFromBackend(),
  dashboardUiConfig: { // dashboard UI config: hideTitle, hideTab, hideChartControls, filters.visible, filters.expanded (optional), urlParams (optional)
      hideTitle: true,
      filters: {
          expanded: true,
      },
      urlParams: {
          foo: 'value1',
          bar: 'value2',
          // ...
      }
  },
});

7. Guest User Handling: When a request is made with a guest token, the get_guest_user_from_request function parses the token and returns the guest user. This function checks for the presence of the guest token in the request headers or form data, validates the token, and extracts the user, resources, and RLS rules claims.

In summary, the /api/v1/security/guest_token/ endpoint works by authenticating the request with an access token, processing the payload to define access parameters, generating a guest token, and then using that token to embed resources in the frontend. The guest token is validated and parsed to create a guest user for subsequent requests ^[1][2].

To continue talking to Dosu, mention @dosu.

[anuragsingh-prospera]

@dosu Authentication: The agent making the POST request to /api/v1/security/guest_token must be authenticated and have the can_grant_guest_token permission. This is typically done by passing an access token in the request header.

In the above explanation when the general access token is passed in the request header what happens with the general access token ? How is it processed or what happens to it? How does superset makes sure that the user is authenticated etc? Explain in detail in context of the /api/v1/security/guest_token/ endpoint being hit?

[dosubot[bot]]

When the general access token is passed in the request header to the /api/v1/security/guest_token/ endpoint, Superset processes it to ensure that the user is authenticated and has the necessary permissions. Here is a detailed explanation of how this works:

1. Authentication and Authorization:

   • The endpoint is decorated with @protect() and @permission_name("grant_guest_token").
   • The @protect() decorator ensures that the user is authenticated. It checks the access token in the request header to verify the user's identity.
   • The @permission_name("grant_guest_token") decorator ensures that the authenticated user has the can_grant_guest_token permission.

2. Processing the Access Token:

   • When the request is made, the access token in the header is extracted and validated.
   • The protect() decorator uses the access token to authenticate the user. This involves decoding the token, verifying its signature, and checking its claims (such as expiration time and audience).
   • If the token is valid, the user is considered authenticated.

3. Permission Check:

   • After authentication, the @permission_name("grant_guest_token") decorator checks if the authenticated user has the can_grant_guest_token permission.
   • This permission check ensures that only users with the appropriate role can generate guest tokens.

4. Endpoint Execution:

   • If both the authentication and permission checks pass, the endpoint proceeds to process the request payload.
   • The payload is validated using the GuestTokenCreateSchema, and the guest token is generated using the create_guest_access_token method.

Here is the relevant code snippet from the SecurityRestApi class:

@expose("/guest_token/", methods=("POST",))
@event_logger.log_this
@protect()
@safe
@statsd_metrics
@permission_name("grant_guest_token")
def guest_token(self) -> Response:
    """Get a guest token that can be used for auth in embedded Superset.
    ---
    post:
      summary: Get a guest token
      requestBody:
        description: Parameters for the guest token
        required: true
        content:
          application/json:
            schema: GuestTokenCreateSchema
      responses:
        200:
          description: Result contains the guest token
          content:
            application/json:
              schema:
                type: object
                properties:
                    token:
                      type: string
        401:
          $ref: '#/components/responses/401'
        400:
          $ref: '#/components/responses/400'
        500:
          $ref: '#/components/responses/500'
    """
    try:
        body = guest_token_create_schema.load(request.json)
        self.appbuilder.sm.validate_guest_token_resources(body["resources"])

        token = self.appbuilder.sm.create_guest_access_token(
            body["user"], body["resources"], body["rls"]
        )
        return self.response(200, token=token)
    except EmbeddedDashboardNotFoundError as error:
        return self.response_400(message=error.message)
    except ValidationError as error:
        return self.response_400(message=error.messages)

In summary, the general access token in the request header is used to authenticate the user via the @protect() decorator. Once authenticated, the @permission_name("grant_guest_token") decorator ensures the user has the necessary permission to generate a guest token. If both checks pass, the endpoint processes the request and generates the guest token ^[1].

To continue talking to Dosu, mention @dosu.

[anuragsingh-prospera]

@dosu where is the code of @protect decorator in the superset source code ?

[dosubot[bot]]

The code for the @protect decorator is imported from flask_appbuilder.security.decorators:

from flask_appbuilder.security.decorators import protect

To find the actual implementation of the @protect decorator, you would need to look into the flask_appbuilder library, specifically in the security/decorators.py file ^[1].

To continue talking to Dosu, mention @dosu.

[harikishoremv]

@dosu does this work only with Dashboards? what to do if this needs to work with Charts?