Child pages
  • Scripting an OpenAM deployment
Skip to end of metadata
Go to start of metadata

When setting an OpenAM infrastructure, it is common to have more than one environment, for example having a Development, Test/Acceptance and Production environment is very common. One of the questions that arises is, how do I move my configuration from the Acceptance to the Production environment ?

The answer to this question has to do with the deployment practices. For OpenAM there are two ways to configure the system: Use the Web GUI and use the CLI (Commnad Line Interface)

The recommended practice is to script the installation by using the CLI (ssoadm). In this way the configuration can be redeployed at any time and in different environments; it helps to enforce deployment practices and maintains a live documentation of the existing configuration.

The scripts could be as simple or as complex as needed, depending on how much you want the deployment to be automated. Some administrators use simple scripts containing the specific ssoadm commands together with the parameters for the environment, some other administrators have a generic set of scripts and use properties files to use as input for the configuration scripts of the specific environment.

The Command Line Reference shows the ssoadm available sub-comands and parameters:

https://wikis.forgerock.org/confluence/display/openam/OpenAM+Command+Line+Reference

Examples of typical configuration commands are:

  1. Create a realm

    ssoadm create-realm --realm myrealm -u amadmin -f /home/openam/.mypass

    Set a realm's organization name

    ssoadm set-realm-attrs --realm myrealm -u amadmin -f /home/openam/.mypass -s sunIdentityRepositoryService --attributevalues openam.example.com

  2. Create a Data Store configuration for a realm

    Create a Data Store configuration for a realm

    ssoadm create-datastore -u amadmin -f /home/openam/.mypass -e /myrealm -m newds -t LDAPv3ForOpenDS -D datastore_info.text


    (Where datastore_info.text contains the parameters to configure the Data Store)

  3. Remove the embedded data store

    ssoadm delete-datastores -e /myrealm -u amadmin -f /home/openam/.mypass -m "embedded"

     

    Example script

    Here an example of a script that deploys a specific environment. This is just an illustrative example and the complexity of a script for a production environment can change depending of the features used. This example applies to a Linux environment, but a similar bat file can be created for a Windows environment:

    Simple deployment script example
    #!/bin/bash
    #
    # Example script for creating initial OpenAM config
    #
    SSOADM=/opt/openam/cli/openam/bin/ssoadm
    PWDFILE=/opt/openam/pwdfile
    XMLCFG=/opt/tomcat/webapps/openam/WEB-INF/classes
    # Realm config
    #
    # Create the realm myrealm
    ${SSOADM} create-realm --realm myrealm -u amadmin -f ${PWDFILE}
    # Set the realm attributes
    ${SSOADM} set-realm-attrs --realm / -u amadmin -f ${PWDFILE} -s
    sunIdentityRepositoryService --attributevalues sunOrganizationAliases=openam
    ${SSOADM} set-realm-attrs --realm /myrealm -u amadmin -f ${PWDFILE} -s
    sunIdentityRepositoryService --attributevalues
    sunOrganizationAliases=openam.example.com sunOrganizationAliases=example
    # List the realm attributes for info
    ${SSOADM} get-realm --realm / -u amadmin -f ${PWDFILE} -s
    sunIdentityRepositoryService
    ${SSOADM} get-realm --realm /myrealm -u amadmin -f ${PWDFILE} -s
    sunIdentityRepositoryService
    # DataStore config
    #
    # List datastore types (NOt really needed, just her eas an example)
    ${SSOADM} list-datastore-types -u amadmin -f ${PWDFILE}
    # Create the newds datastore (The file datastore_info.text) contains the
    ${SSOADM} create-datastore -u amadmin -f ${PWDFILE} -e /myrealm -m newds -t
    LDAPv3ForOpenDS -D datastore_info.text
    # Remove the embedded datastore
    ${SSOADM} delete-datastores -e /myrealm -u amadmin -f ${PWDFILE} -m "embedded"
    # List the available datastores
    ${SSOADM} list-datastores --realm /myrealm -u amadmin -f ${PWDFILE}
    # Authn modules
    #
    # Create an LDAP configuration instance
    ${SSOADM} create-auth-instance -u amadmin -f ${PWDFILE} -m MyLDAP -t LDAP
    -e /myrealm
    # Configure the MyLDAP Authentication instance
    ${SSOADM} update-auth-instance -u amadmin -f ${PWDFILE} -m MyLDAP -e /myrealm -a
    "iplanet-am-auth-ldap-base-dn=dc=example,dc=com" -a "iplanet-am-auth-ldap-user-
    naming-attribute=uid"
    # Or as an alternative, the
    LDAP_Authn_config is a file containing the
    configuration fo the MyLDAP Authentication instance
    # ${SSOADM} update-auth-instance -u amadmin -f ${PWDFILE} -m MyLDAP -e /myrealm
    -D LDAP_Authn_config
    # List Authentication configuration
    ${SSOADM} list-auth-instances -u amadmin -f ${PWDFILE} -e /myrealm
    # Authn service (or chains)
    #
    # Create and configure MyLDAPChain containing the MyLDAP Authentication module as
    required
    ${SSOADM} create-auth-cfg -u amadmin -f ${PWDFILE} -e /myrealm -m MyLDAPChain
    ${SSOADM} add-auth-cfg-entr -u amadmin -f ${PWDFILE} -e /myrealm -m MyLDAPChain
    -o MyLDAP -c REQUIRED
    

