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
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/api/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/api/app/oauth2/callback?code=wrva_ds656f566e_ddd5&state="{"appId": '', providerId: ''}"
- Response type is token: redirect access_token within URL fragment
https://app.buildfire.com/api/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'
}
- Read more Information about OAuth 2.0.
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) .
Name | Required | Description |
---|---|---|
Authorize URl | yes | The HTTPS URL where authorization to use OAuth2.0 is started. |
Token URL | yes | The URL where the access token will be requested. |
User Info URL | yes | The URL where the user information will be requested. |
Redirect URL | yes | Important 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 ID | yes | The client ID generated by provider (Business Partner). This is the public identifier of the application on the provider side. |
Client Secret | yes | The Client Secret generated by provider. This is the shared secret between the application and the provider ensuring the authorization is secure. |
Scopes | yes | A 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 chooseOAuth2 Sign In Integration
.Once choose
OAuth2 Sign In Integration
option, we will seeAdd OAuth2 Integration
dialog.Start filling the required fields for
Design
andConfigurations
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
Name | Required | Description |
---|---|---|
Integration Name | yes | The logical identifier of the integration. |
User Info Request Method | yes | Specify the HTTP request method that used to request user info. The allowed methods are POST and GET. |
User Info Request Body | no | The HTTP request body fields to request user info if required. Only valid for POST method . |
Response Type | yes | This 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 duringAdd OAuth2 integration
by fillingUser Info Object Keys
form.User Info Object Keys:
Name Default User Object Key Description Id (sub)
sub The unique user identifier, Important
we should mapping it correctly, Auth flow will be fail if it's found.Email
email User's email. First Name
given_name User's first name. Last Name
family_name User's last name. Display Name
name User's display name. We can set default
User Info Object Keys
based onBusiness 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.