Adding a custom Java callout security policy

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

What is a custom Java callout security policy?

Java callouts enable you to customize your API's behavior using Java code. When you implement a Java callout, Apigee sets default permissions for the API using Java permission policies. In Apigee hybrid, you can change the default permissions by creating a custom Java callout security policy.

Note: Custom Java callout security policies are only available in Apigee hybrid. The security policy is scoped to the environment, and there can only be one security policy in an environment.

You can create a custom Java callout security policy using a resource, which is defined in a resource file of type securityPolicy. The resource is configured at the environment level. The resource file can have any name, but you must add the suffix .policy to the custom java policy file name. For example: strict-security.policy.

The following command adds a resource file named strict-security.policy.

curl -X POST "https://apigee.googleapis.com/v1/organizations/my-organization/environments/test/resourcefiles?name=CustomJavaSecurityPolicy&type=securityPolicy"
-H "Authorization: Bearer $TOKEN" \
-H "Content-type: multipart/form-data" \
-F file=@/Users/home/strict-security.policy

Security policy files support the same syntax as standard Java security policy; see Default Policy Implementation and Policy File Syntax.

Once you have created a security policy file defining a custom Java Callout policy, Apigee runtime can detect the policy and use the custom permissions the policy defines. If no custom Java callout policy is present, Apigee uses the default security policy for custom Java or Python code.

Security policy file

The following examples show sample content of a security policy file.

The lines below specify the location of the code for a custom Java callout and grant all permissions to the directory.

Relaxed security policy file for testing
// javacallout code has just read permission in the installed dir and everything below it
  grant codeBase "file:${javacallout.dir}/-"  {
    permission java.security.AllPermission;
}

These lines specify the location of the code for a custom Jython/Python Callout and grant read permissions to the directory.

// Jython/Python secure
grant codeBase "file:${jython-secure-jar}" {
    // No logging permissions for secure jar. Hence value of the AllExcept target parameter set to 0
    permission com.apigee.securitypolicy.AllExcept "0", "java.io.FilePermission";
    permission java.io.FilePermission "{T}conf_security-policy_install.dir{/T}/lib/-" , "read";
    // Add JRE read permissions to jython. Existing permissions have two formats to java home. Keep the same.
    permission java.io.FilePermission "${java.home}/-", "read,readLink";
    permission java.io.FilePermission "${JAVA_HOME}/-", "read,readLink";
}

Examples

The following examples show how to perform specific tasks related to custom Java callout security policies.

Create a custom Java callout security policy

The following command creates a custom Java callout security policy, defined in the resource file named strict-security.policy.

curl -X POST "https://apigee.googleapis.com/v1/organizations/my-organization/environments/test/resourcefiles?name=CustomJavaSecurityPolicy&type=securityPolicy"
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-type: multipart/form-data" \
  -F file=@/Users/home/strict-security.policy

View all security policies

The following command lets you view all existing custom Java callout security policies in your API.

curl -X GET "https://apigee.googleapis.com/v1/organizations/my-organization/environments/test/resourcefiles/securityPolicy" \
  -H "Authorization: Bearer $TOKEN"

View the contents of a security policy file

The following command gets the contents of an individual security policy file so you can view it.

curl -X GET "https://apigee.googleapis.com/v1/organizations/my-organization/environments/test/resourcefiles/securityPolicy/CustomJavaSecurityPolicy" \
  -H "Authorization: Bearer $TOKEN"

Update a policy scoped to an environment

The following command updates a security policy scoped to an environment.

curl -X PUT "https://apigee.googleapis.com/v1/organizations/my-organization/environments/test/resourcefiles/securityPolicy/CustomJavaSecurityPolicy"
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-type: multipart/form-data" \
  -F file=@/Users/home/strict-security-revised.policy

Delete security policy scoped to an environment

The following command deletes a security policy scoped to an environment.

curl -X DELETE https://apigee.googleapis.com/v1/organizations/my-organization/environments/test/resourcefiles/securityPolicy/CustomJavaSecurityPolicy \
  -H "Authorization: Bearer $TOKEN"