Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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.and how to upgrade the SMS Configuration. As part of this guide we will explain which upgrade rules need to be created and how to write them.

Note: This is a working document which will continue to evolve as as fill in more detail. If you have comments or suggestions, please feel free to make them.


Schema Changes

Currently there are two ways to change the service schema in AM:

  1. In the xml schema files that use the sms.dtd
  2. Through annotations on POJO's in the AM codebase 

...

  1. codebase

When a change is made upgrade rules will need to be written so that customers can continue to use their configurationto the schema of AM, there needs to be a corresponding change to AM's configuration. New installations of AM will will produce the latest configuration, however existing installations of AM will have configuration that is out of date. The role of an upgrade rule in this case is to upgrade the existing configuration so that it matches the latest schema of AM.

Currently there are 3 ways a customer might upgrade AM's configuration :

...

depending on the deployment model they are using:

...

hiddentrue

...

  1. LDAP SMS: These customers have a deployment based on storing their configuration in an LDAP database. They will upgrade their configuration using the AM upgrader. Developers creating these rules will implement org.forgerock.openam.upgrade.steps.UpgradeStep
  2. Using the openam-config-upgrader and rules
    1. to update Amster files
    2. to update FBC files

TODO: A checklist?

UpgradeStep

TODO:

openam-config-upgrader

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.

Code Block
languagebash
themeEmacs
titleamupgrade CLI
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

Rules to upgrade Amster files

Examples

The the released rules and associated test cases are a good set of examples to follow.

Rules to upgrade FBC

TODO: How to find the service name as it is not the Amster name

TODO: Outline the structure of the fbc

master.groovy

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.

Examples

Idempotency can be achieved using the configuration version.  More information can be found here Upgrade rule filtering based on version.

Code Block
languagebash
themeEmacs
titleIdempotency using configuration version
def UPGRADE_TO_VERSION = "1.0.0.1"    
def APPLICABLE_VERSIONS = ["1.1.0.0","2.0.0.0"]
return
    [
    setVersion(UPGRADE_TO_VERSION),
    forRealmService("authenticationTreesService",
       forVersionsBefore(APPLICABLE_VERSIONS,
           forRealmDefaults(
               addAttribute("new").with("attribute"))
            )
       )
    ]

From authenticationTreesService-realm-defaults-add-attribute.groovy

Guards can be used to achieve idempotency.

Code Block
languagebash
themeEmacs
titleIdempotency using guards
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()))))),
    ]

From oauth2Provider-realm-instances-add-attribute-idempontent.groovy

Testing

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.

Content by Label
showLabelsfalse
max5
spacesopenam
showSpacefalse
sortmodified
reversetrue
typepage
cqllabel = "kb-how-to-article" and type = "page" and space = "openam"
labelskb-how-to-article

  1. Amster based Deployments: These customers have their configuration as exported Amster files. These configuration files will need to be upgraded using the openam-config-upgrader. Developers implementing these rules will need to write new Amster rules to perform this upgrade.

  2. File-based Configuration Deployments: Starting with AM 7.0.0, customers will be able to store their configuration in file-based configuration files on disk. Similar to Amster files in some ways, these new files will also be upgraded using the openam-config-upgrader.

Checklist of required actions

As part of a schema change the following tasks need to be completed

Directly Related

The openam-config-upgrader is released with AM and is the tool for upgrading both Amster-export and FBC AM configuration.

Child Pages

Children Display