Skip to main content

Kraken OAuth

Note: This feature is still work in progress.

To enable login functionality on a consumer site, you can authenticate with Kraken as an identity provider instead of directly providing email and password to the obtainKrakenToken mutation. This approach is particularly beneficial when customers use the same login for multiple applications, as it allows the creation of a single login form that can be used independently by different consuming applications.

API Route​

The kraken-oauth API route is responsible for handling the OAuth flow using the Kraken Authorisation Server API.

Prerequisite values​

The client ID, client secret, redirect URI, and authorize URI are all required variables in the OAuth flow.

  • The client ID is a public identifier for the application. It is unique to the application and is used by the Kraken server to identify the application making the request. It is generated when an application is registered with Kraken.

  • The client secret is a confidential piece of information known only to the application and the Kraken Authorisation server. It is used in the OAuth flow to authenticate the identity of the application to the server when the application requests to exchange an authorisation code for an access token.

  • The redirect URI is the URL to which the Kraken server will send the user after they have successfully completed authorisation. This must match one of the redirect URIs registered with the application. It is used to ensure that the authorization code is sent to the correct application.

  • The authorize URI is the URL of the Kraken server's authorisation endpoint. The application sends the user to this URL in order to start the authorization process. The authorize URI includes parameters that tell the Kraken server about the request, including the client ID, redirect URI, and code challenge.

  • In this context, a code challenge is a cryptographic value that the client application generates and sends to the Kraken server as part of the authorization request. The code challenge is used to verify the integrity of the authorization process and prevent certain types of attacks, such as authorization code interception.

These four variables are provided when performing the OAuth query, redirect the user back to the application after authorisation, and ensure that the application is correctly identified and authorised by the Kraken server.

How is the OAuth flow initiated?​

The OAuth flow is initiated when a user clicks on the "Login with Kraken Auth" button. This sends a request to the kraken-oauth API route located at src/pages/api/auth/kraken-oauth.ts.

What happens in the serverless function?​

The serverless function at this route performs the following tasks by using the createKrakenOAuthURI utility function located in the auth package. This is performed server side using the getServerSideProps of the login page.

  • Generates a unique code verifier and code challenge.
  • Stores the code verifier in a secure HTTP-only cookie to send with the request headers.
  • Creates a URI to be navigated to, using the redirect URI, client ID and authorise URI.
  • Redirects the user to the Kraken authorisation endpoint with the code challenge and the application's client ID.

How is the OAuth flow completed?​

After the user authorises the application on the Kraken website, they are redirected back to the kraken-oauth API route with an authorisation code. The serverless function then performs the following tasks:

  • Retrieves the code verifier from the cookie.
  • Sends a request to the Kraken token endpoint with the authorisation code and the code verifier to exchange them for an access token and a refresh token.
  • Stores the access token and the refresh token in secure HTTP-only cookies.
  • Optional: Redirects the user to a success page.
    • This step is the default behaviour, however may be overridden by providing a custom function.

How are errors handled?​

The serverless function responsible for handling the OAuth flow includes error handling logic via an error handler to deal with authorisation related errors. When an error is caught, the user is redirected to the application's login page by default, where a relevant error message may be displayed.

How are the tokens used?​

The access token is used to authenticate all subsequent requests to the Kraken API. The refresh token is used to obtain a new access token when the current one expires. The token expiry value for the cookie is set to the value retrieved in the successful response.

What happens when a token expires?​

Note: This is intended functionality and has yet to be implemented

When the access token expires, a new one is obtained by sending a request to the Kraken token endpoint with the refresh token. If the refresh token also expires, the user is required to login again.

What happens when a user logs out?​

When a user logs out, the access token and the refresh token cookies are deleted.

Useful resources​

  1. OAuth 2.0 Simplified

  2. Modern Guide - What is OAuth 2.0 and How Does It Work?