This article will describe the steps that you need to take when making a change to the service schema in AM (aka the configuration), in particular this will focus on how the upgrade rules should be created and applied.
Currently there are two ways to change the service schema in AM:
In either case when a change is made upgrade rules will need to be written so that customers can continue to use their configuration.
Currently there are 3 ways a customer might upgrade AM's configuration:
Using the openam-config-upgrader and rules
TODO: A checklist?
A tool for converting AM configuration files (Amster export or FBC) to be usable with a newer version of AM. The project is within the openam repository. The README and its examples is a good place to start, as is the the CLI output. The tool is delivered as part of the AM.zip. It is driven by rules that are either delivered along with the tool or even custom written.
Usage: amupgrade [options] <Rules files> Options: * --inputConfig, -i The input configuration directory * --output, -o The output configuration directory --version, -V Prints the version of this config upgrader tool and exits --verbose, -v include to log verbose output * --amsterVersion, -a The version of Amster that will be used to import the configuration (for example 6.0.0) --secretsConfigFile, -f The properties file that contains settings necessary to migrate credentials to secrets This is mandatory if your rules contain secrets upgradessee sampleconfig.properties file for more details --log-output, -l The file location to log output to
The the released rules and associated test cases are a good set of examples to follow.
TODO: How to find the service name as it is not the Amster name
TODO: Outline the structure of the fbc
Set of idempotent rules that will upgrade file based configuration files to be compatible with the latest version of AM on a branch. master.groovy is contained in the AM.zip release.
Idempotency can be achieved using the configuration version. More information can be found here Upgrade rule filtering based on version.
def UPGRADE_TO_VERSION = "188.8.131.52" def APPLICABLE_VERSIONS = ["184.108.40.206","220.127.116.11"] return [ setVersion(UPGRADE_TO_VERSION), forRealmService("authenticationTreesService", forVersionsBefore(APPLICABLE_VERSIONS, forRealmDefaults( addAttribute("new").with("attribute")) ) ) ]
Guards can be used to achieve idempotency.
return [ forRealmService("OAuth2Provider", forRealmDefaults( within("advancedOIDCConfig", where(key("authorisedIdmDelegationClients").isNotPresent(), addAttribute("authorisedIdmDelegationClients").with(Collections.emptySet())))), forSettings( within("advancedOIDCConfig", where(key("authorisedIdmDelegationClients").isNotPresent(), addAttribute("authorisedIdmDelegationClients").with(Collections.emptySet()))))), ]
Unit tests will run against master.groovy for these test cases. When adding rules it is expected that test case files are added to test those rules.
Related articles appear here based on the labels you select. Click to edit the macro and add or change labels.