Another way to execute the ssoadm command is by using the do batch subcommand.

Example:

Execute a batch file

ssoadm do-batch -u amadmin -f /opt/openam/pwdfile -Z /path/batch-file --batchstatus batch-status-file --continue

SSOADM batch file containing seeveral commands
# This file is the batch set of commands (/path/batch-file)
# Configure the DataStrore NewDS witht the params stored in the properties file
update-datastore -e /myrealm -m NewDS -D config/update-datastore-
datafile.properties
# Set the cookie domains for the platform service
set-attr-defs -s iPlanetAMPlatformService -t global -a iplanet-am-platform-
cookie-domains=.example.com iplanet-am-platform-cookie-domains=.internal.com
# Create the MyLDAP Authentication instance and update the config
create-auth-instance -m MyLDAP -t LDAP -e /myrealm
update-auth-instance -m MyLDAP -e /myrealm -a "iplanet-am-auth-ldap-base-
dn=dc=example,dc=com" -a "iplanet-am-auth-ldap-user-naming-attribute=uid"
# Create the MyLDAPChain Authentication chain and add MyLDAP as a required module
create-auth-cfg -e /myrealm -m MyLDAPChain
add-auth-cfg-entr -e /myrealm -m MyLDAPChain -o MyLDAP -c REQUIRED

 

More complex scripted deployment

A more complex set of automation scripts can include the installation and deployment of the
whole environment, for example this would be a list of generic tasks:

  1. Install your web container
  2. Tune your Web Container JVM parameters
  3. Install OpenDJ, configure schema, set JVM parameters
  4. Configure the indexes for the OpenDJ
  5. Load the OpenDJ data
  6. Deploy the OpenAM war in the web container
  7. Perform the initial OpenAM Configuration (using the configurator.jar and the silent installation)
  8. Deploy the ssoadm CLI
  9. Configure OpenAM (using ssoadm commands)
    1. Create site
    2. Configure realm
    3. Add authentication configuration
    4. Configure global services
    5. Configure data stores
    6. Configure Federation
    7. etc

Each of the tasks described above can be scripted and the input for the scripts can be obtained from a properties file and templates for the installation.

How do I script an existing environment that was deployed using the GUI

If you want to export the configuration of an existing deployment, you can do that by exporting the whole configuration with one command, but that does not give the details of each step and it does not give you the flexibility to adjust the configuration to a specific environment, given that the output is a big XML file containing all the services.

The approach should be to deploy the OpenAM of a production environment from the beginning using scripts.

However, if you want to copy a specific part of the configuration from one environment to another, you could use a specific ssoadm command that will provide you with an output that can be reused as the input for an ssoadm command in another environment.

