Optimierter Zugriff auf eingebettete Instruqt Labs

Comment enseigner un sujet très technique aux prospects et clients ? Comment rendre la conduite fluide ?

Chez Isovalent, nous sommes passionnés par l'idée de rendre l'expérience d'apprentissage aussi fluide que possible pour nos utilisateurs. Isovalent sont les créateurs de Cilium, la plateforme de réseau cloud de facto pour Kubernetes. Même si nous aimons les réseaux et la sécurité, nous comprenons que les gens puissent trouver cela un sujet difficile. Nous avons pensé rendre l'apprentissage du réseautage Kubernetes amusant, c'est pourquoi nous nous efforçons de gamifier l'expérience d'apprentissage.
Instruqt fournit une excellente plate-forme pour créer des laboratoires pratiques qui peuvent être à la fois techniquement avancés et attrayants pour les utilisateurs.

Nous pensons également que l'expérience utilisateur doit être fluide et les processus entièrement automatisés.
Heureusement, beaucoup de choses peuvent être faites en tirant parti de l'API Instruqt graphQL.
Dans ce but, nous avons écrit notre propre bibliothèque instruqt-go, que nous avons décidé de rendre open source. La bibliothèque est conçue pour aider les développeurs à automatiser et à intégrer facilement la plateforme Instruqt.

L'un des problèmes liés à la publication des laboratoires Instruqt est de lier les informations utilisateur d'Instruqt avec celles de votre propre base de données ou CRM.
Dans ce premier article, nous vous guiderons dans la création d'un proxy à l'aide d'instruqt-go qui :

• collecte les identifiants des utilisateurs (par exemple, les jetons HubSpot) ;
• valide l'identité de l'utilisateur ;
• redirige les utilisateurs vers un laboratoire avec des jetons d'accès uniques générés via l'API Instruqt.

Nous publierons ensuite la fonction sur Google Cloud Functions.

Pourquoi un proxy

Il existe plusieurs raisons de collecter des informations sur les utilisateurs dans les laboratoires :

• Il est utile de pouvoir générer des badges (et nous adorons les badges) à la fin du laboratoire (plus d'informations à ce sujet dans un prochain article).
• Il permet de montrer aux utilisateurs leur progression dans les labs afin qu'ils sachent lesquels suivre (voir par exemple la carte Cilium Labs).

Comment transmettre les données utilisateur

Il existe plusieurs méthodes pour transmettre les données utilisateur aux pistes Instruqt.

Paramètres personnalisés

Les paramètres personnalisés Instruqt sont très utiles pour transmettre tout type d'informations lors du démarrage d'une piste. Ces champs sont simplement ajoutés à l'URL en tant que paramètres de requête, préfixés par icp_. Ces paramètres peuvent également être récupérés dans les webhooks Instruqt ainsi que via l'API Instruqt GraphQL, ce qui les rend pratiques à utiliser.

Jusqu'à récemment, Instruqt encourageait les développeurs de pistes à transmettre les informations utilisateur (telles que le nom, l'adresse e-mail ou le jeton) à l'aide de paramètres personnalisés.

Cependant, l'utilisation de paramètres personnalisés présente quelques inconvénients :

1. Ils ne sont pas standardisés et Instruqt ne les interprète pas. Cela signifie que les sessions utilisateur s'afficheront comme anonymes dans les rapports Instruqt (et le nombre d'utilisateurs uniques peut être erroné).
2. Ils ne sont pas chiffrés par défaut. Vous pouvez bien sûr les chiffrer pour vos propres clés, mais Instruqt vous montrera la valeur chiffrée dans les rapports de lecture.
3. J'ai constaté à plusieurs reprises la perte de paramètres personnalisés lorsque les utilisateurs redémarraient un laboratoire. En fait, j'ai démarré ma propre base de données de cache pour contrer ce problème.

Invitations

Les invitations Instruqt permettent de créer une liste de pistes et de générer un lien d'invitation qui peut être partagé avec les utilisateurs pour un accès facile. Des invitations peuvent être définies pour collecter des données utilisateur via un formulaire.

Ces données utilisateur sont ensuite ajoutées aux détails de l'utilisateur sur Instruqt (les détails de l'utilisateur sont joints aux comptes d'utilisateurs, mais sont uniques par équipe Instruqt).

