Upgrading from 4.0.X to 4.1.0

There are no breaking changes between 4.0.X to 4.1.0 even though there were substantial changes made and new features added. For informational purposes, some of the non-breaking additions are described below.

Upgrading the XML Configuration

Description Applicability Change Method
OpenID Connect claims OAuth with OpenID Connect enabled No action, automatic using XSLT, or manual
Access control rules that apply to the admin UI Delegated administration Manual

As with previous releases, the XML configuration can be converted using a provided XSLT and its associated auto-upgrade.sh script. New with this version is automatic upgrades that will run when necessary to perform the same upgrade. To run the XSLT on a configuration data set, run the auto-upgrade.sh script, like this:

Listing 72 Upgrading from 4.0.X to 4.1.0 using the provided XSLT and auto-upgrade.sh
$ $INSTALL_DIR/misc/upgrade/4.0-to-4.1/auto-upgrade.sh $IDSVR_HOME/etc/init/some-config.xml

OpenID Connect Claims

Prior to 4.1.0, the way that attributes were placed into ID tokens and the response to calls made to the userinfo endpoint were rather opaque. If the account manager configured on the profile provided attributes in a way that could be mapped to the ID token or userinfo response, they were mapped automatically. If they were not, however, a token issuance procedure had to be used to place the data where it was needed. With the new claims providers and claims mappings, this can be done in a more intuitive way. There are a few ways to migrate to the new claims-based system:

  1. Do nothing and, on first boot, the configuration will be automatically upgraded.
  2. Run the XSLT transform included with the distribution.
  3. Manually upgrade the configuration as described below.

Add an Account Manager Claims Provider

Each claim value is now clearly obtained from some provider. These are extensible using the SDK, and many are provided out of the box. One included claims value provider is a component that obtains claim values from an account manager. Because all OpenID Connect claim values were previously obtained from an account manager, migrating to this new release while maintaining the exact same behavior requires the definition of an account manager claims provider. This can be done by adding an XML snippet such as the following to each OAuth profile that has OpenID Connect enabled.

Listing 73 An account manager claims provider
<profile>
    <type xmlns:as="https://curity.se/ns/conf/profile/oauth">as:oauth-service</type>
    <settings>
    <authorization-server xmlns="https://curity.se/ns/conf/profile/oauth">
        <claims-value-provider>
            <id>account-manager-claims-provider</id>
            <account-manager-claims-provider xmlns="https://curity.se/ns/ext-conf/account-manager-claims-provider">
                <account-manager>
                    <id>
                        <!-- The ID of the account manager set on the OAuth profile -->
                    </id>
                </account-manager>
            </account-manager-claims-provider>
        </claims-value-provider>
    </authorization-server>
    </settings>
</profile>

The ID of the account manager should be the same as the one set on the profile.

Add Standard OpenID Connect Claims

Add the standard OpenID Connect claims to the configuration. This can be done by adding XML configuration such as this:

