Doc: Adding Note for JWT_PRINCIPAL_CLAIMS Order (#17369)

Co-authored-by: Prajwal Pandit <prajwalpandit@Prajwals-MacBook-Air.local>

openmetadata-docs/content/v1.4.x/deployment/security/azure/bare-metal.md

@@ -24,6 +24,12 @@ 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.
 
+{% note %}
+
+Altering the order of claims in `jwtPrincipalClaims` may lead to problems when matching a user from a token with an existing user in the system. The mapping process relies on the specific order of claims, so changing it can result in inconsistencies or authentication failures, as the system cannot ensure correct user mapping with a new claim order.
+
+{% /note %}
+
 ```yaml
 authorizerConfiguration:
   className: "org.openmetadata.service.security.DefaultAuthorizer"

openmetadata-docs/content/v1.4.x/deployment/security/azure/docker.md

@@ -28,6 +28,12 @@ AUTHENTICATION_CLIENT_ID={Client ID} # Update with your Client ID of Azure Appli
 AUTHENTICATION_CALLBACK_URL=http://localhost:8585/callback
 ```
 
+{% note %}
+
+Altering the order of claims in `jwtPrincipalClaims` may lead to problems when matching a user from a token with an existing user in the system. The mapping process relies on the specific order of claims, so changing it can result in inconsistencies or authentication failures, as the system cannot ensure correct user mapping with a new claim order.
+
+{% /note %}
+
 ## 2. Start Docker
 
 ```commandline

openmetadata-docs/content/v1.4.x/deployment/security/azure/index.md

@@ -44,6 +44,21 @@ Admin permissions are required to register the application on the Azure portal.
 - Provide a redirect URL as a `Single Page Application`.
 - Click on `Register`.
 
+{% note %}
+
+- **SPA (Single Page Application):**  
+  This type is designed for implicit flows. In this case, providing both the client ID and client secret will result in a failure because the implicit flow only requires the client ID for authentication.
+
+- **Web:**  
+  This type is intended for confidential clients. If you select this option, you must provide both the client ID and client secret. Simply passing the client ID will cause the authorization process to fail, as the Authorization Code flow requires both credentials for successful authentication.
+
+### Recommendation:
+
+- Use the **Web** type for confidential clients that require both a client ID and secret.
+- Use the **SPA** type for applications using implicit flows where only a client ID is needed.
+
+{% /note %}
+
 {% image src="/images/v1.4/deployment/security/azure/create-app-3.png" alt="create-app" /%}
 
 ### Step 3: Where to Find the Credentials

openmetadata-docs/content/v1.4.x/deployment/security/azure/kubernetes.md

@@ -31,4 +31,10 @@ openmetadata:
       callbackUrl: "http://localhost:8585/callback"
 ```
 
+{% note %}
+
+Altering the order of claims in `jwtPrincipalClaims` may lead to problems when matching a user from a token with an existing user in the system. The mapping process relies on the specific order of claims, so changing it can result in inconsistencies or authentication failures, as the system cannot ensure correct user mapping with a new claim order.
+
+{% /note %}
+
 {% partial file="/v1.4/deployment/configure-ingestion.md" /%}

openmetadata-docs/content/v1.4.x/deployment/security/keycloak/bare-metal.md

@@ -30,6 +30,12 @@ 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.
 
+{% note %}
+
+Altering the order of claims in `jwtPrincipalClaims` may lead to problems when matching a user from a token with an existing user in the system. The mapping process relies on the specific order of claims, so changing it can result in inconsistencies or authentication failures, as the system cannot ensure correct user mapping with a new claim order.
+
+{% /note %}
+
 ```yaml
 authorizerConfiguration:
   className: "org.openmetadata.service.security.DefaultAuthorizer"

openmetadata-docs/content/v1.4.x/deployment/security/keycloak/docker.md

@@ -29,6 +29,12 @@ AUTHENTICATION_CLIENT_ID=open-metadata # Update with your Client ID
 AUTHENTICATION_CALLBACK_URL=http://localhost:8585/callback
 ```
 
+{% note %}
+
+Altering the order of claims in `jwtPrincipalClaims` may lead to problems when matching a user from a token with an existing user in the system. The mapping process relies on the specific order of claims, so changing it can result in inconsistencies or authentication failures, as the system cannot ensure correct user mapping with a new claim order.
+
+{% /note %}
+
 ## 2. Start Docker
 
 ```commandline

openmetadata-docs/content/v1.4.x/deployment/security/keycloak/kubernetes.md

@@ -31,4 +31,10 @@ openmetadata:
       callbackUrl: "http://localhost:8585/callback"
 ```
 
+{% note %}
+
+Altering the order of claims in `jwtPrincipalClaims` may lead to problems when matching a user from a token with an existing user in the system. The mapping process relies on the specific order of claims, so changing it can result in inconsistencies or authentication failures, as the system cannot ensure correct user mapping with a new claim order.
+
+{% /note %}
+
 {% partial file="/v1.4/deployment/configure-ingestion.md" /%}

openmetadata-docs/content/v1.5.x-SNAPSHOT/deployment/security/azure/bare-metal.md

@@ -24,6 +24,12 @@ 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.
 
+{% note %}
+
+Altering the order of claims in `jwtPrincipalClaims` may lead to problems when matching a user from a token with an existing user in the system. The mapping process relies on the specific order of claims, so changing it can result in inconsistencies or authentication failures, as the system cannot ensure correct user mapping with a new claim order.
+
+{% /note %}
+
 ```yaml
 authorizerConfiguration:
   className: "org.openmetadata.service.security.DefaultAuthorizer"

openmetadata-docs/content/v1.5.x-SNAPSHOT/deployment/security/azure/docker.md

@@ -28,6 +28,12 @@ AUTHENTICATION_CLIENT_ID={Client ID} # Update with your Client ID of Azure Appli
 AUTHENTICATION_CALLBACK_URL=http://localhost:8585/callback
 ```
 
+{% note %}
+
+Altering the order of claims in `jwtPrincipalClaims` may lead to problems when matching a user from a token with an existing user in the system. The mapping process relies on the specific order of claims, so changing it can result in inconsistencies or authentication failures, as the system cannot ensure correct user mapping with a new claim order.
+
+{% /note %}
+
 ## 2. Start Docker
 
 ```commandline

openmetadata-docs/content/v1.5.x-SNAPSHOT/deployment/security/azure/index.md

@@ -44,6 +44,21 @@ Admin permissions are required to register the application on the Azure portal.
 - Provide a redirect URL as a `Single Page Application`.
 - Click on `Register`.
 
+{% note %}
+
+- **SPA (Single Page Application):**  
+  This type is designed for implicit flows. In this case, providing both the client ID and client secret will result in a failure because the implicit flow only requires the client ID for authentication.
+
+- **Web:**  
+  This type is intended for confidential clients. If you select this option, you must provide both the client ID and client secret. Simply passing the client ID will cause the authorization process to fail, as the Authorization Code flow requires both credentials for successful authentication.
+
+### Recommendation:
+
+- Use the **Web** type for confidential clients that require both a client ID and secret.
+- Use the **SPA** type for applications using implicit flows where only a client ID is needed.
+
+{% /note %}
+
 {% image src="/images/v1.5/deployment/security/azure/create-app-3.png" alt="create-app" /%}
 
 ### Step 3: Where to Find the Credentials

openmetadata-docs/content/v1.5.x-SNAPSHOT/deployment/security/azure/kubernetes.md

@@ -31,4 +31,10 @@ openmetadata:
       callbackUrl: "http://localhost:8585/callback"
 ```
 
+{% note %}
+
+Altering the order of claims in `jwtPrincipalClaims` may lead to problems when matching a user from a token with an existing user in the system. The mapping process relies on the specific order of claims, so changing it can result in inconsistencies or authentication failures, as the system cannot ensure correct user mapping with a new claim order.
+
+{% /note %}
+
 {% partial file="/v1.5/deployment/configure-ingestion.md" /%}

openmetadata-docs/content/v1.5.x-SNAPSHOT/deployment/security/keycloak/bare-metal.md

@@ -30,6 +30,12 @@ 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.
 
+{% note %}
+
+Altering the order of claims in `jwtPrincipalClaims` may lead to problems when matching a user from a token with an existing user in the system. The mapping process relies on the specific order of claims, so changing it can result in inconsistencies or authentication failures, as the system cannot ensure correct user mapping with a new claim order.
+
+{% /note %}
+
 ```yaml
 authorizerConfiguration:
   className: "org.openmetadata.service.security.DefaultAuthorizer"

openmetadata-docs/content/v1.5.x-SNAPSHOT/deployment/security/keycloak/docker.md

@@ -29,6 +29,12 @@ AUTHENTICATION_CLIENT_ID=open-metadata # Update with your Client ID
 AUTHENTICATION_CALLBACK_URL=http://localhost:8585/callback
 ```
 
+{% note %}
+
+Altering the order of claims in `jwtPrincipalClaims` may lead to problems when matching a user from a token with an existing user in the system. The mapping process relies on the specific order of claims, so changing it can result in inconsistencies or authentication failures, as the system cannot ensure correct user mapping with a new claim order.
+
+{% /note %}
+
 ## 2. Start Docker
 
 ```commandline

openmetadata-docs/content/v1.5.x-SNAPSHOT/deployment/security/keycloak/kubernetes.md

@@ -31,4 +31,10 @@ openmetadata:
       callbackUrl: "http://localhost:8585/callback"
 ```
 
+{% note %}
+
+Altering the order of claims in `jwtPrincipalClaims` may lead to problems when matching a user from a token with an existing user in the system. The mapping process relies on the specific order of claims, so changing it can result in inconsistencies or authentication failures, as the system cannot ensure correct user mapping with a new claim order.
+
+{% /note %}
+
 {% partial file="/v1.5/deployment/configure-ingestion.md" /%}