Identity Appliance

Every time you promote an identity appliance from one environment to the other, certain tasks need to be performed due to the nature of some features like SSO protocols. In many organizations, this process must be automated and changes to the artifacts are not allowed. JOSSO 2 provides a set of tools aimed specifically to satisfy these requirements. This tutorial will focus on DEVOPS best practices related to JOSSO 2.

Prerequisites

Before starting, make sure that the following prerequisites are met.

• JOSSO 2.4.x instance

Deploying an Identity Appliance

Every time an identity appliance must be promoted to a new environment some changes need to be made to match the new execution context. A typical modification is to update the SSO server and applications host names. JOSSO provides command line tools to automate these changes when the Identity Appliance is imported in the new environment. The idea is that the initial import will modify general parameters (like service locations), then other commands can be used to complete the changes. In this example we will:

• Modify JOSSO host name for all services in the appliance

• Modify JOSSO managed application host names

• Modify external Service Provider metadata (to match the corresponding SP, i.e. production)

• Export the new SAML metadata for the current JOSSO setup

Updating Services Host Name

The following command will import an identity appliance, but at the same time it will make some changes during the process. The -m flag enables modifications. One of the key changes is the location (-l). JOSSO will replace location elements for identity services (IdPs, SPs, VPs, Execution Environments) that are not external (not managed by this identity appliance). The identity appliance name (-n), description (-d*) and name (-n) are also updated. The realm is important because we will be using external properties in our setup, this means that JOSSO will look for these properties at *$JOSSO2_HOME/etc/com.mycompany.sso.prod.cfg in this example. In the external configuration file we will store information about the users repository and external UI application for the new environment.

appliance:import-definition -m -l https://sso-prod.mycompany.com -n sso-prod -r com.mycompany.sso.prod -d 'SSO Prod' -i /export/sso-qa-1.0.32.zip

Updating Resources Locations

The next change we need to perform is to update the appliance resources with the new applications URLs for production. In our case, we have a Java application deployed in Apache Tomcat. The resource name we used in the Identity Appliance is app-1, so this is the command we need to use (notice that arguments are appliance name or id and resource name).

appliance:modify-resource -l http://www.mycompany.com/partnerapp -d 'Partnerapp Prod' sso-prod app-1

Updating External Providers Metadata

The last thing we need to modify is the SAML metadata of external SPs connected to JOSSO. This is only needed if the SPs have different settings for production, QA, etc. Let’s take a look at the modification command:

appliance:update-provider-metadata -m /tmp/sp-ext-1-saml-md.xml sso-prod sp-ext-1

Putting it all together

Now you can create your own JOSSO script to perform all these changes. In our case, the script will be named: qa-to-prod.sh and to execute it you can run the following JOSSO command:

shell:source /tmp/qa-to-prod.sh

Ideally these are the steps the shell will perform. The key commands were described above:

• Export current identity appliance

• Delete current identity appliance

• Import new identity appliance, including modifications

• Modify application locations

• Modify external providers MD

• Build/Start identity appliance

• Export key providers MD (IdP, etc)

Externalizing Configuration Options

This feature allows you to keep configuration options in an external file. These options can vary from environment to environment, making appliance promotion easier. Those settings that should be updated, like user repository connection settings, can be kept outside the appliance.

In order to enable this feature you need to access the modeling tool and open your identity appliance definition. Select the identity appliance element and access the Security tab on the properties sheet at the bottom.

By enabling the External Configuration Properties checkbox, JOSSO will automatically look for a properties file at the following location: $JOSSO2_HOME/etc/<appliance-realm>.cfg. You can specify your own file, by entering the full URL in the External Configuration File input field.

JOSSO will not create any configuration files, even when using the default name and location.

The file follows a standard java properties format: <property-name>=<property-value>, let’s take a look at our example: $JOSSO2_HOME/etc/com.mycompany.sso.prod.cfg

pre-authn.url=http://login.mycompany.com/login.aspx
db-server=10.1.1.1
db-user=users
db-password=secret

And now we can use them when configuring Identity Appliance elements:

• ${pre-authn.url}
• ${db-server}
• ${db-user}
• ${db-password}

Referring Configuration Properties

When you want to refer to a configuration property from any input field on any element, just use this syntax, where <property-name> must be replaced with a specific property available in the configuration file.

${<property-name>}

Appendix A : Appliance Related Commands

All appliance-related commands have the appliance: prefix or namespace. For parameter details, please run each command with the --help option. A list of options and arguments will be displayed.

Command	Description
activate	Activates an execution environment (application container) by installing the necessary resources and performing required configuration changes. Only required once, while installing JOSSO agents. You MUST build and start the identity appliance before running the activation. Not all environments can be fully activated by this command.
add-samlidp	Adds a new external SAML 2.0 Identity Provider to an identity appliance. The IdP is not managed by JOSSO.
add-samlsp	Adds a new external SAML 2.0 Service Provider to an identity appliance. The SP is not managed by JOSSO.
build	Builds an identity appliance, creating runtime artifacts based on the identity appliance model.
deploy	Deploys an identity appliance, without starting any services.
dispose	Moves an identity appliance to the trash can. You can then run the remove command to complete the task, or execute an undispose to recover it.
export-definition	Exports an identity appliance definition.
export-provider-metadata	Exports the metadata for a given provider, normally useful with SAML 2.0 providers (internal/external IdPs/SPs).
import-definition	Imports an identity appliance definition.
list	Lists all the available identity appliances.
modify	Modifies basic appliance information.
remove	Deletes a disposed identity appliance.
remove-samlidp	Removes a SAML 2.0 Identity Provider from the identity appliance (normally external IdPs).
remove-samlsp	Removes a SAML 2.0 Service Provider from the identity appliance (normally external SPs).
rename-provider	Renames a provider, the location element will be adjusted using the new name. This will require rebuilding the identity appliance, and exchanging metadata files again (for SAML 2.0 providers).
start	Starts an identity appliance. All identity services will be made available.
stop	Stops an identity appliance.
undeploy	Moves an identity appliance to the staged state. This allows for a build to be started.
undispose	Moves an identity appliance from the disposed to the staged state, so it can be deployed again.
update-provider-keystore	Updates a provider keystore resource. It only applies to internal providers (IdPs, SPs).
modify-resources-location	Modifies locations of multiple resources at the same time.
modify-resource	Modifies a resource location and description.