Add specific documentation for entra id

SUMMARY.md

@@ -150,8 +150,10 @@
     * [File-based](setup/security/authentication/file.md)
     * [LDAP](setup/security/authentication/ldap.md)
     * [Open ID Connect \(OIDC\)](setup/security/authentication/oidc.md)
+      * [Microsoft Entra ID](setup/security/authentication/oidc/microsoft-entra-id.md)
     * [KeyCloak](setup/security/authentication/keycloak.md)
     * [Service tokens](setup/security/authentication/service_tokens.md)
+    * [Troubleshooting](setup/security/authentication/troubleshooting.md)
   * [RBAC](setup/security/rbac/README.md)
     * [Role-based Access Control](setup/security/rbac/role_based_access_control.md)
     * [Permissions](setup/security/rbac/rbac_permissions.md)

setup/security/authentication/oidc.md

@@ -12,9 +12,9 @@ SUSE Observability can authenticate using an OIDC authentication provider. To en
 
 Before you can configure SUSE Observability to authenticate using OIDC, you need to create a client for SUSE Observability on your OIDC provider. Use the following settings for the client \(if needed by the OIDC provider\):
 
-* Use the OIDCAuthoirzation Flow
-* Set the **Redirect URI** to the base URL of SUSE Observability suffixed with `/loginCallback`. For example `https://stackstate.acme.com/loginCallback`. For some OIDC providers, such as Google, the Redirect URI must match exactly, including any query parameters. In that case, you should configure the URI like this `https://stackstate.acme.com/loginCallback?client_name=StsOidcClient`.
-* Give SUSE Observability access to at least the scopes `openid` and `email` or the equivalent of these for your OIDC provider.
+* Use the OIDC Authorization Flow, it is also often called the Authorization code flow. SUSE Observability does not support the Implicit grant and hybrid flows, so there is no need to enable support for them.
+* Set the **Redirect URI** to the base URL of SUSE Observability suffixed with `/loginCallback`. For example `https://stackstate.acme.com/loginCallback`. For some OIDC providers, such as Google and Azure Entra ID, the Redirect URI must match exactly, including any query parameters. In that case, you should configure the URI like this `https://stackstate.acme.com/loginCallback?client_name=StsOidcClient`.
+* Give SUSE Observability access to at least the scopes `openid` and `email` or the equivalent of these for your OIDC provider. Depending on the provider more scopes may be required, if a separate `profile` exists include it as well.
 * SUSE Observability needs OIDC offline access. For some identity providers, this requires an extra scope, usually called `offline_access`.
 
 The result of this configuration should produce a **clientId** and a **secret**. Copy those and keep them around for configuring SUSE Observability. Also write down the **discoveryUri** of the provider. Usually this is either in the same screen or can be found in the documentation.
@@ -43,10 +43,10 @@ stackstate:
     # map the groups from OIDC provider
     # to the 4 standard roles in SUSE Observability (guest, powerUser, k8sTroubleshooter and admin)
     roles:
