Integrations and OAuth 2.0 Clients are only available for Birdview (PSA version of Easy Projects) Team and Enterprise accounts. Please check out our Birdview pricing plans to learn more.

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 applications you use without having to, for example, manually transfer data from one application to another.

When setting up an integration between Birdview and another application, the latter will ask the users for parameters that identify this application for Birdview and grant access. OAuth Client is a tool that stores those parameters in a secure way and provides the application with a token that allows it to get access to Birdview without revealing user credentials.

OAuth 2.0 Specifications

For detailed OAuth 2.0 specifications please visit the official site.

OAuth Client Settings 

The OAuth 2.0 Client settings are found on the Integrations page (Company Settings > Integrations), OAuth 2.0 Clients tab. A new client is created automatically after clicking the creation button (). 

To access the OAUTH Clients page you need the Manage System Settings permission enabled in your role.

Every OAuth client has the following parameters:

• Client Name - a name that identifies the application. Client Name is generated automatically after clicking the creation button but can be changed by users manually.
• Client ID - it identifies an Oauth client for both Birdview and the application that attempts to get access. It is generated automatically after creation and cannot be changed.
• Client Secret - this is a secret token used by OAuth Client to authenticate an application. It is generated automatically after creation and SHOULD BE COPIED to Clipboard right away. You will not have another chance as, for security reasons, a client secret cannot be shown again after you leave the page, so copy it at once.

Copy the client secret after it is created before you leave or close the page!

Resetting Client Secrets 

Client Secret can be reset if needed, but please note that old secret will not work anymore and needs to be changed to new one. If you fail to do that, any authorized applications will lose access eventually (they use client secrets to refresh their access tokens as the tokens have a limited time of validity). After resetting a token, the user needs to copy the new one and substitute it for the previous one in the settings of an authorized application. 

To reset a client secret:

1. Click the client to be edited.
2. For the Client Secret field, click the reset button ().
3. Confirm the action.

Resetting Client Secret will not invalidate any access tokens authorized by users, but your applications need to update their secret before it will be able to refresh tokens.

Automatic Consent Grant

Automatic Consent Grant is an on/off option. If it is off, the users will need to allow an application to get access to their Birdview resources. The Client Name parameter (see above) is used in the process, so it is important to choose a proper client name if automatic consent grant is off. 

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

Creating OAuth Clients

To create a client:

1. Click the creation button ().
2. Type a name in the Client name field.
3. Click "Add return URL" to add a return URL.
4. Client ID: Click the Clipboard icon () to copy the auto-generated Client ID.
5. Client Secret: Click the Clipboard icon () to copy the auto-generated Client Secret. See Note above.
6. If required, enable the Automatic Consent Grant option.

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.

Deleting a client will invalidate any access tokens authorized by users. They will not be able to use this application again.

Client Authorization Grants

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

Allow Client Credentials Grant Authorization

If this parameter is disabled, a 3rd party can be authorized to have access to Birdview and perform their actions on behalf of the user whose credentials were used to get the token. Only Password, Authorization Code and Refresh grants are allowed, so applications that get the token will act on behalf of the user, as if they login to the application and make these actions themselves, having limited role and permissions.

If this parameter is enabled, the application is allowed to use the Client Credentials grant. When they have a token of this type, applications take action in their own right. In Birdview, authorization clients created by users will be able to get a automatically have a scope of any user, “all users”. It means, while sending a request to OAUTH to get a token, you should provide a parameter scope with the ID of a user on behalf of who your application will act. For example:

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

It means that application will act as the user with ID = 7. You can get user ID from the URL, when you open this user’s details on Users page:

All actions in application will be done on behalf of this user. For example, if you authorize another application with a scope of Alex (user #7 as shown in the picture), and application creates a task, the task details will have a statement, “Created by Alex Burn”. Similarly, if the user’s permissions are limited—for example, Alex cannot create projects—a create project request will return an error. 

You cannot get access token of scope of a user, if he or she is inactive or can't login by status. You can get access token of scope of limited users (guests), but actions will be limited by their permissions, as explained above.