Technical Note: Host Name Changes in a Sun Java™ System Access Manager 7.1 WAR Deployment describes the configuration changes that need to be made to an Access Manager system when there are changes to host or domain names of the core servers.
It contains the following sections:
Changing the Host Machine Name or Domain in an Access Manager Deployment
Changing the Host Machine Name or Domain in Access Manager Deployed in a Federation Environment
This document is relevant only when using the software specified below as the mechanism for making changes or the properties to be changed may be different between versions of the software.
Sun Java System Access Manager 7.1 (WAR Download Only)
Sun Java System Web Server 7.0
Sun Java System Directory Server 6.0
The following procedures explain the modifications you need to make to an Access Manager configuration when the host machine name or domain changes.
To Change the Host Machine Name in an Access Manager Deployment
To Change the Host Machine Name or Domain in the Access Manager Configuration Data Store
To Change the Host Machine Name or Domain in the Access Manager Session Data Store
To Change the Host Machine Name or Domain in the Access Manager Authentication Data Store
To Change the Host Machine Name or Domain in the Access Manager User Data Store
To Change the Host Machine Name or Domain in the Access Manager Policy Data Store
The following procedure explains what you need to modify in an Access Manager deployment when the name of the machine on which Access Manager is hosted changes.
Stop Access Manager.
Delete the bootstrap file.
# rm user_home/AccessManager/* |
where user_home is the home directory of the UNIX user under which the Access Manager web container is running.
Copy the value of the am.encryption.pwd property from AMConfig.properties.
am.encryption.pwd=eza2p5sYo+19hlzeZPynfOk+g89JUbRS
Delete the sample identities created by the Identity Repository Service when Access Manager is deployed.
By default, context-root is amserver.
Change to the agent directory.
# cd AM-Config-Dir/context-root/idRepo/agent/ |
Remove the following.
# rm LibertyBearerTokenWSP LibertySAMLTokenWSP LibertyX509TokenWSP LocalDiscoDiscovery SAML-HolderOfKeyWSP SAML-SenderVouchesWSP UserNameTokenWSP wscWSC wspWSP X509TokenWSP |
Change to the realm directory.
cd AM-Config-Dir/context-root/idRepo/realm/ |
Remove the following.
# rm ContainerDefaultTemplateRole |
Change to the user directory.
cd AM-Config-Dir/context-root/idRepo/user/ |
Remove the following.
# rm jondoe jsmith |
Start Access Manager.
Using a browser, go to the Access Manager URL using the new host machine name: http://new_FQDN_AM_host:port/amserver.
You will be redirected to the Access Manager configuration page. After redirection, verify that the URL in the Location bar reflects the new host name.
Fill in the details on the configuration page displayed.
Be sure of the following:
Verify that the value of the Server URL correctly reflects the new host name.
Paste the encryption password you previously copied as the value of the Encryption Key.
Click Configure to submit the form.
A message confirming a successful configuration will be displayed and you will be redirected to the Access Manager console to login.
Login to the Access Manager console as amadmin.
If configuration has failed or you are unable to login, troubleshoot the issue by looking at the logs from the web container that hosts Access Manager and the debug logs from Access Manager itself.
Make the following changes to the Access Manager Platform Service.
Make the following changes to the top-level realm.
Follow the instructions in To Change the Domain in an Access Manager Deployment, if applicable.
Log out of the Access Manager console.
The following procedure explains what you need to modify in an Access Manager deployment when the domain in which the machine on which Access Manager is hosted changes.
Login to the Access Manager console as amadmin.
Click the Configuration tab.
Click System Properties.
Click Platform.
Add the new Access Manager domain name as a new value to the Cookie Domains attribute.
Click Save to save the changes.
Follow the instructions in To Change the Host Machine Name in an Access Manager Deployment, if applicable.
Log out of the Access Manager console.
The following procedure explains what you need to modify in the Access Manager configuration data store when the host machine name or domain in which the machine on which Access Manager is hosted changes.
To change the host machine name in the configuration data store, follow steps 1 through 7 in To Change the Host Machine Name in an Access Manager Deployment.
Enter the domain in which the configuration data store is installed as the value in the Directory Server Settings field on the new Access Manager configuration page.
Click Configure to submit the form.
A message confirming a successful configuration will be displayed and you will be redirected to the Access Manager console to login.
Sun Java System Message Queue is used by Access Manager to implement session failover. Part of the installation process includes installing the Berkeley DB as a session data store. The following procedure explains what you need to modify in this session data store when the host machine name or domain in which the machine on which Access Manager is hosted changes.
Login to the Access Manager console as amadmin.
Click the Configuration tab.
Click Global Properties.
Click Session.
Change the host name of the session data store under Secondary Configuration Instance.
Click Save to save the changes.
Log out of the Access Manager console.
The following procedure explains what you need to modify in a configured Access Manager authentication data store when the host machine name or domain in which the machine on which Access Manager is hosted changes.
Login to the Access Manager console as amadmin.
Click the Access Control tab.
Click the name of the top-level realm.
Click Authentication.
Click Module Instances.
Click the name of the relevant instance(s) and make the appropriate changes to the configured host machine name and domain.
Click Save to save the changes.
Log out of the Access Manager console.
Login to the Access Manager console as amadmin.
Click the Access Control tab.
Click the name of the top-level realm.
Click Data Stores.
Click the name of the relevant data store(s) and make the appropriate changes to the configured host machine name and domain.
Click Save to save the changes.
Log out of the Access Manager console.
Login to the Access Manager console as amadmin.
Click the Access Control tab.
Click the name of the top-level realm.
Click Services.
Click Policy Configuration.
Make changes to the host machine name and domain configured in the appropriate attributes.
Click Save to save the changes.
Log out of the Access Manager console.
If the host machine name or domain is configured in an instance of Access Manager that acts as an identity provider or service provider in a federation environment, the following changes also need to be made, depending upon the federation protocol used.
You only need to change the hosted or remote entities that contain a host machine name or domain that has changed, For example, if the host name of machine A has changed, you need to change the metadata for all entities hosted on machine A. If the metadata for those entities hosted on machine A was imported to machine B, you also need to change the remote metadata (for A) on machine B.
By default, saml2meta, the command line utility used in this section, uses the top-level realm as input when the --realm option is not defined. If you are making changes to a sub-realm, use the --realm option with a value of /sub-realm-name.
If the host machine name or domain is configured in an instance of Access Manager that acts as an identity provider or service provider in a SAML v2 environment, use this procedure. As Access Manager has no console support for SAML v2, changes to the URLs configured in the metadata files need to be made on the command-line on both the identity provider and the service provider sides.
Run the following command to export the standard and extended metadata from the identity provider machine.
# /opt/SUNWam/saml2/bin/saml2meta export --runasdn amadmin --password passwd-for-amadmin --realm realm-name --entityid "IDP-OLD-FQDN" --metadata /tmp/metadata.xml --extended /tmp/ext_metadata.xml |
If you receive the following exception:
com.iplanet.sso.SSOException: Invalid sessionid formatjava.lang.IllegalArgumentException: Invalid server id in session id com.iplanet.services.naming. ServerEntryNotFoundException: Cannot find server. at com.iplanet.sso.providers.dpro.SSOProviderImpl. createSSOToken(SSOProviderImpl.java:177) at com.iplanet.sso.SSOTokenManager.createSSOToken(SSOTokenManager.java:305) at com.sun.identity.authentication.AuthContext.getSSOToken(AuthContext.java:1070)
append the following line to AMConfig.properties, restart Access Manager, and run the saml2meta export again.
com.iplanet.am.naming.ignoreNamingService=true
Run the following command to delete the standard and extended metadata just exported from the identity provider machine.
# /opt/SUNWam/saml2/bin/saml2meta delete --runasdn amadmin --password passwd-for-amadmin --realm realm-name --entityid "IDP-OLD-FQDN" Descriptor and config for entity "IDP-OLD-FQDN" was deleted successfully. |
Change all occurrences of "IDP-OLD-FQDN" to "IDP-NEW-FQDN" in the exported files, /tmp/metadata.xml and /tmp/ext_metadata.xml.
Run the following command to import the modified metadata files to the identity provider.
# /opt/SUNWam/saml2/bin/saml2meta import --runasdn amadmin --password passwd-for-amadmin --realm realm-name --entityid "IDP-OLD-FQDN" --metadata /tmp/metadata.xml --extended /tmp/ext_metadata.xml File "/tmp/metadata.xml" was imported successfully. File "/tmp/ext_metadata.xml" was imported successfully. |
Run the following command to export the standard and extended metadata from the service provider machine.
# /opt/SUNWam/saml2/bin/saml2meta -i /var/opt/SUNWam/fm/war_staging export --runasdn amadmin --password passwd-for-amadmin --entityid "IDP-OLD-FQDN" --metadata /tmp/metadata.xml --extended /tmp/ext_metadata.xml Entity descriptor was exported to file "/tmp/metadata.xml" successfully. Entity config was exported to file "/tmp/ext_metadata.xml" successfully. |
Run the following command to delete the standard and extended metadata from the service provider machine.
# /opt/SUNWam/saml2/bin/saml2meta -i /var/opt/SUNWam/fm/war_staging delete --runasdn amadmin --password passwd-for-amadmin --entityid "IDP-OLD-FQDN" Descriptor and config for entity "IDP-OLD-FQDN" was deleted successfully. |
Change all occurrences of "IDP-OLD-FQDN" to "IDP-NEW-FQDN" in the files exported from the service provider machine, /tmp/metadata.xml and /tmp/ext_metadata.xml.
Run the following command to import the modified metadata files to the service provider.
# /opt/SUNWam/saml2/bin/saml2meta -i /var/opt/SUNWam/fm/war_staging import --runasdn amadmin --password passwd-for-amadmin --metadata /tmp/metadata.xml --extended /tmp/ext_metadata.xml File "/tmp/metadata.xml" was imported successfully. File "/tmp/ext_metadata.xml" was imported successfully. |
If the host machine name or domain is configured in an instance of Access Manager that acts as an identity provider or service provider in a Liberty Alliance Project Identity Federation Framework (Liberty ID-FF) environment, use this procedure to make changes to the following:
Entity descriptors on the identity provider and service provider sides
Discovery Service
Liberty Personal Profile Service on the Access Manager system where the Discovery Service is hosted
Login to the Access Manager console as amadmin.
Change the entity descriptor files.
Make changes to the Discovery Service.
From the Access Manager console home page, click the Web Services tab.
Click Discovery Service.
Change the host name in the Provider ID URL.
Click the Provider ID under Classes for ResourceID Mapper Plug-in.
Change the host machine name in the Provider ID attribute and click Save.
Click the configured Service Type entry name under Resource Offerings for Bootstrapping.
Change the host machine name in the Provider ID attribute and click Save.
Click Edit for the entry under Service Description.
Change the host machine name in the value of the End Point URL attribute.
Click Save to save the changes.
Make changes to the Liberty Personal Profile Service.
Log out of the Access Manager console.
If the host machine name or domain is configured in an instance of Access Manager that acts as an identity provider or service provider in a SAML v1 environment, use this procedure to make the appropriate changes.
Login to the Access Manager console as amadmin.
Click the Federation tab.
Click the SAML tab.
Click the Instance ID of the relevant entry under Site Identifier.
Change the host machine name in the value of the Instance ID and Issuer Name attributes.
Click Save to save the changes.
Click Save on the SAML Profile page.
Click the Instance ID of the relevant entry under Trusted Partners, if applicable.
Change the host machine name in the URL endpoints of the relevant entries in the list of Trusted Partners.
Click Save to save the changes.
Click Save on the SAML Profile page.
Log out of the Access Manager console.