Merge pull request #1695 from GersonTrj/gt_update-okta-readme

updating okta readme

.changeset/cuddly-snakes-beam.md

@@ -0,0 +1,5 @@
+---
+'@roadiehq/catalog-backend-module-okta': patch
+---
+
+Update README.md

plugins/backend/catalog-backend-module-okta/README.md

@@ -3,7 +3,16 @@
 This is an extension module to the plugin-catalog-backend plugin, providing
 entity providers to read Okta Group and User objects as Backstage Entities.
 
-To setup the Okta providers you will need an [Okta API Token](https://developer.okta.com/docs/guides/create-an-api-token/main/)
+To setup the Okta providers you will need
+an [Okta API Token](https://developer.okta.com/docs/guides/create-an-api-token/main/)
+
+## Installation
+
+To install the plugin dependency in your Backstage app, from the root of your project run:
+
+```bash
+yarn --cwd packages/backend add @roadiehq/catalog-backend-module-okta
+```
 
 ## App Config
 
@@ -28,7 +37,9 @@ catalog:
 
 ### OAuth 2.0 Scoped Authentication
 
-[Create an OAuth app](https://developer.okta.com/docs/guides/implement-oauth-for-okta/main/#create-an-oauth-2-0-app-in-okta) in Okta. You will need to grant it with the `okta.groups.read` and `okta.users.read` scopes as a bare minimum. In the following example the `oauth.privateKey` may be passed as either a string encoded PEM or stringified JWK.
+[Create an OAuth app](https://developer.okta.com/docs/guides/implement-oauth-for-okta/main/#create-an-oauth-2-0-app-in-okta)
+in Okta. You will need to grant it with the `okta.groups.read` and `okta.users.read` scopes as a bare minimum. In the
+following example the `oauth.privateKey` may be passed as either a string encoded PEM or stringified JWK.
 
 ```yaml
 catalog:
@@ -52,7 +63,8 @@ Note: `keyId` is optional but _must_ be passed when using a PEM as the `privateK
 
 ### Filter Users and Groups
 
-The provider allows configuring Okta search filtering for users and groups. See here for more details on what is possible: https://developer.okta.com/docs/reference/core-okta-api/#filter
+The provider allows configuring Okta search filtering for users and groups. See here for more details on what is
+possible: https://developer.okta.com/docs/reference/core-okta-api/#filter
 
 ```yaml
 catalog:
@@ -71,34 +83,72 @@ catalog:
             minutes: 1
 ```
 
-## Adding the provider with default configuration
-
-The Okta catalog module provides default implementations of 3 entity providers that can be used with the Backstage backend system.
+## Adding the provider
 
-To integrate these into your application, you can use the following lines in your Backstage backend entry file:
+First, add the required okta-entity-provider dependency to your backend in the `packages/backend/src/index.ts` file:
 
 ```typescript
 backend.add(
   import('@roadiehq/catalog-backend-module-okta/okta-entity-provider'),
 );
+```
+
+Now, you need to add a provider factory that will define the strategy used to load users and groups. We provide three
+default
+factory that you can use out of the box, or your can create your own custom one, let's explore both options.
+
+### Default entity providers
+
+The Okta catalog module provides default implementations of 3 entity providers that can be used with the Backstage
+backend system.
+
+To integrate these into your application, add them after the okta-entity-provider, like this:
+
+```typescript
+backend.add(
+  import('@roadiehq/catalog-backend-module-okta/okta-entity-provider'), // The required entity provider
+);
 backend.add(
-  import('@roadiehq/catalog-backend-module-okta/org-provider-factory'),
+  import('@roadiehq/catalog-backend-module-okta/org-provider-factory'), // Optional - Load both users and groups
 );
 ```
 
-You need to register the `okta-entity-provider` module and one of three options for the provider factory. The provider factory decides which kind of entities are provided for you. You can either use the `OktaOrgEntityProvider` found as `org-provider-factory` which loads both users and groups. Or you can load user or groups separately user the `OktaUserEntityProvider` (`user-provider-factory`) and `OktaGroupEntityProvider` (`group-provider-factory`) providers.
+The provider factory decides which kind of entities are provided for you.
+The options are:
+
+- `org-provider-factory` - Loads both users and groups
+- `user-provider-factory` - Loads only users
+- `group-provider-factory` - Loads only groups
+
+## Custom entity provider(s)
 
-Note that this is the automatic configuration of provider factories and does not allow customization of naming strategies or other configurations.
+Instead of using the default entity providers, you can create your own custom entity provider(s) by implementing the
+`EntityProvider` interface.
 
-## Adding provider(s) with customized configuration
+You can also tailor the entity providers to handle different configurations if there is a need to add specific logic for
+example naming strategies for your entities.
 
-You can also tailor the entity providers to handle different configurations if there is a need to add specific logic for example naming strategies for your entities.
+> ⚠️ **Note:** You use either the custom entity provider\(s\) or the default ones, not both.
 
 ### Load Users and Groups Together - OktaOrgEntityProvider
 
 You can construct your own configuration of OktaOrgEntityProvider factory and register it into the backend:
 
+In a separated file of your choice, to avoid cluttering the `packages/backend/src/index.ts` file,
+you can create a new module that will contain the custom entity provider registration logic.
+
 ```typescript
+import {
+  createBackendModule,
+  coreServices,
+} from '@backstage/backend-plugin-api';
+import {
+  oktaCatalogBackendEntityProviderFactoryExtensionPoint,
+  EntityProviderFactory,
+  OktaOrgEntityProvider,
+} from '@roadiehq/catalog-backend-module-okta/new-backend';
+import { Config } from '@backstage/config';
+
 export const oktaOrgEntityProviderModule = createBackendModule({
   pluginId: 'catalog',
   moduleId: 'default-okta-org-entity-provider',
@@ -121,13 +171,19 @@ export const oktaOrgEntityProviderModule = createBackendModule({
     });
   },
 });
+```
 
-// ...snip...
+This is your custom entity provider module. You can now add it to the backend in the `packages/backend/src/index.ts`
+file:
 
+```typescript
+// We need to comment or remove the default entity provider, since now we have a custom one.
+// backend.add(import('@roadiehq/catalog-backend-module-okta/org-provider-factory'));
 backend.add(oktaOrgEntityProviderModule);
 ```
 
-You can configure the provider with different naming strategies. The configured strategy will be used to generate the discovered entity's `metadata.name` field. The currently supported strategies are the following:
+You can configure the provider with different naming strategies. The configured strategy will be used to generate the
+discovered entity's `metadata.name` field. The currently supported strategies are the following:
 
 #### User naming strategies
 
@@ -146,7 +202,9 @@ export const customUserNamingStrategy: UserNamingStrategy = user =>
 
 - id (default) | Group entities will be named by the group id.
 - kebab-case-name | Group entities will be named by their group profile name converted to kebab case.
-- profile-name | Group entities will be named exactly as their group profile name. ⚠ The Okta field supports characters not supported as [entity names in backstage](https://backstage.io/docs/features/software-catalog/descriptor-format#name-required). ⚠
+- profile-name | Group entities will be named exactly as their group profile name. ⚠ The Okta field supports characters
+  not supported
+  as [entity names in backstage](https://backstage.io/docs/features/software-catalog/descriptor-format#name-required). ⚠
 
 You may also choose to implement a custom naming strategy by providing a function.
 
@@ -176,7 +234,8 @@ const factory: EntityProviderFactory = (oktaConfig: Config) =>
 
 The module supports also custom transformers that can be configured as part of the customized registration.
 
-In case you want to customize the emitted entities, the provider allows to pass custom transformers for users and groups by providing `userTransformer` and `groupTransformer`.
+In case you want to customize the emitted entities, the provider allows to pass custom transformers for users and groups
+by providing `userTransformer` and `groupTransformer`.
 
 1. Create a transformer:
 
@@ -301,7 +360,8 @@ export const oktaUserEntityProviderModule = createBackendModule({
 backend.add(oktaUserEntityProviderModule);
 ```
 
-You can configure the provider with different naming strategies. The configured strategy will be used to generate the discovered entity's `metadata.name` field. The currently supported strategies are the following:
+You can configure the provider with different naming strategies. The configured strategy will be used to generate the
+discovered entity's `metadata.name` field. The currently supported strategies are the following:
 
 - id (default) | User entities will be named by the user id.
 - kebab-case-email | User entities will be named by their profile email converted to kebab case.
@@ -314,7 +374,8 @@ export const customUserNamingStrategy: UserNamingStrategy = user =>
   user.profile.customField;
 ```
 
-In case you want to customize the emitted entities, the provider allows to pass custom transformer by providing `userTransformer`.
+In case you want to customize the emitted entities, the provider allows to pass custom transformer by providing
+`userTransformer`.
 
 1. Create a transformer:
 
@@ -390,7 +451,8 @@ export const oktaGroupEntityProviderModule = createBackendModule({
 });
 ```
 
-You can configure the provider with different naming strategies. The configured strategy will be used to generate the discovered entities `metadata.name` field. The currently supported strategies are the following:
+You can configure the provider with different naming strategies. The configured strategy will be used to generate the
+discovered entities `metadata.name` field. The currently supported strategies are the following:
 
 User naming strategies:
 
@@ -409,7 +471,9 @@ Group naming strategies:
 
 - id (default) | Group entities will be named by the group id.
 - kebab-case-name | Group entities will be named by their group profile name converted to kebab case.
-- profile-name | Group entities will be named exactly as their group profile name. ⚠ The Okta field supports characters not supported as [entity names in backstage](https://backstage.io/docs/features/software-catalog/descriptor-format#name-required). ⚠
+- profile-name | Group entities will be named exactly as their group profile name. ⚠ The Okta field supports characters
+  not supported
+  as [entity names in backstage](https://backstage.io/docs/features/software-catalog/descriptor-format#name-required). ⚠
 
 You may also choose to implement a custom naming strategy by providing a function.
 
@@ -420,9 +484,11 @@ export const customGroupNamingStrategy: GroupNamingStrategy = group =>
 
 Make sure you use the OktaUserEntityProvider's naming strategy for the OktaGroupEntityProvider's user naming strategy.
 
-You can optionally provide the ability to create a hierarchy of groups by providing the `hierarchyConfig`. See example of OrgEntityProvider above for usage instructions.
+You can optionally provide the ability to create a hierarchy of groups by providing the `hierarchyConfig`. See example
+of OrgEntityProvider above for usage instructions.
 
-In case you want to customize the emitted entities, the provider allows to pass custom transformer by providing `groupTransformer`.
+In case you want to customize the emitted entities, the provider allows to pass custom transformer by providing
+`groupTransformer`.
 
 1. Create a transformer:
 
@@ -497,4 +563,5 @@ export const oktaGroupEntityProviderModule = createBackendModule({
 
 ---
 
-Roadie gives you a hassle-free, fully customisable SaaS Backstage. Find out more here: [https://roadie.io](https://roadie.io).
+Roadie gives you a hassle-free, fully customisable SaaS Backstage. Find out more
+here: [https://roadie.io](https://roadie.io).