Upgrading from 11.2.X to 11.3.0#

Ephemeral Clients - Redirect URI Validation Policy removed (breaking change)#

Ephemeral clients were an experimental feature until now. The Curity Identity Server no longer supports assigning a Redirect URI Validation Policy to Ephemeral clients: the redirect-uri-validation-policy setting under ephemeral-client has been removed from the configuration model.

The setting was removed because using a redirect URI policy violates the Client ID Metadata Document specification, which requires the authorization request’s redirect_uri to be an exact match of one of the redirect_uris published in the metadata document.

It is replaced by two dedicated ephemeral-client settings:

• redirect-uri-same-origin (default true): an https redirect URI that uses a regular domain name (neither a loopback nor an IP-literal address) must have the same origin (scheme, host, and port) as the client_id. Disable it to accept any https domain.
• allow-loopback-redirect-uris (default false): accept cross-origin loopback redirect URIs (http or https). When enabled, the loopback port is not validated.

A redirect URI that is same-origin with the client_id is always accepted, regardless of these settings.

JDBC Data Source#

Entity Management Storage Changes#

The database schema for the JDBC data sources was updated to improve how entities (like SCIM groups or database scopes) are stored:

• The experimental entities table is altered with a new column and a column rename.
• A new table has been added to persist a new type of relations for entities.

DynamoDB Database changes#

No mandatory changes are included in this release, however, the new combined tag and name filtering in the GraphQL Admin API requires a new global secondary index (GSI) to be added to the curity-database-clients table - tag-client_name_key-index: with tag_key attribute as partition key and tag_client_name_key attribute as sort key. To facilitate updating the table’s schema, JSON configuration files are provided with this release, in the $IDSVR_INSTALL/misc/upgrade/11.2-to-11.3/dynamodb directory. Files can be used with the aws dynamodb update-table command and passed as arguments to, respectively, the --global-secondary-index-updates and the --attribute-definitions options, to create the required index. In addition, a backfill script backfill-tag-client-name-key.sh is provided in the same directory and must be run after the index is created, to add the tag_client_name_key attribute to secondary items written before this release. The identity-server picks up the new index automatically on the first combined-filter query after the upgrade scripts run — no restart is required. This update is only required when using combined tag and name filtering in the searchDatabaseClients or databaseClients GraphQL queries.

Changes to HAAPI Responses#

This release includes small changes to the HAAPI responses for certain views to improve the user experience based on how clients are expected to handle the responses (namely the HAAPI SDKs provided by Curity). The changes are done accordingly to the HAAPI schema and also aligning with other responses produced by the server, so a HAAPI client should be able to handle them without any change.

HTML Form Authenticator#

The HAAPI responses for the following views were changed to use a form action instead of a link for the “return to login” option, for consistency with other responses of the authenticator:

• reset-password/post.
• forgot-account-id/post.
• set-password/get when the token is invalid.

In all three cases, the previous link with relation restart was replaced by a form action with kind continue and the same target URL.

Use of title and actionTitle in form Actions Without Visible Fields#

In different cases, HAAPI responses contain form actions which only have hidden fields, i.e. actions that don’t require user input other than submitting. In many of such cases the server previously returned both title and actionTitle in the form action, with the same (or very similar) values. A client rendering a UI for such responses would likely present a suboptimal user experience due to the redundancy.

In this release, the server was updated to only return actionTitle in such cases, and not title, allowing clients to render a more concise UI (e.g. simply showing a button). The HAAPI responses for the following views were changed accordingly:

• authenticator/bankid/wait/index
• authenticator/bankid/failed/index
• authenticator/email/link-wait/index
• authenticator/html-form/create-account/post
• authenticator/html-form/account-activation/success
• authenticator/html-form/set-password/post
• authenticator/passkeys/authenticate-device/get (“no devices” case)
• authenticator/passkeys/authenticate-device/username
• authenticator/sms/link-wait/get
• authenticator/sms/register/wait
• authenticator/webauthn/authenticate-device/get (“no devices” case)
• authenticator/webauthn/authenticate-device/username
• authenticator/webauthn/add-additional-device/get
• authentication-action/opt-in-mfa/* (all views except select)
• authentication-action/signup/get

The above approach is used for form actions in the root of the response, except when the action is the single/first in a view, in which case its title can act as the page title. Note that title is an optional field in the HAAPI schema, so clients should already handle its absence.

Token Issuance Authorizer SDK Changes#

The Token Issuance Authorizer SDK (still annotated @Experimental) now allows a scope to carry multiple decisions at once. The constructor of se.curity.identityserver.sdk.oauth.tokenissuanceauthorizers.TokenIssuanceAuthorizerResult takes Map<String, List<TokenIssuanceAuthorizationDecision>> instead of Map<String, TokenIssuanceAuthorizationDecision>. Custom TIA plugins must wrap each scope’s decision in a list.

Token Issuance Authorizer access denied change#

When a token issuance request is denied by a Token Issuance Authorizer (i.e. all of the requested scopes are rejected and a token without custom claims (other than exp/iss/etc.) would be issued), an access denied (HTTP/400) error is returned, instead of a token response with an empty scope and no custom claims. This allows clients to distinguish between a request that was denied by the TIA and a request that was accepted but resulted in a token with no scopes or custom claims.

OIDC Authenticator - Response Mode and Parameter Mappings#

The authenticator now supports configuring the response mode for the authorization endpoint, to use either query (the default) or form-post.

Adding a parameter mapping for a parameter named response_mode is now forbidden and fails configuration validation. Trying to use this parameter mapping with a value other than query would result in a runtime error, anyway, because the authenticator didn’t previously support other response modes. Using this parameter mapping with the value query is not recommended by OpenID Connect, because it is the default response mode for Authorization Code grants.

Any existing parameter mapping for response_mode should be removed before upgrading.

SAML2 Authenticator - AudienceRestriction validation#

The SAML2 Authenticator now correctly validates the AudienceRestriction condition in the SAML assertion, if present, according to the SAML2 WebSSO profile specification. By default, it will perform this validation.

If the SAML IDP that you are relying on for authentication does not include the AudienceRestriction condition in the SAML assertion and it is unfeasible to fix it on the SAML IDP side to do so, you can disable this validation by setting the require-audience-restriction configuration property to false. Note that this will only accept assertions without AudienceRestriction, but if an assertion includes it, it will still be validated.

Entity Schemas Changes#

This release introduces a breaking change to the experimental YANG configuration for entity schemas. As a result, the entity schema configuration cannot be reused as-is between the 11.2 and 11.3 versions of the Curity Identity Server, and any existing configuration must be reviewed and migrated before upgrading.

In addition, entity data already persisted in the database will be stale after the upgrade, as the schema changes are not backward compatible. There is no automated migration path for this data; refer to the Entity Management Storage Changes .

Migrating the Configuration#

To migrate an existing entity schema configuration from 11.2 to 11.3 version, follow these steps:

1. Export the configuration from the running 11.2 Curity Identity Server.

2. In the exported configuration, empty the body of each entity schema, keeping only its id tag, as follows:

   <data-schemas>
     <entity-schema>
       <id>my-scim-groups-schema</id>
       <!-- Delete anything else -->
     </entity-schema>
   </data-schemas>

3. Import the edited configuration into the 11.3 Curity Identity Server.

4. Enable the schema with the SCIM Groups feature by running the Creates or updates an entity schema to support groups Config Spec.