How To

How do I update property values in AM (All versions) using Amster?

Last updated Aug 8, 2018

The purpose of this article is to provide information on using Amster to update property values in AM. You can also use these concepts to help you get started with creating resources via Amster.


2 readers recommend this article

Overview

This article provides a summary of the steps involved in updating property values using Amster and also provides worked examples to help guide you through the process.

The high level steps for updating a property value are:

  1. Determine the entity to which the property you want to update belongs. All the available entities are listed in the Entity Reference. See Tips for finding which entity to update for further information.
  2. Connect to AM using Amster per User Guide › Connecting to ForgeRock Access Management.
  3. Run the read command against the entity you are interested in to return the entity details in JSON format.
  4. Copy the outputted JSON response and make the following changes:
    • Amster 5.5 only: Remove the line breaks (for example, using sed or an online tool). 
    • Edit the value of the property you want to update.
    • Remove the end of the response starting with ,"_rev" (leaving the closing curly bracket). The string to remove includes the _id field and possibly others such as _type.
  5. Run the corresponding update command against the entity, passing the edited JSON response in the body. You must enclose the JSON response in single quotes.
Note

You can also use a JSON parsing library, which allows you to do a read, update the required property and then send the update. Using a JSON parsing library is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Professional Services.

The following sections show worked examples to help you get started:

Note

You can use similar principles to create resources via Amster; it is often best to initially create the resource via the console and then do a read so you know which fields are required for future creates. Alternatively, you can do a read on a similar resource (for example, an existing realm if you want to create another realm) and then use that output as the basis of your create.

Updating a default server setting

This worked example demonstrates updating the session cookie name. From the Reference guide, we can see it is a Security property: Reference › Configuration Reference > Cookie and the corresponding property name is: com.iplanet.am.cookie.name. The corresponding entity is DefaultSecurityProperties: Entity Reference › DefaultSecurityProperties.