Listing 74 Standard claims that should be added to each OpenID Connect enabled OAuth profile
<profile>
    <type xmlns:as="https://curity.se/ns/conf/profile/oauth">as:oauth-service</type>
    <settings>
    <authorization-server xmlns="https://curity.se/ns/conf/profile/oauth">
    <claims>
        <claim>
            <name>website</name>
            <value-provided-by>account-manager-claims-provider</value-provided-by>
        </claim>
        <claim>
            <name>zoneinfo</name>
            <value-provided-by>account-manager-claims-provider</value-provided-by>
        </claim>
        <claim>
            <name>family_name</name>
            <value-provided-by>account-manager-claims-provider</value-provided-by>
        </claim>
        <claim>
            <name>gender</name>
            <value-provided-by>account-manager-claims-provider</value-provided-by>
        </claim>
        <claim>
            <name>given_name</name>
            <value-provided-by>account-manager-claims-provider</value-provided-by>
        </claim>
        <claim>
            <name>locale</name>
            <value-provided-by>account-manager-claims-provider</value-provided-by>
        </claim>
        <claim>
            <name>middle_name</name>
            <value-provided-by>account-manager-claims-provider</value-provided-by>
        </claim>
        <claim>
            <name>name</name>
            <value-provided-by>account-manager-claims-provider</value-provided-by>
        </claim>
        <claim>
            <name>birthdate</name>
            <value-provided-by>account-manager-claims-provider</value-provided-by>
        </claim>
        <claim>
            <name>nickname</name>
            <value-provided-by>account-manager-claims-provider</value-provided-by>
        </claim>
        <claim>
            <name>picture</name>
            <value-provided-by>account-manager-claims-provider</value-provided-by>
        </claim>
        <claim>
            <name>preferred_username</name>
            <value-provided-by>account-manager-claims-provider</value-provided-by>
        </claim>
        <claim>
            <name>profile</name>
            <value-provided-by>account-manager-claims-provider</value-provided-by>
        </claim>
        <claim>
            <name>updated_at</name>
            <value-provided-by>account-manager-claims-provider</value-provided-by>
        </claim>
        <claim>
            <name>phone_number</name>
            <value-provided-by>account-manager-claims-provider</value-provided-by>
        </claim>
        <claim>
            <name>phone_number_verified</name>
            <value-provided-by>account-manager-claims-provider</value-provided-by>
        </claim>
        <claim>
            <name>email</name>
            <value-provided-by>account-manager-claims-provider</value-provided-by>
        </claim>
        <claim>
            <name>email_verified</name>
            <value-provided-by>account-manager-claims-provider</value-provided-by>
        </claim>
        <claim>
            <name>address</name>
            <value-provided-by>account-manager-claims-provider</value-provided-by>
        </claim>
    </claims>
    </authorization-server>
    </settings>
</profile>

Map Claims to ID Tokens and Userinfo

Claims values are now mapped to different “sinks”, different final output destinations. ID tokens and userinfo responses are such sinks. This is done using claims mappers. A claims mapper can define mappings of claims that should end up in ID tokens, userinfo responses, access tokens, and more. A mapper can be set per client, and a default can be configured per profile. To maintain backward compatibility, a new mapper should be defined and set as the default. It should map the standard claims to ID tokens and user info. As above, this should be done for each OAuth profile that has OpenID Connect enabled. The mapping that is needed is shown in the following snippet:

Listing 75 Standard claims that should be added to each OpenID Connect enabled OAuth profile
<profile>
    <type xmlns:as="https://curity.se/ns/conf/profile/oauth">as:oauth-service</type>
    <settings>
    <authorization-server xmlns="https://curity.se/ns/conf/profile/oauth">
        <claims-mappers>
            <claims-mapper>
                <id>default</id>
                <id_token>
                    <claim>website</claim>
                    <claim>zoneinfo</claim>
                    <claim>family_name</claim>
                    <claim>gender</claim>
                    <claim>given_name</claim>
                    <claim>locale</claim>
                    <claim>middle_name</claim>
                    <claim>name</claim>
                    <claim>birthdate</claim>
                    <claim>nickname</claim>
                    <claim>picture</claim>
                    <claim>preferred_username</claim>
                    <claim>profile</claim>
                    <claim>phone_number</claim>
                    <claim>phone_number_verified</claim>
                    <claim>email</claim>
                    <claim>email_verified</claim>
                    <claim>address</claim>
                    <claim>updated_at</claim>
                </id_token>
                <userinfo>
                    <claim>website</claim>
                    <claim>zoneinfo</claim>
                    <claim>family_name</claim>
                    <claim>gender</claim>
                    <claim>given_name</claim>
                    <claim>locale</claim>
                    <claim>middle_name</claim>
                    <claim>name</claim>
                    <claim>birthdate</claim>
                    <claim>nickname</claim>
                    <claim>picture</claim>
                    <claim>preferred_username</claim>
                    <claim>profile</claim>
                    <claim>phone_number</claim>
                    <claim>phone_number_verified</claim>
                    <claim>email</claim>
                    <claim>email_verified</claim>
                    <claim>address</claim>
                    <claim>updated_at</claim>
                </userinfo>
            </claims-mapper>

            <default-claims-mapper>default</default-claims-mapper>
        </claims-mappers>
    </authorization-server>
    </settings>
</profile>

Add Standard Claims to Standard Scopes

