Merge remote-tracking branch 'upstream/master' into entra-rename

docs/auth/index.md

@@ -406,3 +406,50 @@ providerFactories: {
   ghe: providers.github.create(),
 },
 ```
+
+## Configuring token issuers
+
+By default, the Backstage authentication backend generates and manages its own signing keys automatically for any issued
+Backstage tokens. However, these keys have a short lifetime and do not persist after instance restarts.
+
+Alternatively, users can provide their own public and private key files to sign issued tokens. This is beneficial in
+scenarios where the token verification implementation aggressively caches the list of keys, and doesn't attempt to fetch
+new ones even if they encounter an unknown key id. To enable this feature add the following configuration to your config
+file:
+
+```yaml
+auth:
+  keyStore:
+    provider: 'static'
+    static:
+      keys:
+        # Must be declared at least once and the first one will be used for signing
+        - keyId: 'primary'
+          publicKeyFile: /path/to/public.key
+          privateKeyFile: /path/to/private.key
+          algorithm: # Optional, algorithm used to generate the keys, defaults to ES256
+          # More keys can be added so with future key rotations caches already know about it
+        - keyId: ...
+```
+
+The private key should be stored in the PKCS#8 format. The public key should be stored in the SPKI format.
+You can generate the public/private key pair, using openssl and the ES256 algorithm by performing the following
+steps:
+
+Generate a private key using the ES256 algorithm
+
+```sh
+openssl ecparam -name prime256v1 -genkey -out private.ec.key
+```
+
+Convert it to PKCS#8 format
+
+```sh
+openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private.ec.key -out private.key
+```
+
+Extract the public key
+
+```sh
+openssl ec -inform PEM -outform PEM -pubout -in private.key -out public.key
+```

docs/auth/microsoft/provider.md

@@ -38,13 +38,18 @@ auth:
         clientId: ${AUTH_MICROSOFT_CLIENT_ID}
         clientSecret: ${AUTH_MICROSOFT_CLIENT_SECRET}
         tenantId: ${AUTH_MICROSOFT_TENANT_ID}
+        domainHint: ${AZURE_TENANT_ID}
 ```
 
-The Microsoft provider is a structure with three configuration keys:
+The Microsoft provider is a structure with three mandatory configuration keys:
 
 - `clientId`: Application (client) ID, found on App Registration > Overview
 - `clientSecret`: Secret, found on App Registration > Certificates & secrets
 - `tenantId`: Directory (tenant) ID, found on App Registration > Overview
+- `domainHint` (optional): Typically the same as `tenantId`.
+  Leave blank if your app registration is multi tenant.
+  When specified, this reduces login friction for users with accounts in multiple tenants by automatically filtering away accounts from other tenants.
+  For more details, see [Home Realm Discovery](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/home-realm-discovery-policy)
 
 ## Outbound Network Access