Fix #6856: Added Troubleshooting docs for Okta SSO (#6885)

* Fix #6856: Added Troubleshooting docs for Okta SSO

* rename to service_application_client_id

ingestion/src/metadata/ingestion/ometa/auth_provider.py

@@ -246,7 +246,13 @@ class OktaAuthenticationProvider(AuthenticationProvider):
             )
             if err:
                 raise APIError(f"{err}")
-            response_dict = json.loads(res_json)
+
+            try:
+                response_dict = json.loads(res_json)
+            except ValueError:
+                raise AuthenticationException(
+                    "Could not fetch the access token please validate the orgURL & clientId in configuration"
+                )
 
             token = response_dict.get(ACCESS_TOKEN)
             if not token:

openmetadata-docs/content/deployment/security/okta/bare-metal.md

@@ -22,6 +22,7 @@ authenticationConfiguration:
 Then, 
 - Update `authorizerConfiguration` to add login names of the admin users in `adminPrincipals` section as shown below.
 - Update the `principalDomain` to your company domain name.
+- update the `botPrincipals`, add the Ingestion Client ID for the Service application. This can be found in Okta -> Applications -> Applications, Refer to Step 3 for `Creating Service Application`.
 
 ```yaml
 authorizerConfiguration:
@@ -33,6 +34,7 @@ authorizerConfiguration:
     - "user2"
   botPrincipals:
     - "ingestion-bot"
+    - "<service_application_client_id>"
   principalDomain: "open-metadata.org"
 ```
 

openmetadata-docs/content/deployment/security/okta/docker.md

@@ -12,12 +12,14 @@ To enable security for the Docker deployment, follow the next steps:
 Create an `openmetadata_okta.env` file and add the following contents as an example. Use the information
 generated when setting up the account.
 
+Note: Make sure to add the Ingestion Client ID for the Service application in `AUTHORIZER_INGESTION_PRINCIPALS`. This can be found in Okta -> Applications -> Applications, Refer to Step 3 for `Creating Service Application`.
+
 ```shell
 # OpenMetadata Server Authentication Configuration
 AUTHORIZER_CLASS_NAME=org.openmetadata.catalog.security.DefaultAuthorizer
 AUTHORIZER_REQUEST_FILTER=org.openmetadata.catalog.security.JwtFilter
 AUTHORIZER_ADMIN_PRINCIPALS=[admin]  # Your `name` from name@domain.com
-AUTHORIZER_INGESTION_PRINCIPALS=[ingestion-bot]
+AUTHORIZER_INGESTION_PRINCIPALS=[ingestion-bot, <service_application_client_id>]
 AUTHORIZER_PRINCIPAL_DOMAIN=open-metadata.org # Update with your domain
 
 AUTHENTICATION_PROVIDER=okta

openmetadata-docs/content/deployment/security/okta/index.md

@@ -38,8 +38,8 @@ This document will explain how to create an Okta app and configure it for OAuth.
     * **Refresh Token** - For the refresh token behavior, it is recommended to select the option to 'Rotate token after every use'.
     * **Implicit (hybrid)** - Select the options to allow ID Token and Access Token with implicit grant type.
   * Enter the **Sign-in redirect URIs**
-    * http://localhost:8585/signin
-    * http://localhost:8585
+    * http://localhost:8585/callback
+    * http://localhost:8585/silent-callback
   * Enter the **Sign-out redirect URIs**
   * Enter the **Base URIs**
   * Select the required option for **Controlled access**
@@ -247,3 +247,14 @@ workflowConfig:
       email: "{email}"
       scopes: []
 ```
+
+<InlineCalloutContainer>
+  <InlineCallout
+    color="violet-70"
+    icon="storage"
+    bold="Troubleshoot Okta Ingestion"
+    href="/deployment/security/okta/troubleshoot"
+  >
+    Troubleshoot the error faced with okta sso ingestion.
+  </InlineCallout>
+</InlineCalloutContainer>

openmetadata-docs/content/deployment/security/okta/kubernetes.md

@@ -10,6 +10,8 @@ Check the Helm information [here](https://artifacthub.io/packages/search?repo=op
 Once the `Client Id` and `Client Secret` are generated, see the snippet below for an example of where to
 place the client id value and update the authorizer configurations in the `values.yaml`.
 
+Note: Make sure to add the Ingestion Client ID for the Service application in `botPrincipals`. This can be found in Okta -> Applications -> Applications, Refer to Step 3 for `Creating Service Application`.
+
 ```yaml
 global:
   authorizer:
@@ -19,6 +21,7 @@ global:
       - "user1"
       - "user2"
     botPrincipals:
+      - ingestion-bot
       - "<service_application_client_id>"
     principalDomain: "open-metadata.org"
   authentication:

openmetadata-docs/content/deployment/security/okta/troubleshoot.md

@@ -0,0 +1,21 @@
+---
+title: Toubleshooting Okta SSO
+slug: /deployment/security/okta/troubleshoot
+---
+
+# Troubleshooting Okta SSO
+
+### Troubleshooting Ingesion with Okta SSO via CLI or Ariflow
+
+- **AuthenticationException**: During metadata ingestion process if you face the see the error `AuthenticationException` with message `Could not fetch the access token please validate the orgURL & clientId in configuration`, One of the possible reason for this error could be that you are passing incorrect `clientId` in the `securityConfig`, Make sure you are passing `clientId` of the Ingestion Client (i.e the service application) and not the Single Page Application. If the `clientId` provided is correct and you are still facing this error then please also validate the `orgURL`, expected value for `orgURL` field is `<ISSUER-URL>/v1/token`
+
+- **RSA key format is not supported**: If you are getting the error as `RSA key format is not supported`, this might be due to incorrect `privateKey` passed in the `securityConfig` configuration for ingestion. The `privateKey` field refers to the `public/private keypair` please refer to step 1 of `Creating Service Application`. A sample configuration for `privateKey` looks like as follows:
+```
+securityConfig:
+    clientId: <Ingestion Client ID>
+    orgURL: <Issuer URL>/v1/token
+    privateKey: '{ "p": "<value>", "kty": "RSA", "q": "<value>", "d": "<value>", "e": "AQAB", "use": "sig", "kid": "<value>", "qi": "<value>", "dp": "<value>", "alg": "RS256", "dq": "<value>", "n": "<value>" }'
+    email: <email>
+```
+
+- **User instance not found**: If you are getting an error as `user instance for <client id> not found`, this is because you might not have added Ingestion Okta Service Application clientId in principles. Please refer to the configuration for your deployment.

openmetadata-docs/content/menu.md

@@ -95,6 +95,8 @@ site_menu:
     url: /deployment/security/okta/bare-metal
   - category: Deployment / Enable Security / Okta SSO / Kubernetes
     url: /deployment/security/okta/kubernetes
+  - category: Deployment / Enable Security / Okta SSO / Troubleshoot
+    url: /deployment/security/okta/troubleshoot
   - category: Deployment / Enable Security / Amazon Cognito SSO
     url: /deployment/security/amazon-cognito
   - category: Deployment / Enable Security / Amazon Cognito SSO / Docker