keycloak · ben95cd · Aug 26, 2022 · stianst · Jul 22, 2024 · stianst
@@ -69,6 +69,8 @@ public enum Feature {
 
         TOKEN_EXCHANGE("Token Exchange Service", Type.PREVIEW),
 
+        ASSERTION_GRANT("AssertionGrantService",Type.PREVIEW),
+
         WEB_AUTHN("W3C Web Authentication (WebAuthn)", Type.DEFAULT),
 
         CLIENT_POLICIES("Client configuration policies", Type.DEFAULT),

@@ -136,6 +136,10 @@ public interface OAuth2Constants {
 
     String UMA_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:uma-ticket";
 
+    // https://datatracker.ietf.org/doc/html/draft-ietf-oauth-jwt-bearer
+    String JWT_BEARER_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:jwt-bearer";
+    String ASSERTION = "assertion";
+
     // https://tools.ietf.org/html/draft-ietf-oauth-device-flow-15#section-3.4
     String DEVICE_CODE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
     String DEVICE_CODE = "device_code";

@@ -164,6 +164,36 @@ public boolean test(JsonWebToken t) throws VerificationException {
         }
     };
 
+    /**
+     * Verify the 'iss' claim in OIDC tokens
+     */
+    public static class IssuerCheck implements Predicate<JsonWebToken> {
+
+        private final String expectedIssuer;
+
+        public IssuerCheck(String expectedIssuer) {
+            this.expectedIssuer = expectedIssuer;
+        }
+
+        @Override
+        public boolean test(JsonWebToken t) throws VerificationException {
+            if (expectedIssuer == null) {
+                throw new VerificationException("Missing expectedIssuer");
+            }
+
+            String issuer = t.getIssuer();
+            if (issuer == null) {
+                throw new VerificationException("No issuer in the token");
+            }
+
+            if (issuer.equals(expectedIssuer)) {
+                return true;
+            }
+
+            throw new VerificationException("Expected issuer not available in the token");
+        }
+    };
+
 
     public static class IssuedForCheck implements Predicate<JsonWebToken> {
 

@@ -15,4 +15,5 @@ include::login-settings/forgot-password.adoc[leveloffset=2]
 include::login-settings/remember-me.adoc[leveloffset=2]
 include::login-settings/acr-to-loa-mapping.adoc[leveloffset=2]
 include::login-settings/update-email-workflow.adoc[leveloffset=2]
-include::realms/keys.adoc[]
+include::realms/keys.adoc[]
+include::realms/cross-domain-trust.adoc[]
@@ -182,3 +182,20 @@ really requires level 2, the client is encouraged to check the presence of the `
 image:images/client-oidc-map-acr-to-loa.png[alt="ACR to LoA mapping"]
 
 For further details see  <<_step-up-flow,Step-up Authentication>> and  https://openid.net/specs/openid-connect-core-1_0.html#acrSemantics[the official OIDC specification].
+
+[[_assertion_grant_configuration]]
+*JWT Bearer Authorization Grant Configuration*
+
+In the advanced settings of a client, you can define a set of cross-domain trusts for the assertion grant protocol. This configuration is used when a client submits an
+assertion to the OIDC token endpoint with  _grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer_ (see the <<_assertion_grant,JWTs as Authorization Grants>> chapter for more information).
+
+[NOTE]
+====
+Cross-domain trusts are configured at the realm level. See the <<cross_domain_trust,Configuring Cross-Domain Trusts>> chapter for more information.
+====
+
+When verifying an assertion, Keycloak will iterate through each cross-domain trust configured on the client and attempt to verify the assertion signature against it. If valid, Keycloak will then
+verify that the _iss_ and _aud_ claim in the assertion match the issuer and audience of the cross-domain trust. If the assertion is valid, Keycloak will generate an access token for the user specified
+in the _sub_ claim of the assertion and return it to the client.
+
+image:images/assertion-grant-config.png[alt="Assertion Grant Configuration"]
@@ -0,0 +1,21 @@
+[[cross_domain_trust]]
+=== Configuring Cross-Domain Trusts
+
+Cross-domain trusts can be defined at the realm level to specify trusted security domains external to Keycloak. This set of trusted
+domains is used by other features, such as the <<_assertion_grant,JWTs as Authorization Grants>> feature which allows external entities
+to request access tokens for users.
+
+To configure a trusted domain:
+
+. Go to `Realm settings`
+. Select the `Cross-Domain Trust` tab
+. Create a trusted domain entry
+. Save the changes
+
+Each cross-domain trust configuration contains 3 elements:
+
+* Issuer: The URI identifying this trusted domain. This value will be used to verify the issuer on assertions signed by this trusted domain.
+* Audience: The URI identifying the audience of assertions submitted by this trusted domain. This value will be used to verify the audience on assertions signed by this trusted domain.
+* Certificate: The base64 encoded X509 signing certificate of the trusted domain. This will be used to verify assertions signed by this trusted domain.
+
+image:images/cross-domain-trust-table.png[alt="Cross-Domain Trust Configuration Table"]
@@ -101,6 +101,23 @@ This is used by clients running on internet-connected devices that have limited
 . The application provides the user with the user code and the verification URI. The user accesses a verification URI to be authenticated by using another browser. You could define a short verification_uri that will be redirected to {project_name} verification URI (/realms/realm_name/device)outside {project_name} - fe in a proxy.
 . The application repeatedly polls {project_name} to find out if the user completed the user authorization. If user authentication is complete, the application exchanges the device code for an _identity_, _access_ and _refresh_ token.
 
+[[_assertion_grant]]
+===== JWTs as Authorization Grants
+
+The JWTs as authorization grants flow described in https://www.rfc-editor.org/rfc/rfc7523#section-2.1[RFC 7523 Section 2.1] enables trusted entities to authenticate users by submitting a signed JWT to the OIDC token endpoint.
+
+The protocol works as follows:
+
+. A trusted entity generates a JWT, specifying the username of the user in the _sub_ claim of the JWT
+. The trusted entity signs the JWT with the private key assocated with a pre-registered certificate (see the <<_assertion_grant_configuration,Assertion Grant Trusted Issuer Configuration>> chapter for configuring trusted certificates)
+. The trusted entity submits the JWT to the oidc _token_ endpoint with _grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer_
+. Keycloak validates the submitted assertion against cross-domain trusts in the client configuration
+. If the assertion is valid, Keycloak creates an authentication session for the requested user and returns the generated OIDC tokens
+
+To perform assertion grant requests, the client submitting the assertion grant request must be authorized to impersonate users.
+
+For details on fine grain permissions and the _impersonate_ role, see the <<full-list-of-permissions,Fine grain admin permissions>> chapter.
+
 [[_client_initiated_backchannel_authentication_grant]]
 ===== Client initiated backchannel authentication grant
 

@@ -3139,6 +3139,25 @@ parRequestUriLifespanHelp=Number that represents the lifetime of the request URI
 identityBrokeringLink=Identity brokering link
 searchClientRegistration=Search for policy
 importFileHelp=File to import a key
+oidcClientJWTBearerEnabled=JWT Bearer Authorization Grant
+oidcClientJWTBearerEnabledHelp=This enables the 'jwt-bearer' grant type as described in RFC 7523
+oidcClientJWTBearerConfigTitle=JWT Bearer Authorization Grant Configuration
+oidcClientJWTBearerConfigHelp=This section is used to configure cross-tenant trust configurations for this client. These trusted issuers will be used to verify assertions sent by this client in 'jwt-bearer' token requests.
+oidcClientJWTBearerCrossDomainTitle=Cross-Domain Trusts
+oidcClientJWTBearerCrossDomainHelp=Keycloak will use the selected cross-domain trusts to verify assertions sent to the token endpoint by this client.
+crossDomainTrustTab=Cross-Domain Trust
+crossDomainTrustConfigDropdownTitle=Trusted Domains
+crossDomainTrustConfigIssuer=Issuer
+crossDomainTrustConfigIssuerHelp=The URI identifying this trusted domain. This value will be used to verify the issuer on assertions signed by this trusted domain.
+crossDomainTrustConfigAudience=Audience
+crossDomainTrustConfigAudienceHelp=The URI identifying the audience of assertions submitted by this trusted domain. This value will be used to verify the audience on assertions signed by this trusted domain.
+crossDomainTrustConfigCert=Certificate
+crossDomainTrustConfigCertHelp=The base64 encoded X509 signing certificate of the trusted domain. This will be used to verify assertions sent by this trusted domain
+crossDomainTrustConfigAddTitle=Add Trusted Domain
+crossDomainTrustConfigAddFail=Failed to add trusted domain: {{error}}
+crossDomainTrustConfigDeleteTitle=Remove Trusted Domain
+crossDomainTrustConfigNoneMessage=No cross-domain trusts configured
+crossDomainTrustConfigNoneInstructions=Click below to add a new trusted domain
 logo=Logo
 avatarImage=Avatar image
 organizationsEnabled=Organizations

@@ -6,6 +6,7 @@ import { useFormContext } from "react-hook-form";
 import { useTranslation } from "react-i18next";
 import { ScrollForm } from "@keycloak/keycloak-ui-shared";
 import type { AddAlertFunction } from "../components/alert/Alerts";
+import useIsFeatureEnabled, { Feature } from "../utils/useIsFeatureEnabled";
 import { convertAttributeNameToForm, toUpperCase } from "../util";
 import type { FormFields, SaveOptions } from "./ClientDetails";
 import { AdvancedSettings } from "./advanced/AdvancedSettings";
@@ -14,6 +15,7 @@ import { ClusteringPanel } from "./advanced/ClusteringPanel";
 import { FineGrainOpenIdConnect } from "./advanced/FineGrainOpenIdConnect";
 import { FineGrainSamlEndpointConfig } from "./advanced/FineGrainSamlEndpointConfig";
 import { OpenIdConnectCompatibilityModes } from "./advanced/OpenIdConnectCompatibilityModes";
+import { AssertionGrantConfigPanel } from "./advanced/AssertionGrantConfigPanel";
 
 export const parseResult = (
   result: GlobalRequestResult,
@@ -51,6 +53,7 @@ export type AdvancedProps = {
 export const AdvancedTab = ({ save, client }: AdvancedProps) => {
   const { t } = useTranslation();
   const openIdConnect = "openid-connect";
+  const isFeatureEnabled = useIsFeatureEnabled();
 
   const { setValue } = useFormContext();
   const {
@@ -187,6 +190,21 @@ export const AdvancedTab = ({ save, client }: AdvancedProps) => {
               </>
             ),
           },
+          {
+            title: t("oidcClientJWTBearerConfigTitle"),
+            isHidden:
+              !isFeatureEnabled(Feature.AssertionGrant) ||
+              attributes?.["oidc.grants.assertion.enabled"]?.toString() !==
+                "true",
+            panel: (
+              <>
+                <Text className="pf-u-pb-lg">
+                  {t("oidcClientJWTBearerConfigHelp")}
+                </Text>
+                <AssertionGrantConfigPanel client={client} save={save} />
+              </>
+            ),
+          },
           {
             title: t("authenticationOverrides"),
             panel: (

@@ -149,6 +149,32 @@ export const CapabilityConfig = ({
                   )}
                 />
               </GridItem>
+              {isFeatureEnabled(Feature.AssertionGrant) && (
+                <GridItem lg={8} sm={6}>
+                  <Controller
+                    name={convertAttributeNameToForm<FormFields>(
+                      "attributes.oidc.grants.assertion.enabled",
+                    )}
+                    defaultValue={false}
+                    control={control}
+                    render={({ field }) => (
+                      <InputGroup>
+                        <Checkbox
+                          data-testid="oidc-assertion-grant"
+                          label={t("oidcClientJWTBearerEnabled")}
+                          id="kc-oidc-assertion-grant"
+                          isChecked={field.value.toString() === "true"}
+                          onChange={field.onChange}
+                        />
+                        <HelpItem
+                          helpText={t("oidcClientJWTBearerEnabledHelp")}
+                          fieldLabelId="oidcClientJWTBearerEnabled"
+                        />
+                      </InputGroup>
+                    )}
+                  />
+                </GridItem>
+              )}
               <GridItem lg={8} sm={6}>
                 <Controller
                   name="directAccessGrantsEnabled"

@@ -0,0 +1,44 @@
+import { useTranslation } from "react-i18next";
+import { ActionGroup, Button } from "@patternfly/react-core";
+
+import { FormAccess } from "../../components/form/FormAccess";
+import { convertAttributeNameToForm } from "../../util";
+import type { AdvancedProps } from "../AdvancedTab";
+import { CrossDomainSelect } from "../../components/cross-domain/crossDomainSelect";
+
+export const AssertionGrantConfigPanel = ({
+  save,
+  client: { access, protocol },
+}: AdvancedProps) => {
+  const { t } = useTranslation();
+
+  return (
+    <FormAccess
+      role="manage-clients"
+      fineGrainedAccess={access?.configure}
+      isHorizontal
+    >
+      {protocol === "openid-connect" && (
+        <>
+          <CrossDomainSelect
+            name={convertAttributeNameToForm(
+              "attributes.oidc.grants.assertion.config",
+            )}
+            label={t("oidcClientJWTBearerCrossDomainTitle")}
+            helpText={t("oidcClientJWTBearerCrossDomainHelp")}
+            onChange={(d) => JSON.stringify(d.map((c) => c.issuer))}
+            onLoad={(trustedDomains, data) => {
+              const loaded = JSON.parse(data || "[]");
+              return trustedDomains.filter((c) => loaded.includes(c.issuer));
+            }}
+          />
+          <ActionGroup>
+            <Button variant="secondary" onClick={() => save()}>
+              {t("save")}
+            </Button>
+          </ActionGroup>
+        </>
+      )}
+    </FormAccess>
+  );
+};