Bitrix24 Applications

OAuth 2.0

OAuth is an open authorization protocol that provides a limited access to protected user resources for third parties without the need to pass logistics and password to such third party.

The protocol operates as follows

Protocol is very widespread and employed by a vast number of services worldwide. It allows getting access to API on behalf of user name on specific account.

Authorization for the server - is an indication that user has granted access to the application and the app has submitted its secret. Bitrix24 account unifies all this data and assigns a corresponding type of access permission to the app.

Protocol consist of two steps:

• User informs Bitrix24 account that he/she has successfully been authenticated. Application adds its ID: client id. In response, server passes the first authentication code to the user, and via user, passes it to the application: code.
• This is an app code that is hidden from user, and passes back to the account Important! The code query cannot be executed via AJAX query from other site page's, because it will be blocked by the browser. Request to retrieve access token must be originated from app's server configuration. , connecting its secret key: client secret. This way, the app confirms that it is the same application known to the Bitrix24 account and can be handled by it. The account's response contains two parameters: access_token - parameter that directly required to access authentication and refresh_token - token required for extending authentication.
• After using refresh_token and jointly issued access_token become invalid. To access REST API, use the newly retrieved access_token, and to extend access - new refresh_token.

General OAuth handling procedure

• add and install a public application or a local app on an individual Bitrix24 account;
• request keys from remote server;
• server re-directs browser to URL, registered by the application;
• response is processed;
• retrieved key signs all Rest API queries.

Full OAuth-authentication in Bitrix24

Specific Bitrix24 acts as data server and stores user authorization. Authorization server accessible via the address https://oauth.bitrix.info/ acts as authorization holder.

Full OAuth authorization scenario consists of several steps:

1. User authentication in Bitrix24.

   Application requests Bitrix24 URL from user and forwards it to a specially generated URL, for example:

   https://portal.bitrix24.com/oauth/authorize/?
       client_id=app.573ad8a0346747.09223434
       &state=JJHgsdgfkdaslg7lbadsfg

   Parameters:

   • сlient_id - application ID, retrieved in the Partner's account when registering an application (and valid for any Bitrix24). In case of local app it also can be retrieved in a specific Bitrix24 account (valid only for such Bitrix24). Required parameter.
   • state - additional parameter, allowing the app to pass arbitrary additional data between authorization steps. Optional parameter.

   This link displays authorization form for a user. If the app with passed client_id is installed on the account after authorization is complete (or during authenticated session), it returns user to redirect_uri of the app. When the app isn't installed on the account, prints an errors message for user.

   Final result of successful authentication is user's return to registered app's URL with additional parameters:

   https://www.applicationhost.com/application/?
       code=avmocpghblyi01m3h42bljvqtyd19sw1
       &state=JJHgsdgfkdaslg7lbadsfg
       &domain=portal.bitrix24.com
       &member_id=a223c6b3710f85df22e9377d6c4f7553
       &scope=crm%2Centity%2Cim%2Ctask
       &server_domain=oauth.bitrix.info

   Parameters:

   • code - first authorization code, see. below;
   • state - value passed in the first query;
   • domain - account's domain used for authorizaton;
   • member_id - unique account ID used for authorizaton;
   • scope - comma-separated list of access permissions to REST API, provided by account to the app;
   • server_domain - domain for authorization server.
   Attention! Partner's account can have a registered application without "redirect address" redirect_uri. (redirect_uri is used to get autherization data.) Such scenario is possible for public applications that don't have permanent address. In this case, it's presupposed that user manually passes first authorization code to an app. Simplified first autherization code will be displayed to the user directly on the page and the app must show user the field to input the code.

2. Application authentication

   Attention! Previous version of implemented protocol included the passing of app's client_secret directly to Bitrix24. However, due to expanding of Rest API mechanism to Bitrix24 Self-hosted editions such action becomes unsecure. All operations that include a secret code must be performed exclusively with authorization server oauth.bitrix.info. Due to the same reason, this authorization server must be the only one trusted source of app's payment status information at the account.

   When the apps gets the first authorization code, it must take a second step in OAuth-authorization and execute a request, hidden from user as follows:

   https://oauth.bitrix.info/oauth/token/?
       grant_type=authorization_code
       &client_id=app.573ad8a0346747.09223434
       &client_secret=LJSl0lNB76B5YY6u0YVQ3AW0DrVADcRTwVr4y99PXU1BWQybWK
       &code=avmocpghblyi01m3h42bljvqtyd19sw1

   Parameters (all - required parameters):

   • grant_type - parameter, showing type of authorization data to be validated. Must contain authorization_code value;
   • client_id - application ID code, received in Partner's account when registering the application either on the account or in case of local application;
   • client_secret - application secret key, received in Partner's account when registering the application either on the account or in case of local application;
   • code - code parameter value, passed to the app at the end of next step приложению в конце предыдущего шага.
   Attention! Lifetime for the first autherization code is only 30 seconds, meaning it must be used immediately after received.

   App receives json in the response as follows:

   GET /oauth/token/
   
   HTTP/1.1 200 OK
   Content-Type: application/json
   
   {
       "access_token": "s1morf609228iwyjjpvfv6wsvuja4p8u",  
       "client_endpoint": "https://portal.bitrix24.com/rest/",  
       "domain": "oauth.bitrix.info",  
       "expires_in": 3600,  
       "member_id": "a223c6b3710f85df22e9377d6c4f7553",  
       "refresh_token": "4f9k4jpmg13usmybzuqknt2v9fh0q6rl",  
       "scope": "app",  
       "server_endpoint": "https://oauth.bitrix.info/rest/",  
       "status": "T"
   }

   Main parameters:

   • access_token - main authorization token required for accessing REST API;
   • refresh_token - additional authorization token for extending saved authorization period;
   • client_endpoint - address for account's REST interface ;
   • server_endpoint - address for server's REST interface;
   • status - application status at the account.

   Also, at this stage the application can get authorization error when commercial or trial period expired.

   {
       "error": "PAYMENT_REQUIRED",  
       "error_description": "Payment required"
   }