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 |
|---|---|
| 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 |
| 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 |
| 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 /).