Implementing OAuth 2.0 into Your Product

Introduction

One of the biggest issues in the restaurant technology space is the lack of automation for onboarding merchants onto new services. This is especially true for Point of Sale (POS) and Delivery Service Provider (DSP) applications. The process of onboarding a merchant is often manual and time-consuming, sometimes requiring the merchant to provide their credentials to the application provider. This can lead to weeks of delay for the merchant and guarantees fragile integrations.

When integrating with Stream as a POS or DSP, we strive to give our users the most Stream-lined experience in all aspects of our products. If you want state-of-the-art security for 3rd party data access or have aspirations to build your own app store within your product ecosystem, then we recommend building the following solution.

Overview

In this document, we'll discuss how to implement OAuth 2.0 into your product to fully automate onboarding of merchants. OAuth 2.0 (RFC 6749) is a protocol that allows a user to grant a third-party web site or application access to their resources, without necessarily revealing their credentials. This document provides a high-level overview of how to implement OAuth 2.0 in your product to fully automate onboarding of merchants. The process includes setting up an Authorization Server, implementing Client Applications, and enabling Resource Owners (in this case, the merchants) to grant access to their resources.

1. Build The Authorization Flow

The Authorization Server is the software that issues access tokens to Stream after successfully authenticating the resource owner and obtaining authorization. To set this up, you'll need to:

• Build a web page for merchants to log in to their existing accounts. Stream will redirect them to this page with our client_id as a query parameter.
  • If a merchant reaches this page without an account, you can redirect them to a sales page to sign up recognizing Stream as the lead-gen by the client_id.
  • After successful login, show the merchant a confirmation button that explains which resources they are granting Stream access to.
• Build a token endpoint /v1/token supporting the following grant types.
  • authorization_code - where Stream can exchange an authorization code for an access_token, expire_time (for the access token), and refresh_token by authenticating with our client secret created in the next step.
    • expire_time should be Unix time in milliseconds. https://currentmillis.com/
      • Suggestion: Set the token expiration period to 30 days. We aim to refresh the token 7 days before its expiration to allow ample time for troubleshooting if any issues arise with the integration.
  • refresh_token - when the access token is near expiration, Stream will send a request to your token endpoint with the refresh_token to obtain a new access_token and expire_time.
    • The refresh_token can remain the same if desired, otherwise we will support refresh token rotation as well.
      • If no rotation supported, you will want to provide refresh_token_expire_time. We will use this to begin to send refresh notifications when closing in on the expiration, in attempt to successfully refresh prior to expiration.

2. Register Stream As Client Application

Client Applications are 3rd party entities (such as Stream) that request access to a merchant's resources.

• You must provide a unique client ID and a client secret for Stream to securely exchange authorization codes for tokens.
• We will provide our redirect URI for you to send merchants back to with the authorization code attached as a query parameter after successful authentication.

3. Support Access Tokens For Resource Endpoints

• When building the required endpoints for your Stream integration, you must support access token authorization for the endpoints labeled as Stream -> <POS or DSP> (OAuth)

4. Handling Refresh Token Expiration

• If you decide not to support refresh token rotation, or use a platform that doesn't allow for it like Cognito, then you must handle the expiration of the token accordingly.
  • Support refresh_token_expire_time on the /v1/token response.
  • Properly return 401 on refresh when expired, so repeated attempts don't occur.
  • Monitor alerting for refresh token expirations, manually reconnecting where needed.
    • When a refresh token is near expiration (within 30 days), we will alert you in preparation of this expiration. During this time, you can go into the platform and manually reconnect the integration through settings to prevent interruptions.

Conclusion

In conclusion, implementing OAuth 2.0 into your product involves setting up an Authorization Server, implementing client applications, and enabling resource owners to grant access to their resources. By carefully considering the security aspects and complying with the OAuth 2.0 standards, you can ensure a smooth and secure experience for your merchants.

If you follow the steps outlined in this document, you'll be able to implement OAuth 2.0 into your product and fully automate onboarding of merchants. For more information, see the OAuth 2.0 specification. If you have any questions or would like to discuss your implementation, please reach out to us at partners@streamorders.com. We appreciate your interest in building high quality solutions for your customers.