C'est extrêmement pratique pour les ateliers, mais il y a encore quelques limitations :

1. Utiliser une invitation pour accéder à tous les ateliers signifie que cette invitation doit contenir tous les ateliers publiés.
2. Les invitations ont leur propre page de destination, donc cela ne fonctionnerait pas avec notre carte Cilium Labs ou d'autres approches de kiosque.

Remarque : Instruqt a récemment introduit les pages de destination, qui sont une forme d'invitation avec un moyen de régler la page de destination, avec les mêmes avantages et limitations.

Formulaires de tiers

Récemment, Instruqt a ajouté une autre façon de transmettre les informations utilisateur, qui combine les avantages des deux méthodes précédentes.

La méthode PII cryptée permet de transmettre un paramètre de requête pii_tpg à une URL intégrée. Cela signifie :

1. Les données sont cryptées à l'aide d'une clé publique fournie par Instruqt, de sorte que les URL ne contiennent pas d'informations utilisateur lisibles.
2. Instruqt comprend les données pii_tpg et dispose de la clé privée pour les déchiffrer. Les informations sont utilisées pour renseigner les coordonnées de l'utilisateur, comme s'il avait accepté une invitation.
3. Ceci n'est pas lié aux invitations, il peut donc être utilisé avec n'importe quelle piste.

Nous allons utiliser cette nouvelle méthode dans cet exemple, car elle est aujourd'hui la plus polyvalente pour transmettre des informations à Instruqt de manière sûre et fiable.

A Note on Embed Tokens

When you visit a track page on Instruqt, there is an option to embed the track.
This gives you a URL which contains a token unique to the track.

While it is perfectly valid to use that URL, it also means that whoever has access to this token can start the track whenever they want.

Instruqt has recently added an API call to generate one-time tokens for tracks, such that URLs using such tokens can only be used once.

The proxy we're coding will use one-time tokens, since we have access to the API and can easily generate them.

Creating the Proxy

Initial Steps

First, create a directory for your function:

mkdir instruqt-proxy

Move to this directory and initialize the Go environment:

# Replace example.com with the prefix of your choice
go mod init example.com/labs

Google Cloud Function Harnessing

For local testing, create a cmd directory:

mkdir cmd

Create a main.go file in that directory, with the following content:

package main

import (
    "log"
    "os"

    // Blank-import the function package so the init() runs
  // Adapt if you replaced example.com earlier
    _ "example.com/labs"

    "github.com/GoogleCloudPlatform/functions-framework-go/funcframework"
)

func main() {
    // Use PORT environment variable, or default to 8080.
    port := "8080"
    if envPort := os.Getenv("PORT"); envPort != "" {
        port = envPort
    }
    if err := funcframework.Start(port); err != nil {
        log.Fatalf("funcframework.Start: %v\n", err)
    }
}

Creating the Function

Back to the instruqt-proxy directory, create a proxy.go file and start by adding the init() function to it, along with the Go packages we will be using:

package labs

import (
    "fmt"
    "net/http"
    "net/url"
    "os"

    "github.com/GoogleCloudPlatform/functions-framework-go/functions"

    "github.com/isovalent/instruqt-go/instruqt"
)

func init() {
    functions.HTTP("InstruqtProxy", instruqtProxy)
}

This will allow Google Cloud Functions to call the instruqtProxy function when it is initialized.

Let's write that function:

const (
    // Replace team name with yours
    instruqtTeam = "isovalent"
)

func instruqtProxy(w http.ResponseWriter, r *http.Request) {
    instruqtToken := os.Getenv("INSTRUQT_TOKEN")

    if instruqtToken == "" {
        w.WriteHeader(http.StatusInternalServerError)
        return
    }

    instruqtClient := instruqt.NewClient(instruqtToken, instruqtTeam)

    // Get user from passed token
    utk := r.URL.Query().Get("utk")
    if utk == "" {
        w.WriteHeader(http.StatusUnauthorized)
        return
    }

    user, err := getUser(utk)
    if err != nil {
        w.WriteHeader(http.StatusUnauthorized)
        return
    }

    labSlug := r.URL.Query().Get("slug")

    url, err := getLabURL(instruqtClient, user, labSlug)
    if err != nil {
        w.WriteHeader(http.StatusNotFound)
        return
    }

    http.Redirect(w, r, url, http.StatusFound)
}

