Getting started

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

This page explains how to get started using Advanced API Security for Subscription and Pay-as-you-go organizations.

Required roles

The following sections describe the required roles to perform tasks using Advanced API Security.

Required roles for security reports

The table below shows the required roles to perform tasks related to security reports.

Security Report Task	Required Role(s)
Enable or disable Advanced API Security	Apigee Organization Admin (roles/apigee.admin)
Create and view reports	Apigee Organization Admin (roles/apigee.admin) Apigee Security Admin (roles/apigee.securityAdmin)
View reports	Apigee Security Viewer (roles/apigee.securityViewer) Apigee Security Admin (roles/apigee.securityAdmin)

Required roles for risk assessment

The table below shows the required roles to perform tasks related to risk assessment.

Risk Assessment Task	Required Role(s)
Create, update, or delete a custom security profile	Apigee Security Admin (roles/apigee.securityAdmin) Apigee Organization Admin (roles/apigee.admin)
Attach or detach a security profile	Apigee Security Admin (roles/apigee.securityAdmin) Apigee Organization Admin (roles/apigee.admin)
View security scores	Apigee Security Admin (roles/apigee.securityAdmin) Apigee Security Viewer (roles/apigee.securityViewer) Apigee Organization Admin (roles/apigee.admin)
List all security profiles or get a profile	Apigee Security Admin (roles/apigee.securityAdmin) Apigee Security Viewer (roles/apigee.securityViewer) Apigee Organization Admin (roles/apigee.admin)

Required roles for abuse detection

The table below shows the required roles to perform tasks related to abuse detection.

Abuse Detection Task	Required Role(s)
View incidents in the Abuse detection UI	Apigee Security Admin (roles/apigee.securityAdmin) Apigee Security Viewer (roles/apigee.securityViewer) Apigee Organization Admin (roles/apigee.admin)

Required roles for security actions

The table below shows the required roles to perform tasks related to security actions.

Security Action Task	Required Role(s)
Create security actions	Apigee Security Admin (roles/apigee.securityAdmin) Apigee Organization Admin (roles/apigee.admin)
Update security actions configuration	Apigee Security Admin (roles/apigee.securityAdmin) Apigee Organization Admin (roles/apigee.admin)
View or list security actions	Apigee Security Admin (roles/apigee.securityAdmin) Apigee Security Viewer (roles/apigee.securityViewer) Apigee Organization Admin (roles/apigee.admin)
Check the state of enforcement	Apigee Security Admin (roles/apigee.securityAdmin) Apigee Security Viewer (roles/apigee.securityViewer) Apigee Organization Admin (roles/apigee.admin)

Note: To make the API calls described in the following sections, you need to obtain an OAuth 2.0 access token, which is passed with the calls.

Manage Advanced API Security for Subscription organizations

To use Advanced API Security as a Subscription customer, Advanced API Security must be part of your Subscription entitlements. See Apigee entitlements. To add Advanced API Security to your entitlements, contact Apigee Sales.

Note: Apigee trial organizations can include an Apigee Advanced API Security trial for the trial period. Contact Apigee Apigee Sales for information.

Once Advanced API Security is part of your entitlements, enable it in your organization:

• Get your Apigee add-ons configuration
• Enable Advanced API Security for Subscription organizations

If you are unsure whether you are using a Subscription or Pay-as-you-go Apigee organization, contact your Apigee organization administrator.

Get your Apigee add-ons configuration

In order to enable Advanced API Security for your Subscription organization, you first need to get your current Apigee add-ons configuration, using the following API call. This will also tell you whether Advanced API Security is already enabled.

curl "https://apigee.googleapis.com/v1/organizations/ORG" \
  -X GET \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer $TOKEN"

where

• ORG is the name of your organization.
• $TOKEN is the environment variable for an OAuth access token.

This call returns basic information about your organization, including a section for your Apigee add-ons configuration that begins with the line:

