Pylon supports two authentication methods for portal and knowledge base login for your customers - passwordless and JWT Single Sign On (SSO). These settings can be configured in the Workspace tab in your Pylon settings page.

Passwordless login

Our default authentication method allows users to input their email, and perform a no-password login using a one-time passcode sent to their email.

From there, they’ll be redirected to their customer portal only if they have access to the portal.

JWT SSO

Single Sign-On (SSO) allows users to log into different applications securely and quickly. Pylon uses the JSON Web Token (JWT) protocol for sign on.

Token Required Attributes

• iat : Token Issue Time. The token will not be accepted after 60 seconds (1 minute).

• email : email address of the user performing the login. Pylon uses this field to map to the user in the Pylon system.

• aud : Token Audience. Must be the value https://portal.usepylon.com

• iss : Issuer. Must be the base URL of the remote login url, discussed below. This must contain a trailing slash /.

  • e.g. For remote login url https://your.domain.com/callback, the issuer should be https://your.domain.com/

Token Optional Attributes

• account_id : Account ID. If a contact has not been created, Pylon can create one during the user's first log in. You can optionally provide an account ID. Otherwise, Pylon will use email domain matching to identify the user.

Pylon supports the following Signing Algorithms for JWT:

• HMAC SHA-256: HS256

• HMAC SHA-384: HS384

• HMAC SHA-512: HS512

Configuration

To enable this for your customers, Pylon will need some information:

• Remote Login URL: If enabled, an unauthenticated user will be redirected to this URL to perform a login.

  • During your user's authentication flow, Pylon will include a redirect_uri query parameter with this redirect. After the user has authenticated with your system, you must redirect the user to this URL, with the JWT as a query param under the key access_token .

    • Note that the URL contains an existing query param, you can simply append &access_token=<token> to redirect_uri to compose the URL.

• Remote Logout URL, Optional: When the user performs a signout, they’ll also be redirected to this URL, allowing the user to be logged out of other systems.

• Shared Secret: This secret is used to sign the JWT before sending it to Pylon, ensuring that the JWT is from a trusted source. You must keep this secure.

More details on adjusting visibility of articles after setting up customer authentication are available here.

Example Auth0 Post-login action for JWT SSO

This example hardcodes the redirect URL, which will always redirect users to the portal. However, to accommodate scenarios where users access specific pages (e.g., a private knowledge base article), you should utilize the redirect URL provided by Pylon. A recommended approach is:

• Store the redirect URL in your application prior to redirecting to Auth0.

• Authenticate the user within Auth0.

• Return the user to your application.

• Finally, redirect them to the Pylon URL.

const jwt = require('jsonwebtoken')

exports.onExecutePostLogin = async (event, api) => {
    // Select an auth0 client id to use for the redirect, optional.
    if (event.client.client_id == "<CLIENT_ID>"){
        const email = event.user.email
        
        const pylonPayload = {
            iat: Math.floor(Date.now() / 1000),
            email,
            iss: "<ISSUER>",
            aud: 'https://portal.usepylon.com'
        };

        const options = {
            algorithm: 'HS256',
            expiresIn: '10h'
        };

        const token = jwt.sign(pylonPayload,"<SECRET>", options);
        // URL is hardcoded here, but you'll want to use the redirect url provided by Pylon.
        const url = `http://graph.usepylon.com/callback/jwt?orgSlug=<ORGSLUG>&access_token=${token}`
        console.log(url)
        api.redirect.sendUserTo(url, {
            query: { access_token: token }
        });
    }
};