Skip to content

OAuth 2 (social login)

subZero support 3rd party login (also called social login) by implementing OAuth 2.0 protocol for authorization.

By default, the the following authentication providers are configured.

Name ID
Google google
Facebook facebook
GitHub github

Upon successful login, subzero will call an (internal) uri defined by OAUTH_SUCCESS_URI env variable. The default implementation for that endpoint will set a SESSIONID cookie (exactly like with local login) then redirect to / with a 303 status code.

Configure OAuth 2.0 providers

Before using OAuth login flow, you must register an application with the appropriate authentication provider (Google/Facebook/GitHub).

Your application will be issued an app ID and app secret, which need to be provided as env variables to subzero container. You will also need to configure for each provider in their respective interfaces, a redirect URI which matches the route in your api. The uri will be of the following form:
https://<you-api-domain>/oauth/callback?provider=<providerid>

For example, for google it may look like
https://mysubdomain.subzero.cloud/oauth/callback?provider=google

Configure subZero container

To enable OAuth login, define the appropriate env variables when configuring the subzero container image. The bold variables are required to enable a provider, the rest are optional (pre-configured)

Var name Description
OAUTH_SUCCESS_URI The function to call upon successfully login
default: /rest/rpc/on_oauth_login
the function is defined in db/src/api/on_auth_login.sql
Google
OAUTH_GOOGLE_CLIENT_ID OAuth client id
OAUTH_GOOGLE_CLIENT_SECRET OAuth client secret
OAUTH_GOOGLE_AUTHORIZATION_URL default: https://accounts.google.com/o/oauth2/v2/auth
OAUTH_GOOGLE_TOKEN_URL default: https://www.googleapis.com/oauth2/v4/token
OAUTH_GOOGLE_USERINFO_URL default: https://www.googleapis.com/oauth2/v3/userinfo
OAUTH_GOOGLE_SCOPE default: email profile
Facebook
OAUTH_FACEBOOK_CLIENT_ID OAuth client id
OAUTH_FACEBOOK_CLIENT_SECRET OAuth client secret
OAUTH_FACEBOOK_AUTHORIZATION_URL default: https://www.facebook.com/v3.2/dialog/oauth
OAUTH_FACEBOOK_TOKEN_URL default: https://graph.facebook.com/v3.2/oauth/access_token
OAUTH_FACEBOOK_USERINFO_URL default: https://graph.facebook.com/v3.2/me
OAUTH_FACEBOOK_SCOPE default: email
GitHub
OAUTH_GITHUB_CLIENT_ID OAuth client id
OAUTH_GITHUB_CLIENT_SECRET OAuth client secret
OAUTH_GITHUB_AUTHORIZATION_URL default: https://github.com/login/oauth/authorize
OAUTH_GITHUB_TOKEN_URL default: https://github.com/login/oauth/access_token
OAUTH_GITHUB_USERINFO_URL default: https://api.github.com/user
OAUTH_GITHUB_SCOPE default: user:email

Initiating the OAuth login flow

To start the login flow, perform a post request (using a simple html form) to a url of the following form:
/oauth/login?provider=<providerid>

This action will redirect the user browser to the desired authentication provider and upon successful login, the user will be redirected back to the callback uri that you configured for that provider. At this point, subZero will validate the call (verify the provided 3rd party tokens) and then call the endpoint configured in OAUTH_SUCCESS_URI where you have the ability to customize the rest of the authentication flow (the default implementation, will perform an UPSERT, set the authentication SESSIONID cookie and redirect the user to /).