In this function, we:

1. get the Instruqt token from the INSTRUQT_TOKEN environment variable
2. initialize the Instruqt API client for the token and team
3. retrieve a utk parameter from the URL parameters in order to authenticate the user
4. get user information based on that UTK
5. get the lab slug from the URL parameters
6. retrieve the lab URL for the redirection
7. redirect the user using an http.Redirect function

Implement getLabURL()

The getLabURL function will generate the redirect URL for the lab based on user information, the requested lab slug, and dynamic information from the Instruqt API.

Let's write it:

const (
    // Replace with your sign-up page format
    labSignupPage = "https://isovalent.com/labs/%s"

    // Adapt to your values
    finishBtnText = "Try your next Lab!"
    finishBtnURL  = "https://labs-map.isovalent.com/map?lab=%s&showInfo=true"
)

func getLabURL(instruqtClient *instruqt.Client, u user, slug string) (string, error) {
    track, err := instruqtClient.GetTrackBySlug(slug)
    if err != nil {
        return "", err
    }

    // Unknown user
    if u.Email == "" {
        url := fmt.Sprintf(labSignupPage, slug)
        return url, nil
    }

    // Get one-time token
    token, err := instruqtClient.GenerateOneTimePlayToken(track.Id)
    if err != nil {
        return "", err
    }

    labURL, err := url.Parse(fmt.Sprintf("https://play.instruqt.com/embed/%s/tracks/%s", instruqtTeam, track.Slug))
    if err != nil {
        return "", err
    }

    // Prepare the fields to encrypt
    encryptedPII, err := instruqtClient.EncryptUserPII(u.FirstName, u.LastName, u.Email)
    if err != nil {
        return "", err
    }

    // Add params
    params := map[string]string{
        "token":             token,
        "pii_tpg":           encryptedPII,
        "show_challenges":   "true",
        "finish_btn_target": "_blank",
        "finish_btn_text":   finishBtnText,
        "finish_btn_url":    fmt.Sprintf(finishBtnURL, track.Slug),
    }

    q := labURL.Query()
    for key, value := range params {
        q.Set(key, value)
    }

    // Encode the parameters
    labURL.RawQuery = q.Encode()

    return labURL.String(), nil
}

First, note that we have defined some new constants that you can tune:

• labSignupPage is the URL on your website where unauthenticated users will be redirected. It contains a variable for the lab slug.
• finishBtnText is the text shown on the finish button of the lab.
• finishBtnURL is the action of the button at the end of the lab. It also contains a variable for the lab slug.

Now let's explain the getLabURL() function steps:

1. Retrieve track information from the Instruqt API, error if it cannot be found.
2. If the user is unknown, redirect to sign-up page.
3. Generate a one-time token for the embedded track access.
4. Generate the redirect URL.
5. Encrypt user information using the PII key from the Instruqt API.
6. Add all parameters (one-time token, encrypted user information, finish button options) to the redirect URL.
7. Encode the URL.
8. Return the resulting URL.

The getUser() Function

The last piece missing in this proxy is the getUser() function. I can't help you much here, since this part is where you plug your own logic. You might be using a CRM like Hubspot to retrieve contact information from the UTK, or another database, it's up to you!

The code I'll show you here simply returns a sample user:

/*
 * This is where you add the logic to get user information from your CRM/database.
 */
type user struct {
    FirstName string
    LastName  string
    Email     string
}

func getUser(utk string) (u user, err error) {
    // Implement the logic to get your user information from UTK

    u = user{
        FirstName: "John",
        LastName:  "Doe",
        Email:     "john@doe.com",
    }

    return u, err
}

Testing the code

Now that we have our whole proxy.go function, let's test it!

First, update your go.mod and go.sum files with:

go get ./...
go mod tidy

In your Instruqt dashboard, go to "API keys" and get the value of your API key. Export it as a variable in your shell:

export INSTRUQT_TOKEN=<your_instruqt_token>
</your_instruqt_token>

Next, launch the function on your local machine:

FUNCTION_TARGET=InstruqtProxy go run ./cmd/main.go

Finally, in another terminal, make test requests to localhost:8080 where your function will be running (you can pass a PORT environment variable above to change the port if necessary):