You can update this property as follows:

  1. Connect to AM using Amster, for example:
    $ ./amster
    
    am> connect --interactive http://host1.example.com:8080/openam
    Sign in to top level realm
    User Name: amadmin
    Password: **********
  2. Run the read command against the DefaultSecurityProperties entity, for example (exclude the --prettyPrint option in Amster 5.x):
    am> read DefaultSecurityProperties --global --prettyPrint false
    Example response:
    ===> {"amconfig.header.encryption":{"am.encryption.pwd":"@AM_ENC_PWD@","com.iplanet.security.encryptor":"com.iplanet.services.util.JCEEncryption","com.iplanet.security.SecureRandomFactoryImpl":"com.iplanet.am.util.SecureRandomFactoryImpl"},"amconfig.header.validation":{"com.iplanet.services.comm.server.pllrequest.maxContentLength":"16384","com.iplanet.am.clientIPCheckEnabled":false},"amconfig.header.cookie":{"com.iplanet.am.cookie.name":"iPlanetDirectoryPro","com.iplanet.am.cookie.encode":false,"com.iplanet.am.cookie.secure":false},"amconfig.header.securitykey":{"com.sun.identity.saml.xmlsig.keystore":"%BASE_DIR%/%SERVER_URI%/keystore.jceks","com.sun.identity.saml.xmlsig.storetype":"JCEKS","com.sun.identity.saml.xmlsig.keypass":"%BASE_DIR%/%SERVER_URI%/.keypass","com.sun.identity.saml.xmlsig.certalias":"test","com.sun.identity.saml.xmlsig.storepass":"%BASE_DIR%/%SERVER_URI%/.storepass"},"amconfig.header.crlcache":{"com.sun.identity.crl.cache.directory.searchlocs":"","com.sun.identity.crl.cache.directory.password":null,"com.sun.identity.crl.cache.directory.ssl":false,"com.sun.identity.crl.cache.directory.user":"","com.sun.identity.crl.cache.directory.searchattr":"","com.sun.identity.crl.cache.directory.host":"","com.sun.identity.crl.cache.directory.port":""},"amconfig.header.ocsp.check":{"com.sun.identity.authentication.ocsp.responder.nickname":"","com.sun.identity.authentication.ocspCheck":false,"com.sun.identity.authentication.ocsp.responder.url":""},"amconfig.header.deserialisationwhitelist":{"openam.deserialisation.classes.whitelist":"com.iplanet.dpro.session.DNOrIPAddressListTokenRestriction,com.sun.identity.common.CaseInsensitiveHashMap,com.sun.identity.common.CaseInsensitiveHashSet,com.sun.identity.common.CaseInsensitiveKey,com.sun.identity.common.configuration.ServerConfigXML,com.sun.identity.common.configuration.ServerConfigXML$DirUserObject,com.sun.identity.common.configuration.ServerConfigXML$ServerGroup,com.sun.identity.common.configuration.ServerConfigXML$ServerObject,com.sun.identity.console.base.model.SMSubConfig,com.sun.identity.console.service.model.SMDescriptionData,com.sun.identity.console.service.model.SMDiscoEntryData,com.sun.identity.console.session.model.SMSessionData,com.sun.identity.console.user.model.UMUserPasswordResetOptionsData,com.sun.identity.shared.datastruct.OrderedSet,com.sun.xml.bind.util.ListImpl,com.sun.xml.bind.util.ProxyListImpl,java.lang.Boolean,java.lang.Integer,java.lang.Number,java.lang.StringBuffer,java.net.InetAddress,java.security.cert.Certificate,java.security.cert.Certificate$CertificateRep,java.util.ArrayList,java.util.Collections$EmptyMap,java.util.Collections$EmptySet,java.util.Collections$SingletonList,java.util.HashMap,java.util.HashSet,java.util.LinkedHashSet,java.util.Locale,org.forgerock.openam.authentication.service.protocol.RemoteCookie,org.forgerock.openam.authentication.service.protocol.RemoteHttpServletRequest,org.forgerock.openam.authentication.service.protocol.RemoteHttpServletResponse,org.forgerock.openam.authentication.service.protocol.RemoteServletRequest,org.forgerock.openam.authentication.service.protocol.RemoteServletResponse,org.forgerock.openam.authentication.service.protocol.RemoteSession,org.forgerock.openam.dpro.session.NoOpTokenRestriction,org.forgerock.openam.dpro.session.ProofOfPossessionTokenRestriction"},"_rev":"570060492","_id":"null/properties/security"}
    
  3. Copy the outputted JSON response and make the following changes:
    • Amster 5.5 only: Remove the line breaks (for example, using sed or an online tool). 
    • Edit the value of the property you want to update (com.iplanet.am.cookie.name).
    • Remove the end of the response starting with ,"_rev" (leaving the closing curly bracket). The string to remove includes the _id field and possibly others such as _type. You would remove the following from the end of the response in this example:
      ,"_rev":"570060492","_id":"null/properties/security"
  4. Run the corresponding update command against the DefaultSecurityProperties entity, passing the edited JSON response in the body. You must enclose the JSON response in single quotes. For example (with the updated property highlighted in bold for reference):
    am> update DefaultSecurityProperties --global --body '{"amconfig.header.encryption":{"am.encryption.pwd":"@AM_ENC_PWD@","com.iplanet.security.encryptor":"com.iplanet.services.util.JCEEncryption","com.iplanet.security.SecureRandomFactoryImpl":"com.iplanet.am.util.SecureRandomFactoryImpl"},"amconfig.header.validation":{"com.iplanet.services.comm.server.pllrequest.maxContentLength":"16384","com.iplanet.am.clientIPCheckEnabled":false},"amconfig.header.cookie":{"com.iplanet.am.cookie.name":"NewCookie","com.iplanet.am.cookie.encode":false,"com.iplanet.am.cookie.secure":false},"amconfig.header.securitykey":{"com.sun.identity.saml.xmlsig.keystore":"%BASE_DIR%/%SERVER_URI%/keystore.jceks","com.sun.identity.saml.xmlsig.storetype":"JCEKS","com.sun.identity.saml.xmlsig.storepass":"%BASE_DIR%/%SERVER_URI%/.storepass","com.sun.identity.saml.xmlsig.keypass":"%BASE_DIR%/%SERVER_URI%/.keypass","com.sun.identity.saml.xmlsig.certalias":"test"},"amconfig.header.crlcache":{"com.sun.identity.crl.cache.directory.host":"","com.sun.identity.crl.cache.directory.ssl":false,"com.sun.identity.crl.cache.directory.user":"","com.sun.identity.crl.cache.directory.searchlocs":"","com.sun.identity.crl.cache.directory.searchattr":""},"amconfig.header.ocsp.check":{"com.sun.identity.authentication.ocspCheck":false,"com.sun.identity.authentication.ocsp.responder.url":"","com.sun.identity.authentication.ocsp.responder.nickname":""},"amconfig.header.deserialisationwhitelist":{"openam.deserialisation.classes.whitelist":"com.iplanet.dpro.session.DNOrIPAddressListTokenRestriction,com.sun.identity.common.CaseInsensitiveHashMap,com.sun.identity.common.CaseInsensitiveHashSet,com.sun.identity.common.CaseInsensitiveKey,com.sun.identity.common.configuration.ServerConfigXML,com.sun.identity.common.configuration.ServerConfigXML$DirUserObject,com.sun.identity.common.configuration.ServerConfigXML$ServerGroup,com.sun.identity.common.configuration.ServerConfigXML$ServerObject,com.sun.identity.console.base.model.SMSubConfig,com.sun.identity.console.service.model.SMDescriptionData,com.sun.identity.console.service.model.SMDiscoEntryData,com.sun.identity.console.session.model.SMSessionData,com.sun.identity.console.user.model.UMUserPasswordResetOptionsData,com.sun.identity.shared.datastruct.OrderedSet,com.sun.xml.bind.util.ListImpl,com.sun.xml.bind.util.ProxyListImpl,java.lang.Boolean,java.lang.Integer,java.lang.Number,java.lang.StringBuffer,java.net.InetAddress,java.security.cert.Certificate,java.security.cert.Certificate$CertificateRep,java.util.ArrayList,java.util.Collections$EmptyMap,java.util.Collections$EmptySet,java.util.Collections$SingletonList,java.util.HashMap,java.util.HashSet,java.util.LinkedHashSet,java.util.Locale,org.forgerock.openam.authentication.service.protocol.RemoteCookie,org.forgerock.openam.authentication.service.protocol.RemoteHttpServletRequest,org.forgerock.openam.authentication.service.protocol.RemoteHttpServletResponse,org.forgerock.openam.authentication.service.protocol.RemoteServletRequest,org.forgerock.openam.authentication.service.protocol.RemoteServletResponse,org.forgerock.openam.authentication.service.protocol.RemoteSession,org.forgerock.openam.dpro.session.NoOpTokenRestriction"}}'
  5. Restart the web application container in which AM runs to update the configuration.

