Updated the note format of documents

Signed-off-by: Aditya Kumar <aditya.kumar60@infosys.com>
2024-05-21 09:22:12 +05:30
parent 2c3f493ee3
commit 67ce37af2c
12 changed files with 86 additions and 32 deletions
@@ -4,10 +4,14 @@ title: Contributing New Providers
 description: Documentation on adding new authentication providers
 ---

-> NOTE: The primary audience for this documentation are contributors to the main
-> Backstage project that want to add support for new authentication providers.
-> While you can follow it to implement your own custom providers it is much
-> more advanced than using our built-in providers.
+:::note Note
+
+The primary audience for this documentation are contributors to the main
+Backstage project that want to add support for new authentication providers.
+While you can follow it to implement your own custom providers it is much
+more advanced than using our built-in providers.
+
+:::

 ## How Does Authentication Work?

@@ -156,8 +156,12 @@ payload:
 - `sub`: the exact string "backstage-server"
 - `exp`: one hour from the time it was generated, in epoch seconds

-> NOTE: The JWT must encode the `alg` header as a protected header, such as with
-> [setProtectedHeader](https://github.com/panva/jose/blob/main/docs/classes/jwt_sign.SignJWT.md#setprotectedheader).
+:::note Note
+
+The JWT must encode the `alg` header as a protected header, such as with
+[setProtectedHeader](https://github.com/panva/jose/blob/main/docs/classes/jwt_sign.SignJWT.md#setprotectedheader).
+
+:::

 The caller then passes along the JWT token with requests in the `Authorization`
 header:
@@ -68,11 +68,15 @@ integrations:

 If you do not specify the `organizations` field the credential will be used for all organizations for which no other credential is configured.

-> Note: An Azure DevOps provider is added automatically at startup for
-> convenience, so you only need to list it if you want to supply a
-> [personalAccessToken](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate),
-> a [service principal](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/service-principal-managed-identity),
-> or a [managed identity](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/service-principal-managed-identity)
+:::note Note
+
+An Azure DevOps provider is added automatically at startup for
+convenience, so you only need to list it if you want to supply a
+[personalAccessToken](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate),
+a [service principal](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/service-principal-managed-identity),
+or a [managed identity](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/service-principal-managed-identity)
+
+:::

 The configuration is a structure with these elements:

@@ -86,9 +90,11 @@ The `credentials` element is a structure with these elements:
 - `tenantId`: The tenant ID of the service principal (required for service principal)
 - `personalAccessToken`: The personal access token (required for personal access token)

-> Note:
->
-> - You cannot use a service principal or managed identity for Azure DevOps Server (on-premises) organizations
-> - You can only use a service principal or managed identity for Microsoft Entra ID (formerly Azure Active Directory) backed Azure DevOps organizations
-> - You can only specify one credential per host without any organizations specified
-> - The personal access token should just be provided as the raw token generated by Azure DevOps using the format `raw_token` with no base64 encoding. Formatting and base64'ing is handled by dependent libraries handling the Azure DevOps API
+:::note Note
+
+- You cannot use a service principal or managed identity for Azure DevOps Server (on-premises) organizations
+- You can only use a service principal or managed identity for Microsoft Entra ID (formerly Azure Active Directory) backed Azure DevOps organizations
+- You can only specify one credential per host without any organizations specified
+- The personal access token should just be provided as the raw token generated by Azure DevOps using the format `raw_token` with no base64 encoding. Formatting and base64'ing is handled by dependent libraries handling the Azure DevOps API
+
+:::
@@ -22,10 +22,18 @@ integrations:
      appPassword: ${BITBUCKET_CLOUD_PASSWORD}
 ```

-> Note: A public Bitbucket Cloud provider is added automatically at startup for
-> convenience, so you only need to list it if you want to supply credentials.
+:::note Note

-> Note: The credential used for this is type [App Password](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/). An Atlassian Account API key will not work
+A public Bitbucket Cloud provider is added automatically at startup for
+convenience, so you only need to list it if you want to supply credentials.
+
+:::
+
+:::note Note
+
+The credential used for this is type [App Password](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/). An Atlassian Account API key will not work.
+
+:::

 Directly under the `bitbucketCloud` key is a list of provider configurations, where
 you can list the Bitbucket Cloud providers you want to fetch data from.
@@ -130,8 +130,12 @@ catalog:

 This provider supports multiple organizations via unique provider IDs.

-> **Note:** It is possible but certainly not recommended to skip the provider ID level.
-> If you do so, `default` will be used as provider ID.
+:::note Note
+
+It is possible but certainly not recommended to skip the provider ID level.
+If you do so, `default` will be used as provider ID.
+
+:::

 - **`catalogPath`** _(optional)_:
  Default: `/catalog-info.yaml`.
@@ -17,9 +17,13 @@ is a hierarchy of
 [`Group`](../../features/software-catalog/descriptor-format.md#kind-group) kind
 entities that mirror your org setup.

-> Note: This adds `User` and `Group` entities to the catalog, but does not
-> provide authentication. See the
-> [GitHub auth provider](../../auth/github/provider.md) for that.
+:::note Note
+
+This adds `User` and `Group` entities to the catalog, but does not
+provide authentication. See the
+[GitHub auth provider](../../auth/github/provider.md) for that.
+
+:::

 ## Permissions

@@ -136,7 +136,11 @@ To use the discovery provider, you'll need a GitLab integration
 [set up](locations.md) with a `token`. Then you can add a provider config per group
 to the catalog configuration.

-> > NOTE: if you are using the New Backend System, the `schedule` has to be setup in the config, as shown below.
+:::note Note
+
+If you are using the New Backend System, the `schedule` has to be setup in the config, as shown below.
+
+:::

 ```yaml title="app-config.yaml"
 catalog:
@@ -158,7 +158,11 @@ amount of data, this can take significant time and resources.
 The token used must have the `read_api` scope, and the Users and Groups fetched
 will be those visible to the account which provisioned the token.

-> > NOTE: if you are using the New Backend System, the `schedule` has to be setup in the config, as shown below.
+:::note Note
+
+If you are using the New Backend System, the `schedule` has to be setup in the config, as shown below.
+
+:::

 ```yaml
 catalog:
@@ -29,8 +29,12 @@ to `@backstage/plugin-catalog-backend-module-ldap` to your backend package.
 yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-ldap
 ```

-> Note: When configuring to use a Provider instead of a Processor you do not
-> need to add a _location_ pointing to your LDAP server
+:::note Note
+
+When configuring to use a Provider instead of a Processor you do not
+need to add a _location_ pointing to your LDAP server
+
+:::

 Update the catalog plugin initialization in your backend to add the provider and
 schedule it:
@@ -8,7 +8,11 @@ If you prefer to watch a video instead, you can start with this video introducti

 <iframe width="560" height="315" src="https://www.youtube.com/embed/EQr9tFClgG0" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

-> Note: This video was recorded in the January 2022 Contributors Session using `@backstage/create-app@0.4.14`. Some aspects of the demo may have changed in later releases.
+:::note Note
+
+This video was recorded in the January 2022 Contributors Session using `@backstage/create-app@0.4.14`. Some aspects of the demo may have changed in later releases.
+
+:::

 Backstage integrators control permissions by writing a policy. In general terms, a policy is simply an async function which receives a request to authorize a specific action for a user and (optional) resource, and returns a decision on whether to authorize that permission. Integrators can implement their own policies from scratch, or adopt reusable policies written by others.

@@ -36,7 +36,11 @@ This approach will work for simple cases, but it has a downside: it forces us to

 To avoid this situation, the permissions framework has support for filtering items in the data source itself. In this part of the tutorial, we'll describe the steps required to use that behavior.

-> Note: in order to perform authorization filtering in this way, the data source must allow filters to be logically combined with AND, OR, and NOT operators. The conditional decisions returned by the permissions framework use a [nested object](https://backstage.io/docs/reference/plugin-permission-common.permissioncriteria) to combine conditions. If you're implementing a filter API from scratch, we recommend using the same shape for ease of interoperability. If not, you'll need to implement a function which transforms the nested object into your own format.
+:::note Note
+
+In order to perform authorization filtering in this way, the data source must allow filters to be logically combined with AND, OR, and NOT operators. The conditional decisions returned by the permissions framework use a [nested object](https://backstage.io/docs/reference/plugin-permission-common.permissioncriteria) to combine conditions. If you're implementing a filter API from scratch, we recommend using the same shape for ease of interoperability. If not, you'll need to implement a function which transforms the nested object into your own format.
+
+:::

 ## Creating the read permission

@@ -8,7 +8,11 @@ In the previous sections, we learned how to protect our plugin's backend API rou

 Take, for example, the "Add" button in our todo list application. When a user clicks this button, the frontend makes a `POST` request to the `/todos` route of our backend. If a user tries to add a todo but is not authorized, they will have no way of knowing this until they perform the action and are faced with an error. This is a poor user experience. We can do better by disabling the add button.

-> Note: Placing frontend components behind authorization cannot take the place of placing your backend routes behind authorization. Authorization checks on the frontend should be used in _addition_ to the corresponding backend authorization, as an improvement to the user experience. If you do not place your backend route behind authorization, a malicious actor can still send a request to the route even if you disabled the corresponding frontend component.
+:::note Note
+
+Placing frontend components behind authorization cannot take the place of placing your backend routes behind authorization. Authorization checks on the frontend should be used in _addition_ to the corresponding backend authorization, as an improvement to the user experience. If you do not place your backend route behind authorization, a malicious actor can still send a request to the route even if you disabled the corresponding frontend component.
+
+:::

 ## Using `usePermission`