OAuth 2.0 Protocol

Note: OAuth is an open authentication protocol that provides to third parties a method of accessing protected end user resources, without sharing third-party credentials (login and password). This protocol is very common and used by a large number of services worldwide.

OAuth module is available in Bitrix24 and is designed to ensure proper operation of apps on the basis of OAuth 2.0 protocol.

How the Protocol Works

Only apps of third kind require authentication. First-kind and second-kind applications get authenticated when connecting to the JS library, or when receiving POST-request data, when an application is started.

The OAuth 2.0 protocol permits application to obtain access to API on behalf of a specific user of a specific account. The authorization is available for both internal users and external users via the extranet.

The authorization for the server is an indication that the user has given access to the application, and the application submits its secret. The account combines all this and issues an appropriate access type to the application.

The protocol consists of two steps:

User notifies the account about his/her authorization. The application adds the identifier: client ID. In return, the server transmits to the user, and through the user to the application, the first authorization code: code.
The application submits this code back to the account (invisibly to the user), adding its secret key: client secret. Thus, the application confirms that it is the application that is “known” to the account and that such application can work with the account. In response, the account issues two parameters: access_token – parameter is required to access authorization and refresh_token – a token that is required for authorization extension.
After they are used, refresh_token and access_token, issued jointly with it, become invalid. To get access to REST API, newly received access_token shall be used; and to extend access period - a new refresh_token.

General procedure for working with OAuth when creating apps for Bitrix24 is the following:

Register your app in Bitrix24 Marketplace;
Request keys from a remote server;
The server redirects the browser to a URL, registered by the application;
Response is processed;
The obtained key is used to sign all REST API calls.

Note: Quick access to REST API can be obtained without the need to create an application. Simplified variant of REST-events, REST-commands, without creating an app is done via Webhooks.