RHIDP-7912: omitIdentityTokenOwnershipClaim flag

assemblies/assembly-authentication-troubleshooting.adoc

@@ -0,0 +1,9 @@
+:_mod-docs-content-type: ASSEMBLY
+
+[id="authentication-troubleshooting"]
+
+= Troubleshooting authentication issues
+
+Learn how to troubleshoot authentication issues.
+
+include::modules/authentication/proc-reducing-token-size.adoc[leveloffset=+1]

assemblies/assembly-enabling-authentication.adoc

@@ -18,3 +18,5 @@ include::assembly-enabling-authentication-with-github.adoc[leveloffset=+1]
 
 include::modules/authentication/proc-enabling-user-authentication-with-microsoft-azure-with-optional-steps.adoc[leveloffset=+1]
 
+include::assembly-authentication-troubleshooting.adoc[leveloffset=+1]
+

modules/authentication/proc-reducing-token-size.adoc

@@ -0,0 +1,43 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="reducing-token-size"]
+= Reducing the size of issued tokens
+
+By default,
+the authentication backend issues user identity tokens with ownership references of the user in the `ent` claim of the JSON Web Token (JWT) payload.
+This makes it easier for consumers of the token to resolve ownership of the user.
+However, depending on the shape of your organization and how you resolve ownership claims,
+the tokens can grow large and lead to HTTP errors that prevent you from accessing parts of {product-very-short}.
+Use the `omitIdentityTokenOwnershipClaim` flag to remove the `ent` claim from tokens and reduce their size.
+
+[IMPORTANT]
+====
+Without the `ent` claim in the token, consumers of the token must call the `/v1/userinfo` endpoint on the auth backend to fetch the ownership references of the user.
+However, there's usually no action required for the consumers.
+Clients still receive the full set of claims during authentication,
+and plugin backends that use the `UserInfoService` to access the ownership references from user credentials can call the `userinfo` endpoint if necessary.
+====
+
+.Procedure
+
+. In the `app-config.yaml` file, set `omitIdentityTokenOwnershipClaim` to `true`:
++
+[source,yaml]
+----
+auth:
+  omitIdentityTokenOwnershipClaim: true
+----
++
+[IMPORTANT]
+====
+When you enable the `omitIdentityTokenOwnershipClaim` flag, it is important that any custom sign-in resolvers directly return the result of the sign-in method.
+
+Example of a correct setup::
+
+[source,yaml,subs="+attributes"]
+----
+return ctx.issueToken({
+  claims: { sub: entityRef, ent: [entityRef] },
+});
+----
+