docs: adding support for OAuth docs

Signed-off-by: Tiago Barbosa <tbarbos@hotmail.com>

docs/getting-started/backstage.md

@@ -1,7 +1,7 @@
 # Configuring Backstage
 
 !!! note
- To setup the PagerDuty plugin on Backstage you need to have an API Key and an Integration Key generated both for your account and service. If you don't have this information already you must follow the steps described in the [PagerDuty integration](/getting-started/pagerduty) section.
+ To setup the PagerDuty plugin on Backstage you need to have an API Key - or client id and client secret for OAuth to generate an access token - and an Integration Key generated both for your account and service. If you don't have this information already you must follow the steps described in the [PagerDuty integration](/getting-started/pagerduty) section.
 
 ## Installing the plugin
 
@@ -93,22 +93,6 @@ annotations:
 
  1. The service id can be found by navigating to a Service with PagerDuty console and pulling the ID value out of the URL (e.g. https://[YOUR-ACCOUNT].pagerduty.com/service-directory/[SERVICE-ID]).
 
-### Configure API Authorization
-
-The PagerDuty plugin requires access to PagerDuty APIs and so we need to configure our Backstage app with the necessary credentials to reach the APIs.
-
-This step requires you to use the API token you generated and stored safely in previous steps. If you haven't done so follow the steps in [Generate a General Access REST API Token](/getting-started/pagerduty/#generate-a-general-access-rest-api-token).
-
-In `app-config.yaml` file add the following configuration and set the API token:
-
-```yaml
-pagerDuty:
- apiToken: ${PAGERDUTY_TOKEN}
-```
-
-!!! warning
- If you were using the plugin **before version 0.8.1** you need to configure a proxy configuration instead. That configuration is now deprecated so use this configuration instead.
-
 ## Add the backend plugin to your application
 
 If you followed the steps in *"Installing the plugin"*, the backend plugin for PagerDuty is now added to your application but in order for it to expose its capabilities to the frontend plugin you need to configure it.
@@ -144,26 +128,51 @@ async function main() {
  apiRouter.use('/pagerduty', await pagerduty(pagerdutyEnv));
 ```
 
-### Configure Backend plugin API credentials
+## Configure API Authorization
+
+The PagerDuty plugin requires access to PagerDuty APIs and so we need to configure our Backstage app with the necessary credentials to reach the APIs. This step requires you to use an access token - for OAuth - or an API token. 
 
-The PagerDuty backend plugin exposes local APIs that query PagerDuty APIs without going through the Backstage proxy. Therefore it requires access to the API Token used in the previous step.
+!!! note
+ If you followed previous steps you should have this information already but if you haven't done so follow the steps in [Register an App](/getting-started/pagerduty/#register-an-application-for-scoped-oauth-recommended) to get the *client id* and *client secret* for OAuth authorization or [Generate a General Access REST API Token](/getting-started/pagerduty/#generate-a-general-access-rest-api-token) to generate a REST API Token.
 
-If you haven't done it previously, add the following to your `app-config.yaml` file.
+### Scoped OAuth (recommended)
+
+In `app-config.yaml` file add the following configuration and set your OAuth configuration:
+
+```yaml
+pagerDuty:
+ oauth:
+ clientId: ${PD_CLIENT_ID}
+ clientSecret: ${PD_CLIENT_SECRET}
+ subDomain: ${PD_ACCOUNT_SUBDOMAIN}
+ region: ${PD_ACCOUNT_REGION} // Optional. allowed values: 'us', 'eu'. 
+ // Defaults to 'us'.
+```
+
+In `app-config.yaml` file add the following configuration to set your REST API Token:
 
 ```yaml
 pagerDuty:
- apiToken: ${PAGERDUTY_TOKEN}
+ apiToken: ${PAGERDUTY_TOKEN} 
 ```
 
 !!! warning
- If you were using the plugin **before version 0.3.1** you need to configure a proxy configuration instead. That configuration is now deprecated so use this configuration instead.
+ If you were using the plugin **before version 0.8.1** of the frontend or **version 0.3.1** of the backend you need to configure a proxy configuration instead. That configuration is now deprecated so use this configuration instead.
 
 ## Test your configuration
 
-Start your Backstage app, passing the PagerDuty API token as an environment variable:
+Start your Backstage app, passing the PagerDuty API token or OAuth parameters as a environment variables.
+
+### For Scoped OAuth
+
+```bash
+PD_CLIENT_ID='<ID>' PD_CLIENT_SECRET='<SECRET>' PD_ACCOUNT_SUBDOMAIN='<SUBDOMAIN>' PD_ACCOUNT_REGION='<REGION>' yarn dev
+```
+
+### For REST API Token
 
 ```bash
 PAGERDUTY_TOKEN='<TOKEN>' yarn dev
 ```
 
-This will proxy the request by adding an `Authorization` header with the provided token.
+This will add an `Authorization` header to all the requests made to PagerDuty REST APIS.

docs/getting-started/pagerduty.md

@@ -5,7 +5,7 @@ The **PagerDuty plugin for Backstage** requires some steps to be performed in Pa
 !!! warning
  PagerDuty plugin for Backstage relies on the [Events API v2 integration](https://developer.pagerduty.com/api-reference/YXBpOjI3NDgyNjU-pager-duty-v2-events-api) to send events to PagerDuty.
 
- To setup an integration on a PagerDuty service and generate the necessary authorizations, such as the API token, you need a **PagerDuty Admin role**. If you do not have this role, reach out to a **Global Admin** or **Account Owner** within your organization to request configuration of this plugin.
+ To setup an integration on a PagerDuty service and generate the necessary authorizations, such as the [API token](https://support.pagerduty.com/docs/api-access-keys) or [register an App](https://developer.pagerduty.com/docs/dd91fbd09a1a1-register-an-app), you need a **PagerDuty Admin role**. If you do not have this role, reach out to a **Global Admin** or **Account Owner** within your organization to request configuration of this plugin.
 
 ## Setup PagerDuty
 
@@ -16,12 +16,78 @@ The PagerDuty plugin for Backstage will in essence perform **two types of action
 
 Perform the following steps on PagerDuty before integrating the plugin in Backstage.
 
-### **Generate a General Access REST API Token**
+### **Create a service integration for Backstage**
+
+Creating a service integration in PagerDuty is the default mechanism to connect services with alerts coming from third-party tools and platforms. In order to create a service integration you can follow **three different approches**:
+
+1. **If you are adding your integration to an existing service:**
+ 1. From the top menu, select **Services**.
+ 2. Click the **name** of the service you want to add the integration to.
+ 3. Go to the **Integrations tab** and click **Add an Integration** button.
+ 4. Search for the **Backstage** integration, **select it** and click the **Add** button.
+ 5. An integration will be created and you can see the **integration key** and the **integration endpoint**.
+
+ ![backstage-service-integration](../images/create-backstage-service-integration.png)
+
+ !!! note
+ On this screen you can update the integration name to something that allows you to easily identify the Backstage instance you are connecting to.
+
+2. **If you are creating a new service for your integration:** Follow the instructions in the documentation that shows how to [create a service](https://support.pagerduty.com/docs/services-and-integrations#create-a-service) and select **Backstage** as the **Integration Type** in step 5.
+3. **If you want to automate service creation with Software Template:** Follow the steps in [Create PagerDuty service with Software Templates](/advanced/create-service-software-template).
+
+Once you complete this step you will be able to configure your services in Backstage to create incidents in PagerDuty by using the **Events API**.
+
+### Setup API Authorization
+
+To use PagerDuty REST APIs you need to have either an **API Token** or a registered Application that will give you the necessary credentials to request a temporary **access token**. Follow **just one** of the following sections as they serve the same purpose but in slightly different ways.
 
 !!! note
- **General Access Tokens** provide an API token with the **full access** to the PagerDuty Account by default. This might raise a security concern in some implementations and we are looking into alternatives that are already supported by PagerDuty APIs such as scoped API keys.
+ The **API Token** will grant access to all APIs and operations. If this is a security concern, please use **Scoped OAuth** which is now supported in all PagerDuty supported regions and allows you to specify the APIs and operations that Backstage can leverage. This improves security by limiting the given permissions assigned to the token.
+
+ **Scoped OAuth is the recommended approach.**
+
+#### Register an Application for Scoped OAuth (recommended)
+
+In order to use **Scoped OAuth** you need to register an App in PagerDuty. Follow the next steps to register an app, define the necessary permissions and capture the necessary information to generate a temporary access token.
+
+1. Log int to your PagerDuty account
+2. From the top menu, select **Integrations**.
+3. Select **App Registration** from the menu.
+4. Once in the app registration page, select **+ New App**.
+5. Provide a **name** and **description** to your app.
+6. Select the **OAuth 2.0** check-box, and click **Next**.
+
+ ![register an app](../images/app-registration.png)
+
+7. Select **Scoped OAuth** as the preferred Authorization mechanism.
+ ![scoped-oauth-checkbox](../images/scoped-oauth-authorization.png)
+8. On permission scope we recommend you to select the following permissions to ensure that the plugin works as expected. Once you select them click on **Register App*.
+
+ ```typescript
+ abilities.read // used in scaffolder only
+ change_events.read
+ escalation_policies.read
+ incidents.read
+ oncalls.read
+ schedules.read
+ services.read
+ services.write // used in scaffolder only
+ teams.read
+ users.read
+ vendors.read // used in scaffolder only
+ ```
+
+ !!! warning
+ You don't have to assign all the above permissions to your application but not doing so might prevent the plugin from running as expected and you might see some errors on the PagerDuty card.
+
+9. Copy the **Client ID** and **Client Secret** and store them somewhere safe. We will use them later when configuring Backstage.
+
+If you were successful in following the above steps you are ready to move to the [Backstage configuration](/getting-started/backstage).
 
- You can choose to create API tokens with **read-only access** by following the action mentioned on step 4.
+#### Generate a General Access REST API Token
+
+!!! note
+ **General Access Tokens** provide an API token with the **full access** to the PagerDuty Account by default. Still, you can choose to create API tokens with **read-only access** by following the action mentioned on step 4.
 
 To create an API Key to use with Backstage you:
 
@@ -40,25 +106,4 @@ To create an API Key to use with Backstage you:
 5. Click **Create Key**
 6. **Copy the key** and **store it** somewhere safe as we will need it later
 
-Now that you have an API Key to query PagerDuty services information the next step is to enable PagerDuty services to ingest alert data from Backstage.
-
-### **Create a service integration for Backstage**
-
-Creating a service integration in PagerDuty is the default mechanism to connect services with alerts coming from third-party tools and platforms. In order to create a service integration you can follow **three different approches**:
-
-1. **If you are adding your integration to an existing service:**
- 1. From the top menu, select **Services**.
- 2. Click the **name** of the service you want to add the integration to.
- 3. Go to the **Integrations tab** and click **Add an Integration** button.
- 4. Search for the **Backstage** integration, **select it** and click the **Add** button.
- 5. An integration will be created and you can see the **integration key** and the **integration endpoint**.
-
- ![backstage-service-integration](../images/create-backstage-service-integration.png)
-
- !!! note
- On this screen you can update the integration name to something that allows you to easily identify the Backstage instance you are connecting to.
-
-2. **If you are creating a new service for your integration:** Follow the instructions in the documentation that shows how to [create a service](https://support.pagerduty.com/docs/services-and-integrations#create-a-service) and select **Backstage** as the **Integration Type** in step 5.
-3. **If you want to automate service creation with Software Template:** Follow the steps in [Create PagerDuty service with Software Templates](/advanced/create-service-software-template).
-
 If you were successful in following the above steps you are ready to move to the [Backstage configuration](/getting-started/backstage).

docs/index.md

@@ -55,6 +55,7 @@ The scope for the plugin is quite limited at the time but we are working on brin
 We are working on some cool new features and capabilities. Here are some of them:
 
 - [x] Create scaffolder action to allow services to be created in PagerDuty
+- [x] Adding support for [Scoped OAuth](https://developer.pagerduty.com/docs/f59fdbd94ceab-o-auth-functionality)
 - [ ] Improving UI for the existing PagerDuty Card
 - [ ] Adding support for adding multiple services on the same card
 - [ ] Adding support for a Team PagerDuty card

docs/release-notes/backend.md

@@ -1,5 +1,32 @@
 # Release notes for Backend plugin
 
+## > 0.4.0
+
+[GitHub release](https://github.com/PagerDuty/backstage-plugin-backend/releases/tag/0.4.0)
+
+### Summary
+
+Release **0.4.0** introduces a minor change that adds a new option configuration field `oauth`. This new configuration improves security when calling PagerDuty REST APIs by replacing the current `apiToken` configuration that assigns full-access privileges to Backstage. 
+
+With **Scoped OAuth** support the PagerDuty admin can grant only the necessary permissions to Backstage instead of access to all APIs and operations.
+
+The new configuration can be defined in `app-config.yaml` with the following parameters:
+
+```yaml
+pagerDuty:
+ oauth:
+ clientId: ${PD_CLIENT_ID}
+ clientSecret: ${PD_CLIENT_SECRET}
+ subDomain: ${PD_ACCOUNT_SUBDOMAIN}
+ region: ${PD_ACCOUNT_REGION} // Optional. allowed values: 'us', 'eu'. Defaults to 'us'.
+```
+
+### Changes
+
+- feat: add OAuth support
+- build(deps): Bump @backstage/backend-app-api from 0.5.8 to 0.5.10
+- docs: updated readme with new features - REST APIs
+
 ## > 0.3.3
 
 [GitHub release](https://github.com/PagerDuty/backstage-plugin-backend/releases/tag/0.3.3)

docs/release-notes/common.md

@@ -1,5 +1,26 @@
 # Release notes for Frontend plugin
 
+## > 0.1.0
+
+[GitHub release](https://github.com/PagerDuty/backstage-plugin-common/releases/tag/0.1.0)
+
+### Summary
+
+Release **0.1.0** adds the type necessary for OAuth support in Backstage plugin configuration. With this new type users will be able to configure the following OAuth parameters in Backstage `app-config.yaml` file.
+
+```yaml
+pagerDuty:
+ oauth:
+ clientId: ${PD_CLIENT_ID}
+ clientSecret: ${PD_CLIENT_SECRET}
+ subDomain: ${PD_ACCOUNT_SUBDOMAIN}
+ region: ${PD_ACCOUNT_REGION} // Optional. allowed values: 'us', 'eu'. Defaults to 'us'.
+```
+
+### Changes
+
+- feat: adds type to allow OAuth support
+
 ## > 0.0.2
 
 [GitHub release](https://github.com/PagerDuty/backstage-plugin-common/releases/tag/0.0.2)

docs/release-notes/frontend.md

@@ -1,5 +1,29 @@
 # Release notes for Frontend plugin
 
+## > 0.9.0
+
+[GitHub release](https://github.com/PagerDuty/backstage-plugin/releases/tag/0.9.0)
+
+### Summary
+
+This release adds the type necessary for OAuth support in Backstage plugin configuration. Users can now configure the following OAuth parameters in Backstage `app-config.yaml` file.
+
+```yaml
+pagerDuty:
+ oauth:
+ clientId: ${PD_CLIENT_ID}
+ clientSecret: ${PD_CLIENT_SECRET}
+ subDomain: ${PD_ACCOUNT_SUBDOMAIN}
+ region: ${PD_ACCOUNT_REGION} // Optional. allowed values: 'us', 'eu'. Defaults to 'us'.
+```
+
+It also introduces more friendly error messages when permissions for certain APIs or operations are not present. This was implemented not to break the PagerDuty Card experience.
+
+### Changes
+
+- feat: add suport for Scope OAuth
+- fix: update error links to PagerDuty docs
+
 ## > 0.8.3
 
 [GitHub release](https://github.com/PagerDuty/backstage-plugin/releases/tag/0.8.3)

overrides/main.html

@@ -3,7 +3,7 @@
 {% block announce %}
 <div>
  <p>
- <strong>🎉 New release!</strong> <span style="margin-left: 20px;"> Checkout the latest versions for Frontend(<a href="/release-notes/frontend/#083">0.8.3</a>), Backend(<a href="/release-notes/backend/#033">0.3.3</a>) and Common(<a href="/release-notes/common/#002">0.0.2</a>) </span>
+ <strong>🎉 New release!</strong> <span style="margin-left: 20px;"> Checkout the latest versions for Frontend(<a href="/release-notes/frontend/#090">0.9.0</a>), Backend(<a href="/release-notes/backend/#040">0.4.0</a>) and Common(<a href="/release-notes/common/#010">0.1.0</a>) </span>
  </p>
 </div>
 {% endblock %}