curl  -i "localhost:8080/?slug=cilium-getting-started&utk=someUtkValue"

Adapt to use a track slug that exists in your Instruqt organization. If the track exists, you should get a 302 response with the redirect URL containing a one-time token for access, as well as John Doe's information encrypted with the PII key, and a one-time token (starting with ott_)!

Alternative testing: using Docker

If you'd like to use Docker to test your function locally, you can create a Dockerfile in your current directory:

FROM golang:1.23

WORKDIR /app

COPY . .

RUN go build -o myapp ./cmd/main.go

ENV DEV=true
ENV PORT=8080

EXPOSE $PORT

CMD ["./myapp"]

Add a docker-compose.yaml file:

version: '3'
services:
  proxy:
    build: ./
    ports:
      - "8080:8080"
    environment:
      INSTRUQT_TOKEN: ${INSTRUQT_TOKEN}
      FUNCTION_TARGET: InstruqtProxy

Finally, build and launch your container:

docker-compose up --build

And you can send requests to localhost:8080 just the same as before!

Hosting the Proxy on Google Cloud Functions

In order to deploy to Google Cloud, first make sure you are logged in to your Google Cloud project:

gcloud auth application-default login

Create a Secret for the API Token

Next, let's create a new secret for the Instruqt token:

echo -n "$INSTRUQT_TOKEN" | gcloud secrets create instruqt-token --data-file=-

In order to adjust the permissions on this secret, you will need to get your project ID:

PROJECT_NUMBER=$(gcloud projects describe $(gcloud config get-value project) --format="value(projectNumber)")

Then, add the "Secret Manager Secret Accessor" role for the default Compute Engine service account for the project:

gcloud secrets add-iam-policy-binding instruqt-token \
    --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
    --role="roles/secretmanager.secretAccessor"

Your secret is now ready to be used by the function!

Deploy the Function

You can then deploy the function (adapt the region if needed):

gcloud functions deploy "instruqt-proxy" \
  --gen2 --runtime=go122 --region=europe-west1 --source=. \
  --entry-point="InstruqtProxy" --trigger-http --allow-unauthenticated \
  --set-secrets="INSTRUQT_TOKEN=instruqt-token:latest"

This will upload and build your project, and return the URL to access the function.

This URL will look something like https://europe-west1-.cloudfunctions.net/instruqt-proxy.
You can then test the function using that URL instead of localhost:8080!

Further Considerations

This is a simplified approach to the lab proxy we use at Isovalent. There are things you might want to consider with this implementation:

• If you have actual user (instead of marketing contact), switch to a proper authentication system (e.g. JWT) instead of UTK.
• The current implementation will give access to any lab in your collection if you know its slug. You might want to filter them out (using for example track tags).
• This implementation manages errors but is very basic in logging. We would recommend using Google Cloud logging to easily audit function runs.
• You might want to pass extra information as custom parameters. For example, we like to pass some form of even or campaign ID. These can then be retrieved via the API as part or the Track structure.
• If you're using a custom form and redirecting to the proxy, you might want to be sure your CRM/database has already gotten the user information. You can for example implement a retry logic in the proxy function.
• Invite embed URLs contain the invite ID. If you want to support invites, the proxy could take an optional invite parameter and add it to the URL.

Using the Proxy

This proxy can typically be used to give access to authenticated users in a safe way, while preserving user information in Instruqt reports and making sure embed URLs are not reusable.

Here is an example of usage of this proxy:

1. Set up lab sign-up pages with the form system of your choice (e.g. using Hubspot forms).
2. Retrieve a user identifier from the page context (e.g. a Hubspot cookie token).
3. Redirect users to the proxy, passing the user identifier and lab slug as parameters.

This can allow you to build a series of public sign-up pages for your labs, similar to what we have built on the Isovalent website. It can also be used to build a Kiosk interface, or even a more creative landing page such as the Cilium Labs map, where clicks on the map redirect to the lab proxy.

By making a complex networking technology like Cilium fun with our labs, we have made it the experience for users less intimidating and more approachable. Using our proxy can help you provide a similar user experience to your prospects. Please get in touch if you have any questions.

Das obige ist der detaillierte Inhalt vonOptimierter Zugriff auf eingebettete Instruqt Labs. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!