[In Progress] 10.2: Integrate Cerb and Jira using OAuth2

[jstanden]

Introduction

Using automations and connected accounts in Cerb, you can integrate with the full Jira Cloud API.

Configure OAuth in Jira

Create an OAuth app

Log into the Jira developer console.

Click the blue Create button in the top right and select OAuth 2.0 integration.

Use the name Cerb integration, agree to the terms, and click the Create button.

Add permissions

In your new Jira app, open the Permissions section and click the Add button for Jira platform REST API.

Click the new Configure button for Jira platform REST API.

Add permissions for View Jira issue data and Create and manage issues.

Configure authorization

In your new Jira app, click on Authorization in the left sidebar.
Click the Configure button for OAuth 2.0 (3LO).

Use rotating refresh tokens.

Add a callback URL for https://example.com/oauth/callback where example.com is your Cerb host. In Cerb Cloud this will be something like example.cerb.me.

Credentials

Click on Settings in the left sidebar.

Copy the Client ID and Secret to use in Cerb.

Create a connected service and account in Cerb

Log into Cerb as an administrator.

Create a connected service

First we need a connected service to define the integration between Cerb and Jira. We'll use the OAuth2 credentials from Jira that we created above.

Navigate to Search > Connected Services.

Click the (+) icon in the top right of the worklist.

Select the Build tab.

Field	Value
Name:	Jira
URI:	jira
Type:	OAuth2 provider
Grant Type:	Authorization Code
Client ID:	(paste from above)
Client Secret:	(paste from above)
Authorization URL:	https://auth.atlassian.com/authorize?audience=api.atlassian.com
Token URL:	https://auth.atlassian.com/oauth/token
Resource URL:	https://api.atlassian.com/oauth/token/accessible-resources
Scope:	offline_access read:jira-user write:jira-work read:jira-work
Approval Prompt:	consent

Click the Save Changes button to create the connected service.

Create a connected account

With OAuth2, each Jira user can consent to link their own account to Cerb. However, it's common for a team to add a Cerb user to their Jira environment for automations.

In Cerb, OAuth-based connected services may have one or more connected accounts.

Navigate to Search > Connected Accounts.

Click the (+) icon in the top right of the worklist.

Select the Jira service.

Use the following details:

Field	Value
Name:	Jira (Cerb)
URI:	jira-cerb
Owner:	Cerb

Click the blue Link to Jira button to link your account.

Accept the integration.

Examples

Navigate to Search > Automations.

Click the (+) icon in the top right of the worklist to add a new automation.

Field	Value
Trigger:	automation.function

Paste the following into the Policy tab:

commands:
  http.request:
    deny/url@bool: {{inputs.url is not prefixed ('https://api.atlassian.com/')}}
    allow@bool: yes

Let's fetch the Cloud ID for your preferred site.

Paste the following automation:

start:
  http.request/fetchResources:
    output: http_response
    inputs:
      method: GET
      url: https://api.atlassian.com/oauth/token/accessible-resources
      authentication: cerb:connected_account:jira-cerb
    on_success:
      return:
        sites@json: {{http_response.body}}

In the Run tab, click the icon.

You can use the Cloud ID to access any of Jira's API endpoints.

Search projects

start:
  # See: https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-projects/#api-rest-api-2-project-search-get
  http.request/getProjects:
    output: http_response
    inputs:
      method: GET
      url: https://api.atlassian.com/ex/jira/a1b2c3-d4e5-f6a1-b2c3-d4e5f6a1b2c3/rest/api/2/project/search
      authentication: cerb:connected_account:jira-cerb
    on_success:
      return:
        projects@json: {{http_response.body}}

Search issues

start:
  # See: https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issue-search/#api-rest-api-2-search-post
  http.request/searchIssues:
    output: http_response
    inputs:
      method: POST
      url: https://api.atlassian.com/ex/jira/a1b2c3-d4e5-f6a1-b2c3-d4e5f6a1b2c3/rest/api/2/search
      authentication: cerb:connected_account:jira-cerb
      headers:
        Content-Type: application/json
      body:
        jql@text:
          project = "Cerb" AND key = "CERB-123"
    on_success:
      return:
        issues@json: {{http_response.body}}

Get issue creation metadata

start:
  # See: https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/#api-rest-api-2-issue-createmeta-get
  http.request/createIssue:
    output: http_response
    inputs:
      method: GET
      url: https://api.atlassian.com/ex/jira/a1b2c3-d4e5-f6a1-b2c3-d4e5f6a1b2c3/rest/api/2/issue/createmeta?projectKeys=CERB,DEVBLOCKS
      authentication: cerb:connected_account:jira-cerb
      headers:
        Accept: application/json
    on_success:
      return:
        issues@json: {{http_response.body}}

Create an issue

start:
  # See: https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/#api-rest-api-2-issue-post
  http.request/createIssue:
    output: http_response
    inputs:
      method: POST
      url: https://api.atlassian.com/ex/jira/a1b2c3-d4e5-f6a1-b2c3-d4e5f6a1b2c3/rest/api/2/issue
      authentication: cerb:connected_account:jira-cerb
      headers:
        Accept: application/json
        Content-Type: application/json
      body:
        fields:
          summary: Testing issue creation from Cerb
          description@text:
            This is a description.
          project:
            key: CERB
          issuetype:
            id: 10001
    on_success:
      return:
        issues@json: {{http_response.body}}