8000 fix: adding defaults for boolean and several string values by shawkins · Pull Request #55168 · keycloak/keycloak · GitHub
[go: up one dir, main page]

Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions docs/documentation/upgrading/topics/changes/changes-27_0_0.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -422,6 +422,50 @@ This prevents an attacker who controls a brokered account with an unverified ema

If you use auto-link flows with a SAML or custom identity provider that does not set the `email_verified` claim, enable *Trust Email* on that identity provider to preserve the previous behavior.

=== Admin API v2 applies client defaults for null values
// https://github.com/keycloak/keycloak/issues/49038

Admin API v2 client representations now define schema defaults for `enabled` and SAML settings, resolving omitted or `null` values to those defaults on create (`POST`) and replace (`PUT`).

On partial update (`PATCH`), omitted fields keep their current values, while fields explicitly set to `null` reset to their schema defaults, except for the conditional defaults described below.
Clients that serialize only non-null fields (such as the Java admin client) must send desired values explicitly when patching.

Previously, omitted or `null` fields on create or replace disabled the setting, left the client disabled, or removed the stored attribute.

The following fields now default to `true` when omitted or `null`:

* `enabled`
* `includeAuthnStatement`
* `signDocuments`
* `clientSignatureRequired`
* `forcePostBinding`
* `frontChannelLogout`

In addition, the following SAML fields resolve to defaults when omitted or `null`:

* `signatureAlgorithm`: `RSA_SHA256`
* `signatureCanonicalizationMethod`: `http://www.w3.org/2001/10/xml-exc-c14n#`
* `forceNameIdFormat`, `signAssertions`, `allowEcpFlow`: `false`

Some defaults are conditional, and are applied only when their condition holds.
Otherwise, a `null` value leaves the field unset.

* SAML `nameIdFormat`: the default is `username`.
On create (`POST`) and replace (`PUT`) it is always applied.
On `PATCH` it is applied only if the client has a stored NameID format.
A legacy client with no stored format keeps negotiating the format with the request, and an explicit `null` preserves that.
* OIDC `auth.secret`: the default is a newly generated secret, applied only for secret-based authentication methods.
A `null` secret on `PATCH` for such a client generates a new secret, also if the client had none, such as a public client that is patched to use a secret-based method.
Setting `auth` itself to `null` makes the client public and removes its secret.

To disable a setting or create a disabled client, specify `false` explicitly.
Review existing scripts or automation that relied on omitted or `null` fields to disable settings.

Other notable behavior changes:

* For existing SAML clients with no stored values for `includeAuthnStatement`, `signDocuments`, `clientSignatureRequired`, or `forcePostBinding`, the API now returns `false` (the effective runtime value) instead of `null`.
* Client policies, such as the secure logout executor, evaluate an unset `frontChannelLogout` field as `true`.

// ------------------------ Notable changes ------------------------ //
== Notable changes

Expand Down
19 changes: 19 additions & 0 deletions docs/guides/admin-api/admin-api-v2.adoc
8000
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,25 @@ The Admin API v2 uses the same CLI tool described in the {adminguide_link}#admin

<@kc.admin parameters="--v2 config credentials --server http://localhost:8080 --realm master --user admin"/>

== Update Semantics (PUT vs PATCH)

The Admin API v2 separates full resource replacement from partial updates:

* *Replace (`PUT`)*: Replaces the entire resource configuration with the representation provided in the request body.
`PUT` does not preserve previous state for omitted fields.
Any omitted field or field set to `null` is resolved to its default schema value (or removed if it has no default).
* *Partial Update (`PATCH`)*: Modifies only the fields explicitly provided in the request body.
Omitted fields retain their current persisted values.
Setting a field with a schema default explicitly to `null` resets it to its default value, while setting optional fields without a schema or conditional default to `null` removes the stored configuration.
If a field has a conditional default, the default is applied only when its condition holds, and setting the field to `null` otherwise leaves the field unset.
The conditional defaults are:

** SAML `nameIdFormat`: the default is `username`, but on `PATCH` it is applied only if a value was previously stored.
A client without a stored value falls back to negotiating the format with the request, and `null` preserves that.
** OIDC `auth.secret`: the default is a newly generated secret, applied only when the client uses a secret-based authentication method.
Setting `auth.secret` to `null` on such a client generates a new secret, also when the client previously had none, such as when a public client is patched to use a secret-based method.
Comment on lines +74 to +75
Setting `auth` itself to `null` makes the client public and removes its secret.

