Tomcat security realms

Gretty configuration supports two properties related to Tomcat security realms - "realm" and "realmConfigFile".

Tomcat security realms for a single web-app

gretty {
  // ...
  servletContainer = 'tomcat8'
  realm 'auth'
  realmConfigFile 'tomcat-realm.properties'
  // ...
}

Here "realm" property defines security realm for the given web-app. When specified, it must match /web-app/login-config/realm-name element in "web.xml".

"realmConfigFile" property defines relative or absolute path to the XML file, containing properties for MemoryRealm.

The syntax of the properties file is described in Tomcat realm how-to.

If "realmConfigFile" is not specified, Gretty looks for files "tomcat8-users.xml" (for Tomcat 8), "tomcat7-users.xml" (for Tomcat 7), "tomcat-users.xml". Tomcat version is defined by gretty.servletContainer property.

If explicitly defined realmConfigFile represents an absolute path, gretty will use just that.

If implicitly or explicitly defined realmConfigFile represents a relative path, gretty tries to resolve it in the following directories:

  • "$project.projectDir/realm"

  • "$project.projectDir/security"

  • "$project.projectDir/server"

  • "$project.projectDir/config"

  • "$project.projectDir"

  • recursively in the abovementioned folders of the overlay sources (if any)

When you generate a product, realm configuration file is copied to "conf" subdirectory and referenced in "conf/server.json". Running product uses realm and realmConfigFile, so that your web-app stays secure.

Tomcat security realms for multiple web-apps

Same realm configuration for multiple web-apps

You can define same realm configuration for all web-apps of the given farm:

farm {
  // ...
  servletContainer = 'tomcat8'
  realm 'auth'
  realmConfigFile 'tomcat-users.xml'
  webapp ':ProjectA'
  webapp ':ProjectB'
  // ...
}

In the example above two web-apps - ProjectA and projectB - are using the same realm configuration.

The same rules apply to resolution and product-packaging of realmConfigFile specified in farm, as in gretty configuration.

Individual realm configurations for multiple web-apps

If web-app has it’s own realm configuration, it is used instread of farm-wide realm configuration:

// in ProjectA:
gretty {
  realm 'auth1'
  realmConfigFile 'tomcat-realm1.properties'
}

// in farm project:
farm {
  // ...
  servletContainer = 'tomcat8'
  realm 'auth'
  realmConfigFile 'tomcat-realm.properties'
  webapp ':ProjectA'
  webapp ':ProjectB'
  // ...
}

In the example above ProjectA uses realm configuration "auth1"/"tomcat-realm1.properties", while ProjectB uses realm configuration "auth"/"tomcat-realm.properties".

When you run a farm or when you generate product from a farm, the rules for resolution and product-packaging of web-app-specific realm configurations are the following:

If "realmConfigFile" is not specified, Gretty looks for one of the files "tomcat8-users.xml" (for Tomcat 8), "tomcat7-users.xml" (for Tomcat 7), "tomcat-users.xml". Tomcat version is defined by gretty.servletContainer property.

If explicitly defined realmConfigFile represents an absolute path, gretty will use just that.

If implicitly or explicitly defined realmConfigFile represents a relative path, gretty tries to resolve it in the following directories:

  • "$project.projectDir/webapp-realm"

  • "$project.projectDir/webapp-security"

  • "$project.projectDir/webapp-config"

  • recursively in the abovementioned folders of the overlay sources (if any)

When you generate a product, realm configuration files linked to web-apps are copied to "conf/$project.name" subdirectories and referenced in "conf/server.json". Running product uses realm and realmConfigFile properties for all designated web-apps, so they stay secure.

Overriding individual realm configurations for multiple web-apps

Farm can override individual realm configurations for web-apps:

// in ProjectA:
gretty {
  realm 'auth1'
  realmConfigFile 'tomcat-realm1.properties'
}

// in ProjectB:
gretty {
  realm 'auth2'
  realmConfigFile 'tomcat-realm2.properties'
}

// in farm project:
farm {
  // ...
  servletContainer = 'tomcat8'
  realm 'auth'
  realmConfigFile 'tomcat-realm.properties'
  webapp ':ProjectA', realm: 'auth3', realmConfigFile: 'tomcat-realm3.properties'
  webapp ':ProjectB'
  webapp ':ProjectC'
  // ...
}

In the example above ProjectA uses realm configuration "auth3"/"tomcat-realm3.properties", while ProjectB uses realm configuration "auth2"/"tomcat-realm2.properties" and ProjectC uses realm configuration "auth"/"tomcat-realm.properties".

Gretty contains example programs, demonstrating use of Tomcat security realms: