Upgrading from 9.7.X to 10.0.0

Token Handler Applications

The default value for require-custom-header in the Token Handler application’s configuration was changed from false to true. Setting this value to true makes a Token Handler application require a custom header which prevents certain types of CSRF attacks (the header has to be sent by an SPA using the given Token Handler application). To avoid breaking existing SPAs it is required to set require-custom-header explicitly to false before upgrading for all Token Handler applications that don’t have this value set explicitly. Refer to the token handler documentation for more information on the custom header.

OpenID Connect Authenticator - Signed UserInfo Responses

The OpenID Connect Authenticator was updated so that it requires the issuer (iss) and audience (aud) claims to be present in signed (and signed then encrypted) UserInfo responses. Those claims are required by the OpenID Connect Core specification in such cases.

If the authenticator is used against a misbehaving OpenID provider, which doesn’t include the issuer and/or audience claims in signed UserInfo JWTs, the fetch-userinfo/strict-validation-when-signed configuration option should be set to false when upgrading. This will disable the requirement for the issuer and audience claims.

If the OpenID provider is compliant, no action is needed.

Email Authenticator

The existing throttling settings, max-challenges-sent and max-allowed-attempts, have been deprecated in favour of the new throttling settings.

Even though no action is required, we recommend moving to the new throttling setting. See the Email Authenticator Documentation for details. If a Bucket is configured to store throttling metadata, make sure to add a janitor procedure to cleanup expired data as mentioned in Database maintenance.

BankID Authenticator

Some changes have been made to the BankID authenticator

Use API version 6 by default

The default API version is changed to be Version 6. Version 5 is deprecated by BankID and should not be used. Version 6 removes the possibility to start a transaction using the users personal number, but should otherwise be backwards compatible. If upgrading to Version 6, note that the settings bankid-issuer-cn and generate-autostart-qr-code are no longer available and needs to be removed from the xml config.

To keep using the Version 5 API, you may explicitly set the api-version in config to be version-5. But you should plan to upgrade as soon as possible since this version is out of support from BankID and may be turned off.

Use Launch template v2 by default

8.7 introduced a v2 of the BankID templates which now is used by default. Read more in Launch Behavior.

Other template updates

The authenticator/bankid/failed/index.vm template was updated to include an additional link that allows the user to terminate the ongoing authentication flow and return to the originating application.

Removal of deprecated config option

The config option use-new-api-endpoint has been removed. This was previously used to switch between the API endpoints that BankID introduced in Version 4 of the API. The option has been hidden and not had an effect in 9.x, and should be safe to be remove.

User Management - Username updates and account deletion with legacy credential data sources

Note

The changes mentioned in this section apply to Credential Data Access using legacy data sources, i.e. data sources using deprecated features. Specifically:

  • JDBC data sources using the credentials-in-accounts-table and credentials-migration credential modes (old DB schema).
  • Custom data source plugins implementing the CredentialDataAccessProvider interface.

In User Management (UM) profiles, it is possible to configure a Credential Manager, which is used in different operations involving user credentials. When the Credential Manager’s data source is a legacy credential data source, certain operations done via the UM APIs could lead to data inconsistency. In previous versions of the Curity Identity Server, such cases were allowed and specific log entries were written. With this release, the following operations are no longer supported when using a legacy credential data source:

  • Account update containing a username change.
  • Account deletion.

This applies to both SCIM and GraphQL endpoints.

If such operations are required, the data source used by the Credential Manager must be upgraded. Namely, JDBC data sources should be upgraded as described in a previous section of this guide.

OAuth Client Authentication

Basic HTTP authentication - URL decoding of client ID and secret

When using HTTP Basic authentication to authenticate OAuth clients, the server now does URL decoding of both the userid and the password components to establish the client ID and secret for validation. This aligns with OAuth 2.0, which states that clients should encode their ID/secret in this context.

Previous versions of the Curity Identity Server didn’t apply URL decoding, so this change is breaking in some cases, namely if a client’s secret includes escape sequences (e.g. %3A). In such cases, the client should start URL-encoding its ID/secret or the secret should be updated.

Note that client secrets generated by the Curity Identity Server are URL-safe, namely in the Admin UI, the Dynamic Client Registration endpoints and the Database Clients API. However, system administrators can explicitly set client secrets in some cases (e.g. configuration-backed clients).

Mutual TLS by Proxy - Proxy password

When using mTLS by Proxy client authentication, it is possible to configure a userid and password for the proxy to authenticate itself. In this case, the proxy uses HTTP Basic authentication through a Proxy-Authorization header.

Previous versions of the Curity Identity Server incorrectly applied URL-encoding to the configured proxy password before using it for validation against the credentials in the Proxy-Authorization header. In the cases where the configured password contained URL-unsafe characters, this would lead to an incorrect password being used for validation.

This behavior was fixed, so that the configured password is always used without modification.

SDK

Deprecation of the CredentialDataAccessProvider interface

Note

The changes mentioned in this section are meant for authors of data access plugins, namely when implementing support for Credential Data Access using the CredentialDataAccessProvider interface.

The CredentialDataAccessProvider interface is now deprecated and scheduled for removal in the next major release. The same applies to the corresponding getCredentialDataAccessProvider method in the DataAccessProviderPluginDescriptor interface.

Any data access plugin implementing that interface should be updated to implement one of the subtypes of the CredentialManagementDataAccessProvider interface, depending on the data access provider (DAP) features. If a credential data source implementing the old interface is used by the server, an alarm will be raised.

If the DAP currently returns false in the customQueryVerifiesPassword method, the CredentialStoringDataAccessProvider interface should be implemented. This is for cases where the DAP is simply a store of credentials and doesn’t implement any credential handling logic on its own. If support for Credential Policies is needed, the DAP should also implement the CredentialAttributesUpdater feature interface.

If the DAP returns true in the customQueryVerifiesPassword method, the CredentialVerifyingDataAccessProvider interface should be implemented. This is for cases where the DAP itself handles credentials, namely verifying that a given password matches the known password for a subject.

Refer to the Javadocs of the different interfaces for more details.

Delegation Data Access Provider

The DelegationDataAccessProvider SDK interface was added with two new methods: setStatusByOwner and setStatusByOwnerAndClient. They are needed for the new experimental Granted Authorization GraphQL API. The interface contains a default implementation for these two new methods that just throws a UnsupportedOperationException, however a proper implementation is needed if the Granted Authorization GraphQL API is going to be used. The DelegationDataAccessProvider implementations included in the Curity Identity Server do correctly support these new methods.

Original Query parameter encoding

The parameter values in the Original Query string are now always URL encoded. In previous Curity Identity Server versions, these values were only encoded if PAR (RFC 9126 - OAuth 2.0 Pushed Authorization Requests) was used. For example, if the value https://example.org/oauth/callback was used for the redirect_uri parameter, then it will appear in the Original Query as https%3A%2F%2Fexample.org%2Foauth%2Fcallback.