== Available Resources

For details on filtering and projection, see <@links.adminapi id="querying" />.
Expand Down
14 changes: 13 additions & 1 deletion js/libs/keycloak-admin-client/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,7 @@
},
"enabled" : {
"type" : "boolean",
"default" : true,
"description" : "Whether this client is enabled"
},
"appUrl" : {
Expand Down Expand Up @@ -167,42 +168,52 @@
"properties" : {
"nameIdFormat" : {
"$ref" : "#/components/schemas/NameIdFormat",
"description" : "Name ID format to use for the subject"
"description" : "Name ID format to use for the subject. Set to username when a client is created without a value. A client without a stored format, such as one created before this setting was always populated, uses the format requested by the SAML client and is left unchanged unless a value is provided."
},
"forceNameIdFormat" : {
"type" : "boolean",
"default" : false,
"description" : "Force the specified Name ID format even if the client requests a different one"
},
"includeAuthnStatement" : {
"type" : "boolean",
"default" : true,
"description" : "Include AuthnStatement in the SAML response"
},
"signDocuments" : {
"type" : "boolean",
"default" : true,
"description" : "Sign SAML documents on the server side"
},
"signAssertions" : {
"type" : "boolean",
"default" : false,
"description" : "Sign SAML assertions"
},
"clientSignatureRequired" : {
"type" : "boolean",
"default" : true,
"description" : "Require client to sign SAML requests"
},
"forcePostBinding" : {
"type" : "boolean",
"default" : true,
"description" : "Force POST binding for SAML responses"
},
"frontChannelLogout" : {
"type" : "boolean",
"default" : true,
"description" : "Use front-channel logout (browser redirect)"
},
"signatureAlgorithm" : {
"type" : "string",
"default" : "RSA_SHA256",
"$ref" : "#/components/schemas/SignatureAlgorithm",
"description" : "Signature algorithm for signing SAML documents"
},
"signatureCanonicalizationMethod" : {
"type" : "string",
"default" : "http://www.w3.org/2001/10/xml-exc-c14n#",
"description" : "Canonicalization method for XML signatures. Validation: must be a valid XML canonicalization method URI (see javax.xml.crypto.dsig.CanonicalizationMethod constants)"
},
"signingCertificate" : {
Expand All @@ -212,6 +223,7 @@
},
"allowEcpFlow" : {
"type" : "boolean",
"default" : false,
"description" : "Allow ECP (Enhanced Client or Proxy) flow"
},
"protocol" : {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,9 @@
public class BaseClientRepresentation extends BaseRepresentation {
public static final String DISCRIMINATOR_FIELD = "protocol";

/** Default for {@link #getEnabled()} when unset, a string because annotation values must be constants. */
public static final String DEFAULT_ENABLED = "true";

@JsonPropertyDescription("UUID generated by the server")
@Schema(description = "UUID generated by the server", readOnly = true)
protected String uuid;
Expand Down Expand Up @@ -121,6 +124,7 @@ public void setDescription(String description) {
this.description = description;
}

@Schema(defaultValue = DEFAULT_ENABLED)
public Boolean getEnabled() {
return enabled;
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
package org.keycloak.representations.admin.v2;

import java.util.Objects;
import javax.xml.crypto.dsig.CanonicalizationMethod;

import jakarta.validation.constraints.Size;

Expand All @@ -36,6 +37,19 @@
public class SAMLClientRepresentation extends BaseClientRepresentation {
public static final String PROTOCOL = "saml";

// Defaults for unset fields, shared by the @Schema documentation and the server side logic that applies them.
// Booleans are strings because annotation values must be constants.
public static final String DEFAULT_FORCE_NAME_ID_FORMAT = "false";
public static final String DEFAULT_INCLUDE_AUTHN_STATEMENT = "true";
public static final String DEFAULT_SIGN_DOCUMENTS = "true";
public static final String DEFAULT_SIGN_ASSERTIONS = "false";
public static final String DEFAULT_CLIENT_SIGNATURE_REQUIRED = "true";
public static final String DEFAULT_FORCE_POST_BINDING = "true";
public static final String DEFAULT_FRONT_CHANNEL_LOGOUT = "true";
public static final String DEFAULT_ALLOW_ECP_FLOW = "false";
public static final String DEFAULT_SIGNATURE_ALGORITHM = "RSA_SHA256";
public static final String DEFAULT_SIGNATURE_CANONICALIZATION_METHOD = CanonicalizationMethod.EXCLUSIVE;

public SAMLClientRepresentation() {
this.protocol = PROTOCOL;
}
Expand Down Expand Up @@ -63,7 +77,9 @@ public static SignatureAlgorithm fromJson(String value) {
}
}

@JsonPropertyDescription("Name ID format to use for the subject")
@JsonPropertyDescription("Name ID format to use for the subject. Set to username when a client is created without a value. "
+ "A client without a stored format, such as one created before this setting was always populated, "
+ "uses the format requested by the SAML client and is left unchanged unless a value is provided.")
private NameIdFormat nameIdFormat;

@JsonPropertyDescription("Force the specified Name ID format even if the client requests a different one")
Expand Down Expand Up @@ -109,6 +125,7 @@ public void setNameIdFormat(NameIdFormat nameIdFormat) {
this.nameIdFormat = nameIdFormat;
}

@Schema(defaultValue = DEFAULT_FORCE_NAME_ID_FORMAT)
public Boolean getForceNameIdFormat() {
return forceNameIdFormat;
}
Expand All @@ -117,6 +134,7 @@ public void setForceNameIdFormat(Boolean forceNameIdFormat) {
this.forceNameIdFormat = forceNameIdFormat;
}

@Schema(defaultValue = DEFAULT_INCLUDE_AUTHN_STATEMENT)
public Boolean getIncludeAuthnStatement() {
return includeAuthnStatement;
}
Expand All @@ -125,6 +143,7 @@ public void setIncludeAuthnStatement(Boolean includeAuthnStatement) {
this.includeAuthnStatement = includeAuthnStatement;
}

@Schema(defaultValue = DEFAULT_SIGN_DOCUMENTS)
public Boolean getSignDocuments() {
return signDocuments;
}
Expand All @@ -133,6 +152,7 @@ public void setSignDocuments(Boolean signDocuments) {
this.signDocuments = signDocuments;
}

@Schema(defaultValue = DEFAULT_SIGN_ASSERTIONS)
public Boolean getSignAssertions() {
return signAssertions;
}
Expand All @@ -141,6 +161,7 @@ public void setSignAssertions(Boolean signAssertions) {
this.signAssertions = signAssertions;
}

@Schema(defaultValue = DEFAULT_CLIENT_SIGNATURE_REQUIRED)
public Boolean getClientSignatureRequired() {
return clientSignatureRequired;
}
Expand All @@ -149,6 +170,7 @@ public void setClientSignatureRequired(Boolean clientSignatureRequired) {
this.clientSignatureRequired = clientSignatureRequired;
}

@Schema(defaultValue = DEFAULT_FORCE_POST_BINDING)
public Boolean getForcePostBinding() {
return forcePostBinding;
}
Expand All @@ -157,6 +179,7 @@ public void setForcePostBinding(Boolean forcePostBinding) {
this.forcePostBinding = forcePostBinding;
}

@Schema(defaultValue = DEFAULT_FRONT_CHANNEL_LOGOUT)
public Boolean getFrontChannelLogout() {
return frontChannelLogout;
}
Expand All @@ -165,6 +188,7 @@ public void setFrontChannelLogout(Boolean frontChannelLogout) {
this.frontChannelLogout = frontChannelLogout;
}

@Schema(defaultValue = DEFAULT_SIGNATURE_ALGORITHM)
public SignatureAlgorithm getSignatureAlgorithm() {
return signatureAlgorithm;
}
Expand All @@ -173,6 +197,7 @@ public void setSignatureAlgorithm(SignatureAlgorithm signatureAlgorithm) {
this.signatureAlgorithm = signatureAlgorithm;
}

@Schema(defaultValue = DEFAULT_SIGNATURE_CANONICALIZATION_METHOD)
public String getSignatureCanonicalizationMethod() {
return signatureCanonicalizationMethod;
}
Expand All @@ -189,6 +214,7 @@ public void setSigningCertificate(String signingCertificate) {
this.signingCertificate = signingCertificate;
}

@Schema(defaultValue = DEFAULT_ALLOW_ECP_FLOW)
public Boolean getAllowEcpFlow() {
return allowEcpFlow;
}
Expand Down
Loading
Loading
0