SDK Authentication
Last updated
Was this helpful?
18.5
Last updated
Was this helpful?
When an Airkit application requires authentication in order to be accessed within an existing web page, the authentication process should be handled server-side. This prevents you from exposing any secure information in the browser while allowing you to use your existing processes to handle authentication.
Out of the box, Airkit provides the infrastructure to quickly configure authentication processes handled by JWTs as well as reference information sent within the payload of incoming JWTs. If at all possible, this is the authentication method we recommend using. However, if you have another authentication method you would prefer to use, it is also possible to configure it manually.
If you've already created a JWT authentication process on your website, Airkit allows you to reuse that process for embedded experiences. You can also create a new JWT authentication process specifically to use in the context of the SDK. Either way, a prerequisite of this process is that JWT authentication should already be configured server-side.
Once JWT authentication is configured server-side, the associated public key will then need to be configured so that Airkit will be able to verify the validity of incoming JWTs. To do so, go to > > Connected Accounts and create a new Connected Account. Select Key Pair as the Integration Type, and then enter the public key into the Public Key field:
Upon clicking Create, the public key will be encrypted and stored so that it can be referenced securely within individual applications.
Now this app can use the configured public key to validate JWTs created using the associated private key. When you attempt to navigate to a Starting Link via an SDK embed, the application will wait for the outer frame to send this authentication in, and the JWT will be required before the Session will be initialized.
Credentials need to be manually passed into the SDK in order for this authentication mechanism to work. Once you have generated a JWT server-side, pass it to the SDK via the bearerToken property.
Note that the only difference between this block of HTML and the block of HTML given in the SDK Quickstart is that bearerToken is explicitly defined to create credentials.
JWTs contain claims in their payloads. These claims are typically statements about the user or other data it might be useful to reference once the JWT has been verified and used to start a Session.
Once this is done, the claims in the JWT will be available for reference throughout the Session.
The App API endpoint can return the session_id and url in the same format the SDK API endpoint did, effectively simulating an SDK API endpoint.
If an App API endpoint returns a payload formatted in the same way as a payload returned by an out-of-the-box SDK API endpoint, it simulates the behavior of an SDK API perfectly.
In such cases, the URL of the App API endpoint (APP_API_URL) can function as the SDK_API_URL in your web page, as in the following example:
The App API endpoint is a proxy for the SDK API endpoint, so the SDK will handle the rest.
The following example shows how an App API endpoint (APP_API_URL) that returns the session_id and url in the header as "x-airkit-session-id" and "x-airkit-session-url" can use them to define the Launch trigger:
To reference it within a particular app, open that app in the and then toggle over to . Under Global > App Authentication Type, select "Secure App". Under Authentication Method, select "External Method", and under Public Key, select the Connected Account configured above:
For instance, say you have saved your JWT as the variable creds. Assuming SDK_API_URL corresponds to the SDK URL as described in the , the following block of HTML will embed your application into the website it is inserted into while requiring a valid JWT before initializing a Session:
Information sent within the JWT can be accessed in the** On Authentication Success Event **(found under Connections > Session) as event.attributes. Should you want to reference this information outside of this Event, use the Action to save the information to another variable, such as the global variable session.claims in the following example:
Airkit provides the infrastructure to quickly configure authentication processes handled by JWTs. If you prefer to handle authentication by another method, you need to make sure that that authentication process is still being handled server-side, and so whatever secret information you're sending to handle authentication, it should be handled by an endpoint. This is meaningfully separate from the . The App API endpoint serves as an intermediary, as it can pass Auth tokens without exposing them to the user's web browser.
If the App API endpoint supports CORS for targeted host names and is given access to an Auth token, it can call on the SDK API endpoint via an after inserting the Auth token into the header. The SDK API endpoint will start a Session return a session_id and a url, corresponding to the Session ID and the respectively. This information can be used in two ways:
The App API endpoint can pass the session_id and url to the web browser which can itself use that information to define the Launch trigger (see for more).
