We need to use the “Oauth2 User-Agent Flow” method when we want to execute some tasks on the user’s behalf, like adding an event to his Google Calendar or publishing a post on his Facebook page. When we only want to provide the “Sign Up With Google/Facebook” Feature we can use the Bubble-made Plugins, these plugins don’t help us execute tasks on behalf of the user, and the other plugins may not have all the actions or all the parameters we need.
To use an API we have to exchange information with its provider:
When we need to use an API that requires authentication, we need to create an account at its provider platform, and set settings and information about our app, also we need to get information from the API provider for our app settings, so our app and the API provider can communicate correctly.
For the easy APIs that require only an API Key for authentication, we need to set the basic profile information, get the API key, and we are good to go, but for the APIs that require an Oauth2 authentication method, we need to exchange more information.
For the Oauth2 authentication method, after creating an account at its provider platform (eg Google Cloud Console or Facebook Developers platform) we could easily feel overwhelmed if didn’t have enough perception about the Oauth2 authentication process, how the information we exchange relates to it, what parts Bubble do automatically for us, and what parts we have to address manually.
Oauth2 steps, settings, and information needed:
The Oauth2 authentication process includes the following basic steps:
1- The user clicks on the “Signup/Login with Google/Facebook/etc.” button: we address this step by making a button that when clicked the “Signup/Login with social network” action is executed.
This is a Bubble side step and we have to address it manually, and no information exchanging is needed.
2- The user navigates to the “Login Dialog” (Consent Screen in Google terms): this is where the user signs up/logs in and grants you the permissions you need to execute tasks on his behalf. For this to work you have to exchange some information with the API provider:
2-1- You need a “Redirect URL” to navigate to the login dialog, you found this URL in the documentation of the API provider, so you need to copy it and past it into the “Login dialog redirect” field in the “Oauth2 User-Agent Flow” screen in the API connector.
If you do this correctly, Bubble will automatically navigate the user to this URL when the “Signup/Login with social network” action is executed.
2-2- The API provider only displays the login dialog (or consent screen) if the redirect URL is visited from an app that is registered in his platform, when you create an account at the API provider platform he gives you an “App ID” and “App Secret”, so these App ID and App Secret should be sent as parameters when the redirect URL called (visited), if these parameters have valid values, the API provider will authenticate your app and display the login dialog to proceed the process.
These “App ID” and “App Secret” can be found somewhere inside your account at the API provider platform, so you need to copy them and paste them into the related fields in the “Oauth2 User-Agent Flow” screen in the API connector.
If you do this correctly, Bubble will automatically send them with the redirect URL.
2-3- The next step in the login dialog is the permissions granting, the API provider needs to know what resources you want to access on the user’s behalf to ask the user if he could grant you permission to access them.
You can find these resources in the Documentation of the API provider or inside your account in his platform under the name Scops or Permissions, so you need to copy them and past them into the “Scope” field in the “Oauth2 User-Agent Flow” screen in the API connector.
If you do this correctly, Bubble will automatically send this scope as a parameter with the redirect URL.
3- The user navigates back to your app after granting you the permissions: the URL to be returned to is called “Redirect URI” (URI not URL), so you have to tell the API provider what redirect URIs are valid (or authorized) by inserting them into the relevant field in your account at the API provider platform, so he navigates the user to them after completing the login process.
The valid redirect URIs (or authorized redirect URIs) are the URLs of the pages from which the user would be navigated to the login dialog after he clicks on the Signup/Login button, so if there is a Signup/Login button in the https://mypage.com, this URL should be added to as a “redirect URI”.
Bubble provides a generic redirect URI (he calls it “generic redirect URL” which can be found in the “Oauth2 User-Agent Flow” screen in the API connector), so instead of inserting all the URLs of the pages that contain a Signup/Login button as redirect URIs, you can insert only this generic redirect URL and Bubble will smartly navigate the user to the page that he moved from, but it doesn’t work for all APIs, so you have to check this for the API you are trying to integrate with. If you will use the “generic redirect URL”, check the “Use a generic redirect URL…” checkbox.
When the API provider calls the “redirect URI” and the login process succeeds, the API provider sends an “Authorization code” as a parameter with the call.
If you set these URIs correctly, the user will be redirected back to your app and Bubble will automatically get the authorization code.
4- When Bubble gets the Authorization code (which means that the user is found in the API provider database and your app is authorized as a registered app at the API provider platform), Bubble will exchange the authorization code for an “access token” and “refresh token”, so the access token will be used for the following calls that access the resources of the user at the API provider platform, and the refresh token will be used to get a new access token whenever needed.
The exchanging process is done by calling an endpoint named “Access token endpoint”, to do this, Bubble needed to know two things:
4-1- What the “Access token endpoint” is, you will find this endpoint in the API documentation, copy it, and paste it into the related field in the “Oauth2 User-Agent Flow” screen in the API connector.
4-2- If this call should be done using “Basic Auth” (which means that the authorization code will be sent as a header parameter), if yes, check the “Requesting an access token uses Basic Auth” checkbox, this information can also be found in the API provider documentation that explains the login implementation.
If you provide the correct access endpoint and determine if it should be called using a basic call, Bubble will automatically get the access token and the refresh token the access token and the refresh token and store them for future API calls.
5- Bubble accesses the profile information of the user at the API provider platform (if possible): Bubble does this for you automatically after the user comes back to the app page, this is because Bubble supposes that you want this information, it is just a normal call like any call you would do (eg adding an event to the user’s Google Calendar or publishing post in the user’s Facebook page). To enable these API calls, Bubble needs the following:**
5-1- Whether the access token should be sent with the API calls as a query parameter or as a header parameter (many APIs accept both but prefer the header parameter), this information can be found in the API documentation within the API calls configurations.
If it goes in the header check the “Authentication goes in the header” checkbox in the “Oauth2 User-Agent Flow” screen in the API connector; otherwise, leave it unchecked.
5-2- The name of the parameter’s key that will hold the access token as a value when it is sent with the API calls, this information also can be found in the API documentation within the API configurations, the default URL parameter key name is “access_token”, and the default header parameter key name is “Authorization” (the value should be started with “Bearer “), so you need to be sure that the correct name is inserted into the field named “Token name” if the previous checkbox is unchecked, or “Header Key” if the previous checkbox is checked.
If you set this checkbox and the previous one correctly, Bubble will automatically include the access token in the API calls.
5-3- The endpoint that fitches the user’s information with the names of the ID and the email parameters: if the permissions granted to you allow you to access the user’s profile information, Bubble will do this call automatically, but he will ask you to provide the endpoint and the keys names in all cases. This information can be found in the API documentation, so you need to copy and paste them into the fields named “User profile endpoint”, “User ID key path”, and the “User email key path”.
If you do this correctly, Bubble will automatically fitches the user information.
Google:
- The “Redirect URL” of the “Consent Screen” is this, it can be found here.
- The “App ID” and “App Secret” can be found after logging in to the Google developer console and creating a new project, you have to click on the three lines at the left for the sidebar to appear, then hover over “APIs and Services”, then click on “Credentials”, then set the consent screen configuration and create credentials.
- A list of scopes can be found here.
- Google accepts the generic redirect URL of Bubble, it can be inserted under the “Authorized redirect URIs” when you create credentials.
- Google requires the access token endpoint to be called using basic auth, so check the “Requesting an access token uses Basic Auth” checkbox.
- Google accepts the access token as a URL parameter and as a header parameter but prefers the header parameter so check the “Authentication goes in the header” checkbox, by checking this checkbox, the appropriate value will be inserted automatically in the “Authorization” Field, do not change it.
- The user profile endpoint is this, and leave the following fields as is, this can be found here.
Facebook:
- The “Redirect URL” of the “login dialog” is this, it can be found here.
- The “App ID” and “App Secret” can be found after logging in to the Facebook developer platform and creating a new app, you have to click on the “App settings” at the left sidebar, then click on “Basic”.
- A list of permissions can be found here.
- Facebook doesn’t accept the generic redirect URL of Bubble and doesn’t display the login dialog if it is visited from a page where its URL is not inserted in the “Valid OAuth Redirect URIs” field, this field can be found after creating an app in your account in the Facebook developers platform, to be able to publish posts on the user’s behalf choose the “Business” app type, then clicking on “set up” button of the “Facebook Login for Business” product.
- Facebook requires the access token endpoint to be called using basic auth, so check the “Requesting an access token uses Basic Auth” checkbox.
- Facebook accepts the access token as a URL parameter and as a header parameter but prefers the header parameter so you can check the “Authentication goes in the header” checkbox if you prefer, the appropriate value will be inserted automatically in the “Authorization” Field, do not change it.
- The user profile endpoint is this, and leave the following fields as is, this can be found here.
I hope this helps in understanding Oauth2 in general and the “Oauth2 User-Agent Flow” method in the API connector. I will be glad for any additions, improvements, or corrections.