"addonsConfig": {

Check to see whether this section contains the following entry:

"apiSecurityConfig": {
          "enabled": true
      }

If so, Advanced API Security is already enabled in the organization. Otherwise, you need to enable it, as described next.

Enable Advanced API Security for Subscription organizations

To enable Advanced API Security in a Subscription organization with the default configuration, issue a POST request like the one shown below.

Caution: This API call overwrites the current add-ons configuration. You must include the current configuration for all add-ons in the request shown below to prevent them from being overwritten.

Notes:

• If you create a new environment after enabling Advanced API Security, you must run the command below again to enable Advanced API Security for the new environment. Note that it is not necessary to disable Advanced API Security before running the command again.
• If you simply detach an environment in which Advanced API Security is enabled from an instance, and then later reattach it, you do not need to run the command below again.

curl "https://apigee.googleapis.com/v1/organizations/ORG:setAddons" \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-type: application/json" \
  -d '{
    "addonsConfig": {
      "apiSecurityConfig": {
          "enabled": true
      }
      <Other entries of your current add-ons configuration>
    }
  }'

where

• ORG is the name of your organization.
• $TOKEN is the environment variable for an OAuth access token.
• <Other entries of your current add-ons configuration> consists of any other entries of your current Apigee add-ons configuration.

Note: The API call above starts a long running operation that may take a while to complete.

For example, if the current add-ons configuration is

"addonsConfig": {
  "integrationConfig": {
      "enabled":true
  },
  "monetizationConfig": {
      "enabled":true
  }
},

the command to enable Advanced API Security would be

curl "https://apigee.googleapis.com/v1/organizations/ORG:setAddons" \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-type: application/json" \
  -d '{
    "addonsConfig": {
      "apiSecurityConfig": {
          "enabled": true
      },
      "integrationConfig": {
          "enabled": true
      },
      "monetizationConfig": {
          "enabled": true
      }
    }
  }'

After you send the request, you will see a response like the following:

{
  "name": "organizations/apigee-docs-d/operations/0718a945-76e0-4393-a456-f9929603b32c",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.apigee.v1.OperationMetadata",
    "operationType": "UPDATE",
    "targetResourceName": "organizations/apigee-docs-d",
    "state": "IN_PROGRESS"
  }
}

Note: When you enable Advanced API Security in an organization, it can take up to a day for the scores for existing proxies and targets to be reflected in an environment.

Disable Advanced API Security for Subscription organizations

If for some reason you need to disable Advanced API Security in your Subscription organization, you can do so by issuing a POST request, passing the add-ons configuration in your request body, as shown below.

Caution: The add-ons configuration that you pass in the request body will overwrite the current add-ons configuration. View the current add-ons configuration in the Apigee organization profile and be sure to include it in the request payload.

Note: The API call below starts a long running operation that may take a while to complete.

curl "https://apigee.googleapis.com/v1/organizations/$ORG:setAddons" \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-type: application/json" \
  -d '{
    "addonsConfig": {
      "apiSecurityConfig": {
          "enabled": false
      }
     <Include current add-ons configuration>
    }
  }'

The following provides an example of the response showing that the operation is in progress:

{
  "name": "organizations/$ORG/operations/06274ffb-8940-41da-836d-781cba190437",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.apigee.v1.OperationMetadata",
    "operationType": "UPDATE",
    "targetResourceName": "organizations/$ORG",
    "state": "IN_PROGRESS"
  }
}

For more information, see the Configure organization add-ons API.

Manage Advanced API Security for Pay-as-you-go organizations

If you are a Pay-as-you-go customer, you can enable Advanced API Security as a paid add-on. For more information on enabling the Advanced API Security add-on for your Intermediate or Comprehensive Apigee environments, see Manage the Advanced API Security add-on.

If you are unsure whether you are using a Subscription or Pay-as-you-go Apigee organization, contact your Apigee organization administrator.

Next steps

Once you have enabled Advanced API Security, take a look at the following sections:

• Security reports
• Risk assessment
• Abuse detection
• Security actions