Skip to main content

Authentication

There are four ways we authenticate access to self-service features:

  • Email and password provides standard customer login.
  • OAuth delegates login to the Kraken Auth Server and is the recommended replacement for email and password.
  • Masquerade allows support users to sign in on behalf of a customer.
  • Expiring URLs provide access to particular features via a link, usually emailed to the customer by Kraken or a customer service user.

The end result of each of these processes is a Kraken token. To learn more about the mechanisms of authentication end to end, please see our Guide to Authentication.

Login​

This is the standard login page where a user puts in their email and password. Here is what that looks like in an app:

View Full Story →

Login with OAuth​

When the Kraken Auth Server is configured, the login page also shows a "Sign in with Kraken" button alongside the email and password form.

For setup instructions, see the Kraken OAuth guide.

View Full Story →

Login with HCaptcha​

When captcha is enabled in Kraken and the HCAPTCHA_SITEKEY environment variable is set, the login page will show a hCaptcha widget. The user must solve the captcha before they can log in.

View Full Story →

Masquerade​

This is how a support user in Kraken can log into the consumer site for that Kraken instance with a customers user details, to see the site as the customer sees it.

Expiring URLs​

This is how a user can access various features without having to log in at all, generally via a link sent in email. We use this for features that have a very high value to the business. These features therefore require the friction for the customer performing the given action to be as low as possible. These URLs might be sent by a support user, or automatically via Kraken. In Blueprint, these URLs are supported by providing a dynamic route which takes a preSignedKey which we exchange for an authorization token with limited scope, and set a cookie with that token using middleware. preSignedKeys are generally scoped to allow the user to perform particular actions. Some examples are to provide feedback on a customer service interaction or a meter reading. By limiting the scope to particular actions, we reduce the impact of these urls being accidentally shared by the customer, since the actions that can be performed with them are limited.

Expiring URLs step by step​

  1. To see this feature in action, we first choose which expiring url we'd like to access. You can see which are supported in the app in the src/pages/anon directory. The Foundation app supports the customer service feedback url, so we'll use that for our example.

    Prerequisite

    This example assumes your Kraken has a customer feedback form set up and you've generated a customer feedback object for your chosen test account. See the Global Technical Guide for that setup.

  2. Next we need to generate a preSignedKey. You can generate that in your test Kraken environment using the 'Generate an expiring URL' recipe and your chosen test account. Kraken will generate a full example url, but the preSignedKey is the bit that follows key=. We then provide this to our chosen route, so for example, if your local server is running on port 3000 and the KRAKEN_GRAPHQL_ENDPOINT is set to your test Kraken, you can use:

    localhost:3000/anon/<key_goes_here>/<account_number_goes_here>/<feedback_form_id_goes_here>/<feedback_id_goes_here>`

  3. Configure middleware with the recommended catch-all matcher:

    export const config = {
      matcher: ["/", "/((?!api|_next|_vercel|.*\\..*).*)"],
    };

    Middleware sends the pre-signed key to the obtainKrakenToken mutation. Kraken returns a scoped access token. Blueprint Auth verifies the token and its PRE-SIGNED-TOKEN grant. It stores the token in the accessToken cookie. The cookie expiry comes from the verified exp claim. The scoped token can access anonymous routes and routes that allow both anonymous and dashboard access. It cannot access a standard dashboard route.

  4. This should then render the customer feedback form for that account and allow the user to submit feedback.

Security of Expiring URLs​

Blueprint Auth applies these cookie options by default:

Use customization.getCookieOptions to change these options. httpOnly prevents browser scripts from reading the cookie. It does not prevent cross-site scripting (XSS).