A scope is a group of claims. For the standard OpenID scopes, the claims in each of these groupings is well defined. With this release, others can be added to them, and custom claims can be added to custom scopes. To maintain parity with previous releases, the standard claims must be grouped into the standard scopes. This can be done by adding the final configuration snippet shown below to each OAuth profile that has OpenID Connect enabled:

Listing 76 Addition of standard claims to standard OpenID Connect scopes
<profile>
    <type xmlns:as="https://curity.se/ns/conf/profile/oauth">as:oauth-service</type>
    <settings>
    <authorization-server xmlns="https://curity.se/ns/conf/profile/oauth">
    <scopes>
        <!-- Potentially other, non-standard scopes -->

        <scope>
            <id>email</id>
            <!-- other settings for this scope -->
            <claims>email</claims>
            <claims>email_verified</claims>
        </scope>

        <scope>
            <id>phone</id>
            <!-- other settings for this scope -->
            <claims>phone_number</claims>
            <claims>phone_number_verified</claims>
        </scope>

        <scope>
            <id>address</id>
            <!-- other settings for this scope -->
            <claims>address</claims>
        </scope>

        <scope>
            <id>profile</id>
            <!-- other settings for this scope -->
            <claims>name</claims>
            <claims>family_name</claims>
            <claims>given_name</claims>
            <claims>middle_name</claims>
            <claims>nickname</claims>
            <claims>preferred_username</claims>
            <claims>profile</claims>
            <claims>picture</claims>
            <claims>website</claims>
            <claims>gender</claims>
            <claims>birthdate</claims>
            <claims>zoneinfo</claims>
            <claims>locale</claims>
            <claims>updated_at</claims>
        </scope>
    </scopes>
    </authorization-server>
    </settings>
</profile>

Access Control Rules

Access control rules created in the admin UI using version 4.0 were not applied to the UI itself. In this version, they are. However, for this to work successfully, the rules must be updated or recreated. The easiest way to do this is to delete the rules in the UI and recreate them in the UI. If this is not feasible or preferable, please contact support for more information about how to migrate the NACM rules.

New Templates

The IDs of the HTML input fields in the oauth/consent.vm template have changed. This should not pose a problem if it was overridden and the variables were used. It could pose a problem if CSS selectors were added based on the ID, however. It may also affect automated tests that selected elements by ID.

The following new templates have been added, and will need to be customized if consentors are used:

BankID consentor

  • ROOT_DIR/consentor/bankid-signing-consentor/bankid-poller.vm - The polling form used to start the BankID signing process. Polling BankID until the process is completed or failed.
  • ROOT_DIR/consentor/bankid-signing-consentor/handle-auto-start-uri.vm - Triggers the automatic start of the BankID application in order to sign the consent data.

Consentor Selection

  • ROOT_DIR/fragments/consentor-chooser-single-color.vm - Template fragment for the consentor selection with single color.
  • ROOT_DIR/fragments/consentor-chooser.vm - Template fragment for the consentor selection with multiple colors.
  • ROOT_DIR/views/select-consentor/index.vm - The default consentor listing view.

(Where ROOT_DIR = $IDSVR_HOME/usr/share/templates/core.)

New Message Files

The following new message files have been added and will need to be localized if consentors are used with an unsupported language:

  • ROOT_DIR/en/consentor/bankid-signing-consentor/bankid.properties - Contains all the keys for the text appearing on the BankID consentor in English.
  • ROOT_DIR/sv/consentor/bankid-signing-consentor/bankid.properties - Contains all the keys for the text appearing on the BankID consentor in Swedish.
  • ROOT_DIR/en/views/select-consentor/messages - Contains all the keys for the text appearing on the consentor selection in English.
  • ROOT_DIR/sv/views/select-consentor/messages - Contains all the keys for the text appearing on the consentor selection in Swedish.

(Where ROOT_DIR = $IDSVR_HOME/usr/share/messages/core.)

Upgrading Assisted Token JavaScript

If the assisted token JavaScript library has been deployed to a Content Delivery Network (DCD) or other server besides a Curity node, it will need to be redeployed to apply the fix for IS-3619. Refer to the release notes for details on that bug.

SDK Changes

In this version, the method getReturnedClaims on the UserInfoOAuthEvent class is deprecated. Also, new types and non-breaking changes to support consentors and claims providers have been made. Refer to the SDK documentation and javadocs for details.