TestBox Partner Documentation

iFraming

Auto-login

Explore

Auto-login

Single Sign-on (SSO)

By far, the preferred method to sign in users is using an industry-standard Single Sign-on (SSO) mechanism.

We currently offer 3 different SSO options.

1 - JSON Web Tokens (JWT)
⁠
⁠

We currently support a JWT-based Single Sign-on flow. This approach is great for a few reasons:

If you don't already have an SSO setup, this flow is very easy to setup.

It is extremely simple, and only requires sharing one key. (We can also sign the jwt with our key which can be verified using JWKs)

The data payload is very flexible to accommodate your needs.

If you already have this set up, or you are willing to set it up as part of your integration process, you are all set to go, reach out to us so we can define the details.

Below is a flow chart to describe how the JWT login approach works within the TestBox ecosystem.

⁠

⁠

2 - OpenID Connect
⁠
⁠

We offer OpenID Connect as a single sign-on option for accounts. This is particularly useful if you use a service like Auth0 or Firebase for your authentication.

Below is a flow chart to describe how the OpenID login approach works within the TestBox ecosystem.

⁠

⁠

Getting started

⁠

First, please connect with us to gather the information you need. You will need:

A client secret

A client ID

In exchange, we will need:

Any redirect URLs you would like us to verify against.

Connection information

⁠

We utilize the OpenID Connect discovery protocol to expose most of the information you will need to set up your OpenID connection. Our configuration file can be found here:

Below are instructions to set up the configurations within your authentication service. We currently have documented steps for Auth0 and Firebase. If you have a different provider, please reach out to us for instructions.

Auth0

We have some specific instructions for Auth0 users.

First, expand the "Authentication" section, then click "Enterprise."

⁠

Click on "OpenID Connect."

⁠

Click "Create Connection."

⁠

Fill out the form. We recommend simply calling your connection name "TestBox."

For the Issuer URL, enter our OpenID issuer configuration URL: https://idp.testbox.com/.well-known/openid-configuration

Enter the client ID and secret provided to you by TestBox.

Take note of the callback URL provided so that you can give this information back to TestBox.

⁠

Click "Create."

You will then be presented with options to configure the login experience. We recommend you do not show the button. You may optionally configure "home realm discovery" to look for tbxofficial.com emails.

⁠

Click "Save," then click on the "Applications" tab next to the "Login Experience" tab.

Activate any Applications necessary to make your TestBox integration work.

⁠

⁠

⁠

Take note of the connection identifier at the top of the screen. We will need this connection ID.

Send the redirect URLs and connection IDs back to TestBox.

You're done! 🎉

Firebase

First, make sure your Firebase project is upgraded to use Google Identity Platform.

Under the Authentication tab for your project, click Sign-in Method.

Click Add New Provider

Choose OpenID Connect under "custom providers."

⁠

⁠

If you are not able to fill out the form, make sure the Enable switch is toggled on.

⁠

Fill out the form with the following details:

Grant type: Code flow Name: TestBox or testbox Provider ID: Recommended to use testbox Client ID: provided to you by us Issuer (URL): https://idp.testbox.com Client secret: provided to you by us

⁠

Click Next.

You will now see your Callback URL. Please send this callback URL to us at TestBox so we can authorize it in our identity provider.

3 - SAML
⁠
⁠

TestBox offers SAML as a single sign-on option. This approach is suitable if your application already supports SAML.

When using SAML, TestBox will act as the identity provider (IDP) and your application will be the service provider (SP). The supported login flow is an IDP-Initiated login where TestBox will create a SAML Assertion with the details of the user who is being logged in and the SP can validate the assertion against the TestBox X.509 public certificate.

TestBox publishes a SAML metadata document that contains the public certificate, expected SAML entity ID and associated service URLs at this URL:

https://idp.testbox.com/saml/metadata.xml⁠

⁠

In order to allow SAML SSO from TestBox, we will need a publicly accessible URL which contains the SAML metadata document for your application. The URL can be static or a different URL per trial. For example we support the following metadata URL format: https://your_product.okta.com/app/{{trial_id}}/sso/saml/metadata

If you allow for a self service option within your web application to allow for SAML please make sure that the trial accounts that we are provided have this option turned on. If you have to manually set up the connection for SAML please reach out to your TestBox contact to review your options and see if we are able to integrate SAML with your implementation.

The diagram below shows the SAML login flow that will be performed:

⁠

⁠

Client-side Auto-login

NOT RECOMMENDED

This mechanism is not as reliable as Single Sign-on, and it produces an unusual user experience. We strongly recommend using Single Sign-on if possible.

Prerequisites
⁠
⁠

You must have a login page with a username/email address field and password.

You must be willing to write and run JavaScript on this page.

You must be willing to allow the login page to be

iFramed⁠

Theory of operation
⁠
⁠

A user is taken directly to your login page.

The login page sends a message to TestBox asking for credentials

TestBox responds with credentials

Log the user in by POST-ing your form as usual.

Whimsical diagram to go here describing the comms flow

Example Implementation
⁠
⁠

Install the

@testboxlab/browser⁠

package.

The NPM page on the link above will have more details on implementation, but here is a quick example of how to implement the login handler.

Want to print your doc?
This is not the way.

Try clicking the ⋯ next to your doc name or using a keyboard shortcut (

CtrlP

) instead.

Auto-login

Single Sign-on (SSO)

1 - JSON Web Tokens (JWT)​⁠⁠

2 - OpenID Connect​⁠⁠

Auth0

Firebase

3 - SAML​⁠⁠

Client-side Auto-login

Prerequisites​⁠⁠

Theory of operation​⁠⁠

Example Implementation​⁠⁠

1 - JSON Web Tokens (JWT)
⁠
⁠

2 - OpenID Connect
⁠
⁠

3 - SAML
⁠
⁠

Prerequisites
⁠
⁠

Theory of operation
⁠
⁠

Example Implementation
⁠
⁠