OAuth clients 2.0

Overview

OAuth 2.0 is a technology that allows a service or application to gain limited access to a user's resources in another application and be authorized to perform certain actions on their behalf. Using this technology, Birdview can integrate with third party applications.

When setting up an integration between Birdview and a third party application, an administrator specifies parameters that identify the application that Birdview grants access to. An OAuth client is a tool that securely stores these parameters and provides the application with a token that allows it to access to Birdview without revealing the user's credentials.

OAuth 2.0 specifications

Detailed specifications of OAuth 2.0 can be found on the official site.

OAuth client settings 

The OAuth 2.0 client settings are found on the Automations page (Company settings > Automations), OAuth 2.0 clients tab. A new client is created automatically after clicking the create button (). 

Every OAuth client created on the OAuth 2.0 client page has the following parameters:

• Client name - a name that identifies the application. The client name is generated automatically after you click the create button and can be manually changed later.
• Client ID - identifies the OAuth client to both Birdview and the application attempting to access Birdview. It is automatically generated upon creation and cannot be changed.
• Client secret - is a secret token used by the OAuth client to authenticate the application. It is generated automatically upon creation and MUST BE COPIED to the clipboard and written down immediately. There will be no second chance, as for security reasons the client secret cannot be shown again after you leave the page.

Resetting client secrets 

If necessary, the client secret can be reset. Note that the old secret will no longer work and must be replaced with a new one in the application. If this is not done, all authorized applications will eventually lose access (they use client secrets to refresh their access tokens, since tokens have a limited validity period). After resetting the token, the user must copy the new one and replace the previous one with it in the authorized application settings. 

To reset a client secret:

1. Click the client to open its details.
2. Click the Reset button on the right of the Client secret field ().
3. Confirm the action.

Client authorization grants

Authorization grant is a way that OAuth 2.0 uses to give the users or applications their access tokens. The OAuth framework specifies several grant types for different use cases. Refer to OAuth 2.0 documentation for more information about the grant types.

Automatic consent grant

Automatic consent grant is an on/off option. If it is turned off, users will need to allow the application to access their Birdview resources. This process uses the client name parameter (see above), so it is important to select the correct client name if automatic consent grant is turned off. 

If the option is enabled, it means that access permission is granted automatically.

Allow client credentials grant authorization

If this setting is disabled, a third party could access Birdview and perform actions on behalf of the user whose credentials were used to obtain the token. Only the Password, Authorization Code and Refresh grants are allowed, so applications that receive the token will act on behalf of the user as if they were logging into the application and performing these actions themselves, with a limited access level and permissions.

If enabled, the application is allowed to use the Client Credentials grant. Given a token of this type, applications perform actions on their own. In Birdview, user-created authorization clients will be able to automatically get the scope of any user, i.e., “all users”. This means that when sending a request to OAuth to get a token, you must specify the parameter scope with the ID of the user on whose behalf your application will act.
For example:

grant_type=client_credentials&client_id={{clientID}}&scope=user:7&client_secret={{clientSecret}}

This means that the application will act on behalf of the user with ID = 7.
The user ID can be obtained from the URL by opening that user’s details on the Users page:

All actions in the application will be performed on behalf of this user. For example, if you authorize another application with Alex's scope (user #7, as shown in the image), and the application creates a task, the task details will say “Created by Alex Burn”. Similarly, if the user’s permissions are limited, such as Alex not being able to create projects, the request to create a project will return an error. 

Creating OAuth clients

To create a client:

1. Click Add OAuth clients button.
2. Type a name in the Client name field.
3. Click "Add return URL" to add a return URL, if necessary.
4. Client ID: Click the Clipboard icon () to copy the auto-generated Client ID to the clipboard.
5. Client secret: Click the Clipboard icon () to copy the auto-generated client secret to the clipboard. See the Note above.
6. If required, turn on the other options.

Deleting OAuth clients

To delete a client:

1. Hover over the client to be deleted.
2. Click the More actions button () at the right end of the row.
3. Select Delete.
4. Confirm the action.