Here some examples of such commands:

  1. Data Store Configuration
    1. Show the data store configuration

      ssoadm show-datastore -u amadmin -f /home/openam/.mypass -e /myrealm -m myDataStore > datastore_info

    2. Edit the necessary attributes (for example the password for the bind user)
    3. Load the configuration in the other environment with a command like:

      Load the data store configuration

      ssoadm create-datastore -u amadmin -f /home/openam/.mypass -e / -m newds -t LDAPv3ForOpenDS -D datastore_info.text

  2. Authentication Configuration
    1. List authentication instances in a realm, i.e. list the authentication modules defined in a realm

      List authentication instances

      ./ssoadm list-auth-instances -u amadmin -f /home/victor/openam_tc_8080/.pass -e /

      Authentication Instances:
      DataStore, [type=DataStore]
      WSSAuthModule, [type=WSSAuthModule]
      HOTP, [type=HOTP]
      Federation, [type=Federation]
      LDAP, [type=LDAP]
      SAE, [type=SAE]

    2. List a specific authentication instance configuration:

      List an authentication instance

      victor@balam1:~/openam_tc_8080/cli/openam/bin$ ./ssoadm get-auth-instance -u amadmin -f /home/victor/openam_tc_8080/.pass -e / -m LDAP

      Authentication Instance profile:
      iplanet-am-auth-ldap-ssl-enabled=false
      iplanet-am-auth-ldap-return-user-dn=true
      iplanet-am-auth-ldap-search-scope=SUBTREE
      iplanet-am-auth-ldap-search-filter=
      iplanet-am-auth-ldap-base-dn=dc=example,dc=com
      iplanet-am-ldap-user-creation-attr-list=
      iplanet-am-auth-ldap-user-search-attributes=uid
      iplanet-am-auth-ldap-server=localhost:50389
      iplanet-am-auth-ldap-invalid-chars=*|(|)|&|!
      iplanet-am-auth-ldap-user-naming-attribute=uid
      iplanet-am-auth-ldap-bind-dn=cn=Directory Manager
      iplanet-am-auth-ldap-auth-level=0
      iplanet-am-auth-ldap-bind-passwd=********
      iplanet-am-auth-ldap-server2=
      iplanet-am-auth-ldap-min-password-length=8
      iplanet-am-auth-ldap-server-check=15

    3. Create an equivalent instance in the destination environment (for example LDAP)

      Create authentication instance

      ssoadm create-auth-instance -u amadmin -f /home/victor/openam_tc_8080/.pass --realm / --name LDAP -t LDAP

    4. Edit the output of the get-auth-instance as needed (for example the bind password) and import in the destination system

      Import authentication instance configuration

      ssoadm update-auth-instance -u amadmin -f /home/victor/openam_tc_8080/.pass -e / -m LDAP -D LDAP_Authn

  3. Policy Configuration
    1. List the policies defined in a specific realm. Example policies in the top realm / and write the output in a file named Policies

      List policies

      ssoadm list-policies -u amadmin -f /home/victor/openam_tc_8080/.pass -e / -o Policies

    2. Edit the output of the command above, for example remove the text header
    3. Import the policies in the destination environment by using the file policies as the input to create-policies

      Import policies

      ssoadm create-policies -u amadmin -f /home/victor/openam_tc_8080/.pass -e / -X Policies

      Notice that the above command will not be executed if a policy already exists.

      If your policies are already defined and they need to be updated, do:

      Update policies

      ssoadm update-policies -u amadmin -f /home/victor/openam_tc_8080/.pass -e / -X Policies

      Notice that updating the policies will only update the existing policies and will leave untouched the ones that are not defined in the XML file

      If you want to start from scratch, delete the policies first and create them again.

      Delete policies

      ssoadm list-policies -u amadmin -f /home/victor/openam_tc_8080/.pass -e / -o Policies
      ssoadm list-policies -u amadmin -f /home/victor/openam_tc_8080/.pass -e / --namesonly -o policy_names
      ssoadm delete-policies -u amadmin -f /home/victor/openam_tc_8080/.pass -e / -D policy_names
      ssoadm create-policies -u amadmin -f /home/victor/openam_tc_8080/.pass -e / -X Policies

  4. Agent configuration
    1. List all the agents of a realm

      ssoadm list-agents -u amadmin -f /home/victor/openam_tc_8080/.pass -e /

      wsc (id=wsc,ou=agentonly,dc=example,dc=com)
      SecurityTokenService (id=SecurityTokenService,ou=agentonly,dc=example,dc=com)
      wsp (id=wsp,ou=agentonly,dc=example,dc=com)
      agentAuth (id=agentAuth,ou=agentonly,dc=example,dc=com)
      apache (id=apache,ou=agentonly,dc=example,dc=com)

      or

      List the specific web agents of a realm

      ssoadm list-agents -u amadmin -f /home/victor/openam_tc_8080/.pass -e / -t WebAgent

      apache (id=apache,ou=agentonly,dc=example,dc=com)

    2. List the agent groups of a realm

      List the agent groups of a realm

      ssoadm list-agent-grps -u amadmin -f /home/victor/openam_tc_8080/.pass -e /

      group1 (id=group1,ou=agentgroup,dc=example,dc=com)

    3. List the specific configuration of a policy agent and store the output in a file called apache_agent_output_config:

      List the specific configuration of a policy agent

      ssoadm show-agent -u amadmin -f /home/victor/openam_tc_8080/.pass -e / -b apache -o apache_agent_output_config

      ssoadm show-agent-membership -u amadmin -f /home/victor/openam_tc_8080/.pass -e / -b apache

    4. Create an agent using as input the file named apache_agent_output_config:

      Create an agent

      ssoadm create-agent -u amadmin -f /home/victor/openam_tc_8080/.pass -e / -b apacheX -t WebAgent -D apache_agent_output_config

    5. Add the agent to a group

      ssoadm add-agent-to-grp -u amadmin -f /home/victor/openam_tc_8080/.pass -e / -b group1 -s apacheX

  • No labels