Skip to main content

Using OAuth2 Sign In Integration

The purpose of this feature is to to allow app owner to setup his application to obtain access to user accounts on an HTTP service (Business Partner Service) support OAuth2 protocol such as GitHub, Slack, FitBit, etc. So the app owner can easily setup the service requirement to provide their user a new Sign In method for his App.

Authorization Flow#

Deep Link

1- BuildFire Auth server start login flow by request Authorize URL.

https://www.example.com/authroize?response_type=code&client_id=CLIENT_ID&redirect_uri=https://app.buildfire.com/app/oauth2/callback&scopes=profile&state="{"appId": '', providerId: ''}"

2- Authorization Server redirects the user to the login and authorization prompt.

3- The user authenticates using his username and password on Authorization Server side.

4- The Authorization Server redirects the user back to the BuildFire Auth server with an authorization code, which is good for one use.

  • Response type is code: redirect code within URL query string
    https://app.buildfire.com/app/oauth2/callback?code=wrva_ds656f566e_ddd5&state="{"appId": '', providerId: ''}"
  • Response type is token: redirect access_token within URL fragment
    https://app.buildfire.com/app/oauth2/callback#access_token=wrva_ds656f566e_ddd5d&state="{"appId": '', providerId:''}"

5- Callback handle query params or fragment that attached to redirect URL.

6- BuildFire Auth server sends this code to the Authorization Server (token endpoint) along with the application's Client ID and Client Secret (Request Access Token).

Request Parameter:
client_id': <CLINET_ID>
client_secret': <CLINET_ID>
grant_type': 'authorization_code'
code': 'wrva_ds656f566e_ddd5'
redirect_uri': 'https://app.buildfire.com/app/oauth2/callback'
Request:
Method: POST
Host: https://www.example.com/token
Content-Type: application/x-www-form-urlencoded

7- Authorization Server verifies the code, Client ID, and Client Secret and responds with an Access Token (and optionally, a Refresh Token) to BuildFire Auth server.

Response
Content-Type: application/json
{
โ€ƒ"access_token":"[access_token]",
โ€ƒ"token_type":"bearer",
โ€ƒ"refresh_token":"[refresh_token]",
โ€ƒ"expires_in":43192
}

8- BuildFire Auth server use the Access Token to call an User Info URL to access information about the user.

Request
Menthod: GET
Host: https://www.example.com/userinfo
Authorization: Bearer [access token]
Content-Type: application/json

9- BuildFire Auth server save user info and create session for authenticated user.

Response
Content-Type: application/json;
{
sub: '545454-54565-6565'
given_name: 'Moe',
family_name: 'Hasan',
name: 'Moe Hasn',
email: 'moe@gmail.com'
}

OAuth2 Prerequisites#

To support OAuth2 in our apps there are standard configurations should provide it, and we can get this configurations form provider side BP (Business Partner) .

NameRequiredDescription
Authorize URlyesThe HTTPS URL where authorization to use OAuth2.0 is started.
Token URLyesThe URL where the access token will be requested.
User Info URLyesThe URL where the user information will be requested.
Redirect URLyesImportant The redirect URL that must be saved on the provider side(Business Partner). This redirects the authentication flow back to the platform to complete the initial process.
Client IDyesThe client ID generated by provider (Business Partner). This is the public identifier of the application on the provider side.
Client SecretyesThe Client Secret generated by provider. This is the shared secret between the application and the provider ensuring the authorization is secure.
ScopesyesA space-delimited list of scopes that identify the resources that your application could access on the user's behalf.

Setup OAuth2 Sign In Integration#

To add OAuth2 Sign In Integration continue with the following steps.

  • Go to Control Panel (CP) app.

  • From side menu under Security nav, Open Login Screen page.

  • Navigate to Settings tab.

  • Click on Add Sign In Integration button , then choose OAuth2 Sign In Integration.

    Deep Link

  • Once choose OAuth2 Sign In Integration option, we will see Add OAuth2 Integration dialog.

    Deep Link

  • Start filling the required fields for Design and Configurations sections.

  • Take care of Extra Important OAuth2 Requirements below.

  • Advance section important for mapping user info object keys, more details ofr mapping user info below.

  • Once verify everything is correct, click save;

  • we will see new integration added to Sign In Integrations

Extra Important OAuth2 Requirements

NameRequiredDescription
Integration NameyesThe logical identifier of the integration.
User Info Request MethodyesSpecify the HTTP request method that used to request user info. The allowed methods are POST and GET.
User Info Request BodynoThe HTTP request body fields to request user info if required. Only valid for POST method.
Response TypeyesThis Control which flow will be used to return the access_token. Using a value of code will use the Authorization Code Flow and using a value of token will use the Implicit Grant Flow.

Mapping User Info

  • The idea here to make BuildFire Auth Server able to read user info object properties responding form the Business Partner server and store it to our users table.

    We can do that in Advanced section during Add OAuth2 integration by filling User Info Object Keys form.

  • User Info Object Keys:

    NameDefault User Object KeyDescription
    Id (sub)subThe unique user identifier,Important we should mapping it correctly, Auth flow will be fail if it's found.
    EmailemailUser's email.
    First Namegiven_nameUser's first name.
    Last Namefamily_nameUser's last name.
    Display NamenameUser's display name.
  • We can set default User Info Object Keys based on Business Partner server's response for User Info.

After authorization#

We will store BP's authorization token with the user (in a oauth2Integration object) and issue our own access token to access BuildFire resources. This will allow for backward compatibility. The user will now be able to use the BuildFire app as a login user. In a plugin, you can call buildfire.auth.getCurrentUser() see more here and it will return the oauth2Integration object in the user object as oauthProfile see more here . This will allow the app and any plugins to make API calls to BP's resources.

Example#

Here is an example to add OAuth2 GitHub Integration.

Design#

Deep Link

Configurations#

Deep Link

Deep Link

Advance (Mapping User Info Object Keys )#

Deep Link