Updating realm level authentication settings

This worked example demonstrates enabling client-based sessions in a realm. From the Authentication and Single Sign-On Guide, we can see it is an authentication setting: Authentication and Single Sign-On Guide › Reference › General called Use Client-based Sessions (Use Stateless Sessions in AM 5.x). The corresponding entity is Authentication: Entity Reference › Authentication and the property name is: statelessSessionsEnabled (this was found by searching the Entity Reference for 'Use Client-based Sessions' ('Use Stateless Sessions in AM 5.x')).

You can update this property as follows:

  1. Connect to AM using Amster, for example:
    $ ./amster
    
    am> connect --interactive http://host1.example.com:8080/openam
    Sign in to top level realm
    User Name: amadmin
    Password: **********
  2. Run the read command against the Authentication entity, for example (exclude the --prettyPrint option in Amster 5.x):
    am> read Authentication --realm / --prettyPrint false
    Example response:
    ===> {"core":{"adminAuthModule":"ldapService","orgConfig":"ldapService"},"userprofile":{"dynamicProfileCreation":"false","defaultRole":[],"aliasAttributeName":["uid"]},"accountlockout":{"loginFailureLockoutMode":false,"loginFailureCount":5,"loginFailureDuration":300,"lockoutWarnUserCount":0,"lockoutDuration":0,"lockoutDurationMultiplier":1,"storeInvalidAttemptsInDataStore":true},"general":{"locale":"en_US","identityType":["agent","user"],"userStatusCallbackPlugins":[],"statelessSessionsEnabled":false,"twoFactorRequired":false,"defaultAuthLevel":0},"trees":{"authenticationSessionsStateManagement":"JWT","authenticationSessionsWhitelist":false,"authenticationSessionsMaxDuration":5},"security":{"moduleBasedAuthEnabled":true,"keyAlias":"test","zeroPageLoginEnabled":false,"zeroPageLoginReferrerWhiteList":[],"zeroPageLoginAllowedWithoutReferrer":true},"postauthprocess":{"loginSuccessUrl":["/openam/console"],"loginFailureUrl":[""],"loginPostProcessClass":[],"usernameGeneratorEnabled":true,"usernameGeneratorClass":"com.sun.identity.authentication.spi.DefaultUserIDGenerator","userAttributeSessionMapping":[]},"_rev":"-1312682552","_type":{"_id":"EMPTY","name":"Core","collection":false},"_id":""}
    
  3. Copy the outputted JSON response and make the following changes:
    • Amster 5.5 only: Remove the line breaks (for example, using sed or an online tool). 
    • Edit the value of the property you want to update (statelessSessionsEnabled).
    • Remove the end of the response starting with ,"_rev" (leaving the closing curly bracket). The string to remove includes the _id field and possibly others such as _type. You would remove the following from the end of the response in this example:
      ,"_rev":"-1312682552","_type":{"_id":"EMPTY","name":"Core","collection":false},"_id":""
  4. Run the corresponding update command against the Authentication entity, passing the edited JSON response in the body. You must enclose the JSON response in single quotes. For example (with the updated property highlighted in bold):
    am> update Authentication --realm / --body '{"core":{"adminAuthModule":"ldapService","orgConfig":"ldapService"},"userprofile":{"dynamicProfileCreation":"false","defaultRole":[],"aliasAttributeName":["uid"]},"accountlockout":{"loginFailureLockoutMode":true,"loginFailureCount":5,"loginFailureDuration":300,"lockoutWarnUserCount":0,"lockoutDuration":0,"lockoutDurationMultiplier":1,"storeInvalidAttemptsInDataStore":true},"general":{"locale":"en_US","identityType":["agent","user"],"userStatusCallbackPlugins":[],"statelessSessionsEnabled":true,"twoFactorRequired":false,"defaultAuthLevel":0},"security":{"moduleBasedAuthEnabled":true,"keyAlias":"test","zeroPageLoginEnabled":false,"zeroPageLoginReferrerWhiteList":[],"zeroPageLoginAllowedWithoutReferrer":true},"postauthprocess":{"loginSuccessUrl":["/openam/console"],"loginFailureUrl":[],"loginPostProcessClass":[],"usernameGeneratorEnabled":true,"usernameGeneratorClass":"com.sun.identity.authentication.spi.DefaultUserIDGenerator","userAttributeSessionMapping":[]}}'

Tips for finding which entity to update

The Entity Reference has a full list of entities you can update and includes the JSON schema, which details the properties. In order to update a property, you need to know the property name and the corresponding entity. The following tips should help you find this information:

See Also

How do I enable debug mode for troubleshooting Amster (All versions)?

FAQ: Installing and using Amster in AM

Using Amster in AM

User Guide

Entity Reference

Related Training

N/A

Related Issue Tracker IDs

OPENAM-12092 (Prettyprint for Amster should be a switch)

OPENAM-11813 (Amster documentation needs improving)

OPENAM-10641 (Prettyprint for responses would be great for Amster output)



Copyright and TrademarksCopyright © 2018 ForgeRock, all rights reserved.
Loading...