-      guest: ["oidc-guest-role-for-stackstate"]
-      powerUser: ["oidc-power-user-role-for-stackstate"]
-      admin: ["oidc-admin-role-for-stackstate"]
-      k8sTroubleshooter: ["oidc-troubleshooter-role-for-stackstate"]
+      guest: ["guest-group-in-oidc-provider"]
+      powerUser: ["powerUser-group-in-oidc-provider"]
+      admin: ["admin-group-in-oidc-provider"]
+      k8sTroubleshooter: ["troubleshooter-group-in-oidc-provider"]
 ```
 
 Follow the steps below to configure SUSE Observability to authenticate using OIDC:
@@ -84,29 +84,12 @@ Follow the steps below to configure SUSE Observability to authenticate using OID
 * The authentication configuration is stored as a Kubernetes secret.
 {% endhint %}
 
-## Additional settings for specific OIDC providers
+## Example setups
 
-This section includes additional settings needed for specific OIDC providers.
+Example setups for:
+* [Microsoft Entra ID](./oidc/azure-entra-id.md)
 
-### Microsoft Identity Platform
-
-To authenticate SUSE Observability via OIDC with the Microsoft Identity Platform, the additional scope `offline_access` needs to be granted and requested during authentication.
-
-In Microsoft Azure, approve the permission _"Maintain access to data you have given it access to"_ on the consent page of the authorization code flow.
-
-In the SUSE Observability configuration described above, add the scope `offline_access`, in addition to `openid` and `email`. For example:
-
-```yaml
-jwsAlgorithm: RS256
-      scope: ["openid", "email", "offline_access"]
-      jwtClaims:
-        usernameField: preferred_username
-        groupsField: groups
-```
-
-For further details, see [Permissions and consent in the Microsoft identity platform \(learn.microsoft.com\)](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-permissions-and-consent).
-
-### Using an external secret
+## Using an external secret
 
 When the oidc secrets should come from an external secret, follow [these steps](/setup/security/external-secrets.md#getting-authentication-data-from-an-external-secret) but fill in the following data:
 
@@ -122,6 +105,7 @@ data:
 
 ## See also
 
+* [Troubleshooting authentication and authorization](troubleshooting.md)
 * [Authentication options](authentication_options.md)
 * [Permissions for predefined SUSE Observability roles](../rbac/rbac_permissions.md#predefined-roles)
 * [Create RBAC roles](../rbac/rbac_roles.md)

setup/security/authentication/oidc/microsoft-entra-id.md

@@ -0,0 +1,56 @@
+---
+description: SUSE Observability Self-hosted
+---
+
+# Microsoft Entra ID
+
+## Creating an application in Entra ID
+
+1. Register an application in Entra ID by following [this guide](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app?tabs=client-secret)
+   1. As a display name you can use, for example, `SUSE Observability`
+   2. Select the `Web` platform and specify the redirect URL: `https://<your-stackstate-installation>/loginCallback?client_name=StsOidcClient`
+   3. When adding credentials use the `client secret` credentials and make sure to store the secret
+2. The other sections in the `Prepare for development` section are not required but for a production installation you should follow them to set an owner and possible pre-approve certain scopes (see the next section for the scopes SUSE Observability will request)
+3. Finally make sure SUSE Observability will receive the groups for a user (needed for authorization) by adding the groups claim to the app registration using [this guide](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims?tabs=appui#configure-groups-optional-claims). Select which types of groups you want to expose, the rest of this document assumes you didn't customize the token properties and SUSE Observability receives the Group Id.
+
+## Configuring SUSE Observability
+
+Using the app registration information create a new `authentication.yaml` file for SUSE Observability:
+```
+stackstate:
+  authentication:
+    oidc:
+      # The client id is in the list of essentials on the overview page of the App registration
+      clientId: "<Application (client) ID>"
+      secret: "<Application (client) secret>"
+      # The Directory (Tenant) ID is in the list of essentials on the overview page of the App registration
+      discoveryUri: "https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0/.well-known/openid-configuration"
+      jwsAlgorithm: RS256
+      scope: ["openid", "email", "profile", "offline_access"]
+      jwtClaims:
+        usernameField: "email"
+        groupsField: groups
+    roles:
+      guest: []
+      powerUser: []
+      admin: [ "aaaaaaaa-bbbb-1111-2222-aabbccddeeff", "eeeeeeeeee-bbbb-1111-2222-aabbccddeeff" ]
+      k8sTroubleshooter: []
+```
+
+Get the values for:
+* Application (client) ID: in the Essentials section on the Overview page of the app registration
+* Application (client) secret: created in step 1 of the previous section and saved somewhere
+* Directory (tenant) ID: in the Essentials section on the Overview page of the app registration
+* The group ids for the different roles: in Entra ID admin browse to **Identity > All Groups**. The group id's are in the second column labeled `Object Id`. Decide which Entra ID groups should have which level of permissions and assign them to their respective roles in the above yaml example (removing the 2 example group ids).
+
+Now redeploy SUSE Observability with the helm command used to install but now include the new `authentication.yaml` file, `helm upgrade ... --values authentication.yaml`. Make sure to always include this file now when upgrading.
+
+### Used scopes
+
+SUSE Observability is configured to requests 4 scopes:
+* openid, to do authentication
+* email, to identify users
+* profile, to be able to request the user profile which contains the groups for the users
+* offline_access, to be able to keep a user logged in for a longer time without re-authentication and to allow the user to use SUSE Observabilities API tokens.
+
+For further details, see [Permissions and consent in the Microsoft identity platform \(learn.microsoft.com\)](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-permissions-and-consent).

setup/security/authentication/troubleshooting.md

@@ -0,0 +1,32 @@
+---
+description: SUSE Observability Self-hosted
+---
+
+# Troubleshooting authentication and authorization
+
+When authentication or authorization fails it usually is due to a mismatch in the configuration of the provider and SUSE Observability. To make troubelshooting easier it is possible to enable debug logging on SUSE Observability for authentication and authorization specifically.
+
+{% hint style="warning" %}
+Disable the debug logging again as soon as your are done with troubleshooting, because it is very likely debug logging contains secrets and/or personal information.
+{% endhint %}
+
+To enable debug logging copy/paste the following yaml snippet into a `debug-auth.yaml` file.
+
+```yaml
+stackstate:
+  components:
+    server:
+      additionalLogging: |
+        logger("org.pac4j.core.engine", DEBUG)
+        logger("org.pac4j.oidc.profile.creator", DEBUG)
+        logger("org.pac4j.oidc.credentials.authenticator", DEBUG)
+    api:
+      additionalLogging: |
+        logger("org.pac4j.core.engine", DEBUG)
+        logger("org.pac4j.oidc.profile.creator", DEBUG)
+        logger("org.pac4j.oidc.credentials.authenticator", DEBUG)
+```
+
+Now run the `helm upgrade` command you used before but include this one extra yaml file (so `helm upgrade .... --values debug-auth.yaml`) to enable debug logging. No pods will be restarting, the logging configuration changes will be loaded automatically after about 30 seconds.
+
+To disable the debug logging run the `helm upgrade ....` command again but omit the `--values debug-auth.yaml`. After 30 seconds the updated logging configuration is loaded and the debug logging stops.