Callback handler

The callback handler is a redirect you implement in your app which allow users to sign in to the UserHub Portal

When one of your users is linked directly to the UserHub Portal, say from an invitation or billing statement email, the Portal needs a way to authenticate the request and create a session in the Portal. It does this by redirecting them to the callback handler in your app.

The callback handler is responsible for making sure the user

has an account in your app (i.e. sending them through the sign-in/sign-up flow), and then calling the create Portal session API endpoint and redirecting them to the URL in the response.

Before getting started, you'll need authentication working in your app, a user provider

set up in UserHub, and the ability to expose a public URL.

Decide to implement

If you use an identity provider that supports the OpenID Connect flow you don't need to implement this callback.

Instead, follow one of the provider-specific guides:

If your identity provider isn't supported, or you want full control over the UserHub Portal

sign-in process, continue to the next step.

Setup access to Admin API

Follow the Admin API getting started guide to set up the required credentials to make requests to the Admin API

Add a callback endpoint

Add a path to your app that authenticates the user

or sends them through your sign-in or sign-up flow if required.

You'll need to keep track of the full callback path and redirect the user to it after signing them in.

Here is a basic example of what this might look like:

@app.route("/userhub")
def userhub_callback():
    user_id = session.get("user_id")
    if not user_id:
        # This should sign the user-in/sign-up and redirect back to the
        # "/userhub?portalUrl=..." on success.
        return redirect(url_for("app.signin", redirect_url=request.url))

Create Portal session

Next, you need to generate a redirect URL by calling create Portal session and use the redirectUrl in the response to redirect the user

back to the Portal.

Here is an updated example:

@app.route("/userhub", methods=["GET"])
def userhub_callback():
    # This is your identity provider's user ID
    # (e.g. google-oauth2|1030...).
    user_id = session.get("user_id")
    if not user_id:
        return redirect(url_for("app.signin", redirect_url=request.url))

    admin_api = AdminApi(os.environ["USERHUB_ADMIN_KEY"])

    # This is the connection ID for your user provider
    # (e.g. Auth0, Custom Users, etc.).
    #
    # You can get it from the connection details page via
    # Developers -> Connections in the Admin console.
    connection_id = os.environ["USERHUB_USER_CONNECTION_ID"]

    res = admin_api.users.create_portal_session(
        # This is a way to reference the user by the identity provider's
        # user ID and can be used for any API call that takes a user ID.
        #
        # When used in the create Portal session API call it also
        # has the added benefit of automatically importing the user if
        # they don't already exist in UserHub.
        user_id=f"{user_id}@{connection_id}",
        # This is a query parameter included in the callback handler
        # request and is the Portal page the user is trying to load.
        #
        # It must be included in the API call for the callback handler to
        # work.
        portal_url=request.args.get("portalUrl"),
    )

    return redirect(res.redirect_url)

Set your callback URL

The final step is to configure your callback URL in the Admin console

Go to the Admin console and click Portal via the Developers dropdown or Tenant settings
Enter your newly created Callback URL (following the example above, if your app runs at example.com and your callback route is defined as /userhub, you would enter https://example.com/userhub)
Click Save

Finally click the View Portal link at the top of the page and try signing in to the Portal