Applying Plans to you APIs

Introduction

To expose your API to internal or external consumers, it must have at least one plan. A plan provides a service and access layer on top of your API that specifies access limits, subscription validation modes, and other configurations to tailor it to an application. Example access scenarios APIM can manage with plans include:

• Read-only access and limited request traffic for potential customers to discover and try out your APIs
• Premium access with public resources and access limits for your partners
• Unlimited access to your internal enterprise applications

Each plan must include at least one security type by which subscribers can be authenticated. A security type is a policy integrated directly into a plan. Once a plan is created, the security type can not be changed. However, you can add additional security at the API or plan level with policies.

The sections below describe:

• How to create a plan
• How to publish a plan
• How plans are selected

Create a plan

To create a plan:

1. Log in to your APIM Console

2. Select APIs from the left nav

3. Select your API

4. Select Consumers from the inner left nav

5. Under the Plans header tab, click + Add new plan and select your plan security type:

   

6. Configure the general plan settings:

   

   • Name: Enter a name for your plan
   • Description: Enter a description of your plan
   • Characteristics: Define labels used to tag your plan
   • Page of General Conditions: Select a published Documentation page whose terms must be accepted by the user to finalize the subscription process
   • Toggle Auto validate subscription ON to accept all subscriptions to a plan without the API publisher's approval
   • Toggle Consumer must provide a comment when subscribing to the plan ON to require an explanation for the subscription request, with the option to leave a Custom message to display to consumer
   • Sharding tags: Selectively deploy the plan to particular APIs using available sharding tags
   • Groups excluded: Prevent specified user groups from accessing your plan

7. Click Next

8. Define the security configuration details appropriate to and required by your selected security type, e.g., OAuth2.

   

9. Select any plan restrictions:

   

   • Rate limiting: Intended to help avoid unmanageable spikes in traffic by limiting the number of requests an application can make in a given time period.
   • Quota: Limits the number of requests an application can make in a given time period. Generally used to tier access to APIs based on subscription level.
   • Resource Filtering: Limits access to API resources according to whitelist and/or blacklist rules.

10. Click Create

Plan stages

A plan can exist in one of four stages: STAGING, PUBLISHED, DEPRECATED, and CLOSED:

Depending on the stage it's in, a plan can be edited, published, deprecated, or closed via the icons associated with it:

To edit a plan, click on the pencil icon:

To publish a plan, click on the icon of a cloud with an arrow:

Once a plan has been published, it must be redeployed.

To deprecate a plan, click on the icon of a cloud with an 'x':

To close a plan, click on the 'x' icon:

Plan selection rules

APIM automatically routes each API request to the correct plan. The plan selection workflow parses all published plans in the following order: JWT, OAuth2, API Key, Keyless.

The parsing rules for each plan type are detailed below:

The parsed plan is selected for execution if all the following conditions are met:

• The request contains a token corresponding to the plan type (e.g., an X-DSAPI-Api-Key header for an API Key plan)
• The plan condition rule is valid or not set
• There is an active subscription matching the incoming request

mTLS

mTLS plans overview

The mTLS authentication type enforces the use of a client certificate to connect to an API. The client certificate is added to an application, and then a subscription is created for that application. At runtime, the gateway checks that an incoming request contains a client certificate matching one associated with an application that has an active subscription.

You can use the mTLS with or without TLS enabled between the client and the gateway. The gateway server can require client authentication, which uses the truststore at the server level to determine which clients to trust. The mTLS plan checks the client certificate with the gateway-level TLS. The client certificate is either found in either of the following locations:

• The TLS session between the client and the gateway
• In a pre-specified header in plaintext, base64-encoded.

This can be done if a load balancer is placed in front of the gateway that terminates TLS. For more information about the configuration, See configuration.

Limitations

mTLS plans have the following limitations:

• You can apply mTLS plans to only v4 APIs.
• You cannot use mTLS plans in DSAPI Cloud.
• Only one client certificate can be added per application. This means that to rotate certificates for an application, you need to pause the application’s subscriptions or schedule a maintenance window to avoid traffic for that API.
• Applications do not provide a warning that certificates are going to expire.

Adding a Client Certificate to an Application

To subscribe to an mTLS plan, the client must add a certificate to their application. To add a certification to an application, complete the following steps:

1. In the console, navigate to Applications, and then click a specific application.
2. For that application, click the setting the Tls Configuration. The client certificate is pasted in base64-encoded format.

When you add a client certificate to an application, the gateway adds this application to its truststore. At runtime, the gateway checks whether the truststore has a certificate that matches an application with a valid subscription for the API.

Calling an API with mTLS

Before you begin

• You must have the client certificate
• You must have the private key

Procedure

• To call an API with mTLS, use the following command:

$ curl –-cert  <client.cer> --key <client.key> https://my-gateway.com/mtls-api
    

• Replace <client.cer> and <client.key> with the name of the files where you have stored your client certificate and the file where you have stored the client key.

Also, this requires that your client trusts the certificate sent by the gateway.

Terminating TLS in front of the Gateway

To run a load balancer in front of the gateway like NGINX, and then terminate TLS at the load balancer. The load balancer forwards traffic to the gateway in plaintext. To use the mTLS plan in this situation, you can set a gateway configuration. For example:

http:
      # ...
      ssl:
        clientAuthHeader:
          name: X-DSAPI-Client-Cert
    

When executing an mTLS plan, the gateway checks if TLS is enabled. If it is enabled, the gateway uses the certificate from the TLS handshake , which occurs before plan selection. If TLS is not enabled, it checks for the certificate in the header. If the header contains a valid base64-encoded plaintext certificate matching a certificate for a subscribed application, the request will succeed.

Ensure that when you use this option that only trusted parties can set this header. If using a load balancer, it must be solely responsible for setting this header. In this setup, the gateway should only be directly accessible through the load balancer.

Types of plans

Plans provide a service and access layer on top of your API that specifies access limits, subscription validation modes, and other configurations to tailor it to an application. Here are the plans that you can apply to your APIs:

API Key

Introduction

The API key authentication type enforces verification of API keys during request processing, allowing only applications with approved API keys to access an API. This plan type ensures that API keys are valid, i.e., not revoked or expired, and are approved to consume the specific resources associated with the API.

Configuration

An API Key plan offers only basic security, acting more like a unique identifier than a security token.

• Propagate API Key to upstream API: Toggle ON to ensure the request to the backend API includes the API key header sent by the API consumer. This is useful for backend APIs that already have integrated API key authentication.
• Additional selection rule: Allows you to use DSAPI Expression Language (EL) to filter plans of the same type by contextual data (request headers, tokens, attributes, etc.). For example, if there are multiple API key plans, you can set different selection rules on each plan to determine which plan handles each request.

API Key generation

By default, API keys are randomly generated for each subscription, but DSAPI also offers custom API key generation and shared API key generation. Both of these settings can be enabled at the environment level:

1. Log in to your APIM Console

2. Select Settings from the left nav

3. Select Settings from the inner left nav:

   

Custom API key

You can specify a custom API key for an API Key plan. This is particularly useful when you want to silently migrate to APIM and have a pre-defined API key. When prompted, you can choose to provide your custom API key or let APIM generate one for you by leaving the field empty.

The custom API key must have between 8 and 64 characters and be URL-compliant. ^ # % @ \ / ; = ? | ~ ,and the 'space' character are invalid.

You can provide a custom API key when:

• Creating a subscription

  

• Accepting a subscription

• Renewing a subscription

  

Shared API key

The shared API key mode allows consumers to reuse the same API key across all API subscriptions of an application. On their application's second subscription, the consumer is asked to choose between reusing their key across all subscriptions or generating one different API key for each subscription (default). This is known as the application API key type, which cannot be modified.

Shared API key limitations

API keys can only be shared across API Key plans that belong to distinct Gateway APIs. If you attempt to subscribe to two API Key plans on the same Gateway API, no prompt will be made to choose the application API key type and the default mode will be used automatically.

To select the API key type, the shared API key mode must be enabled before creating an application. To enable this option, create a new application and subscribe to two API Key plans.

If shared API key mode is disabled, applications that have already been configured to use a shared key will continue to do so, but consumers will no longer be asked to choose between modes on their second subscription.

Modifying shared API keys

A shared API key may be used to call APIs that are owned by other API publishers. Consequently:

• Shared API keys cannot be edited from an API publisher's subscriptions

• API publishers can read shared API keys, but cannot renew or revoke them

  

• Shared API keys can only be renewed/revoked by the application owner, from the subscription view of their APIM Console or Developer Portal

  

  

OAuth2

Introduction

OAuth 2.0 is an open standard that applications can use to provide client applications with secure, delegated access. OAuth 2.0 works over HTTPS and authorizes devices, APIs, servers, and applications via access tokens instead of credentials.

The OAuth2 authentication type checks access token validity during request processing using token introspection. If the access token is valid, the request is allowed to proceed. If not, the process stops and rejects the request.

Configuration

To configure an OAuth2 plan, you must first create an OAuth2 client resource that represents your OAuth 2.0 authorization server.

Configuring an OAuth2 plan presents the following options:

• OAuth2 resource: Enter the name of the OAuth2 resource to use as the authorization server

• Cache resource: Optionally enter the name of the cache resource to store responses from the authorization server

• Extract OAuth2 payload: Allows the OAuth2 payload to be accessed from the oauth.payload context attribute via DSAPI Expression Language (EL) during request/response, e.g. using:

  {#context.attributes['oauth.payload']}
      

• Check scopes: An authorization server can grant access tokens with a scopes parameter, which the Gateway will check against the provided Required scopes to determine if the client application is allowed to access the API

• Mode strict: When disabled, the Gateway will validate the API call if the access token contains at least one scope from the Required scopes list. When enabled, strict mode requires the access token to contain all scopes from the Required scopes list.

• Permit authorization header to the target endpoints: Propagate the header containing the access token to the backend APIs

• Additional selection rule: Allows you to use the EL to filter by contextual data (request headers, tokens, attributes, etc.) for plans of the same type (e.g., for two OAuth2 plans, you can set different selection rules on each plan to determine which plan handles each request)

Once OAuth2 configuration is complete and the plan is created and published, your API will be OAuth2-secured and subscribed consumers must call the API with an Authorization Bearer :token: HTTP header to access the API resources.

Subscription requirements

During the OAuth2 plan selection, a token introspection is completed to retrieve the client_id which allows searching for a subscription. Any applications wanting to subscribe to an OAuth2 plan must have an existing client with a valid client_id registered in the OAuth 2.0 authorization server. The client_id will be used to establish a connection between the OAuth 2.0 client and the APIM consumer application.

To mitigate performance concerns, a cache system is available to avoid completing the same token introspection multiple times. If there are multiple OAuth2 plans, it is recommended to use selection rules to avoid any unnecessary token introspection.

JWT

Introduction

A JSON Web Token (JWT) is an open method for representing claims securely between two parties. It is digitally signed using an HMAC shared key or RSA public/private key pair. The JWT authentication type ensures that a JWT issued by a third party is valid by verifying its signature and expiration date. Only applications with approved JWTs can access APIs associated with a JWT plan.

Configuration

APIM uses client IDs to recognize applications that have subscribed to a JWT plan. The inbound JWT payload must include the client_id claim to establish a connection between the JWT and the APIM application subscription.

A JWT plan presents the following configuration options:

• Signature: Select the algorithm used to hash and encrypt your JWT

• JWKS resolver: Select a method to retrieve the JSON Web Key (JWK), which is often stored inside a JSON Web Key Set (JWKS) and required by the Gateway to validate the signature of the JWT:

  • GIVEN_KEY: Provide a signature key as a resolver parameter according to the signature algorithm (ssh-rsa, pem, crt or public-key format

  • GATEWAY_KEYS: Search for public keys set in the API Gateway DSAPI.yml configuration that match the authorization server iss (issuer) and kid (key ID) claims of the incoming JWT

    jwt:
          issuer:
            my.authorization.server:
              default: ssh-rsa myValidationKey anEmail@domain.com
              kid-2016: ssh-rsa myCurrentValidationKey anEmail@domain.com
        

  • JWKS_URL: Provide a URL ending with /.well-known/jwks.json from which the Gateway can retrieve the JWKS

• Use system proxy: When using JWKS_URL, optionally make the HTTP call through a system-wide proxy configured in DSAPI.yml

• Extract JWT Claims: Allow claims to be accessed in the jwt.claims context attribute during request/response via DSAPI Expression Language (EL), e.g., extract the issuer claim from the JWT:

  {#context.attributes['jwt.claims']['iss']}
      

• Propagate Authorization header: Propagate the header containing the JWT token to the backend APIs

• User claim: Set the payload claim where the user can be extracted. The default sub value is standard with JWTs.

• Client ID claim: Override the default claim where the client ID can be extracted. By default, the Gateway checks the azp claim, then the aud claim, and finally the client_id claim.

• Ignore missing CNF: Ignores CNF validation if the token doesn't contain any CNF information

• Enable certificate bound thumbprint validation: Validates the certificate thumbprint extracted from the access_token against the one provided by the client

• Extract client certificate from headers: Extracts the client certificate from the request header (provided in Header name field). Necessary when the mTLS connection is handled by a proxy.

• Additional selection rule: Allows you to use the EL to filter by contextual data (request headers, tokens, attributes, etc.) for plans of the same type (e.g., for two JWT plans, you can set different selection rules on each plan to determine which plan handles each request)

Once JWT configuration is complete and the plan is created and published, your API will be JWT-secured and subscribed consumers must call the API with an Authorization: Bearer your-JWT HTTP header.

Creating and managing applications

Introduction

To access DSAPI APIs, consumers must register an application and subscribe to a published API plan. Applications act on behalf of the user to request tokens, provide user identity information, and retrieve protected resources from remote services and APIs.

This page contains the following sections:

• Prerequisites
• Default application configuration
• Manage applications

Prerequisites

For an API consumer to create an application:

• An admin must define the allowed types of applications that API consumers can create:
  • Default application type: API consumers can optionally define the client_id when creating a simple application.
  • Dynamic Client Registration (DCR) for applications: The API publisher must enable and configure DCR for the allowed application types. The client registration provider is responsible for creating the client_id and client_secret for each application that registers.
• An API consumer must have a user account to register an application and subscribe to an API (see Administration)

Default application configuration

The default simple application enables an API consumer to define the client_id for use in JWT and OAuth API plans. To allow API consumers to create a simple application:

1. Log in to your APIM Console

2. Select Settings from the left nav

3. Select Client Registration from the inner left nav

   

4. Under Default application type, toggle Simple ON

user:
    login:
       # Create a default application when user connects to the portal for the very first time (default true)
       defaultApplication: false

Manage applications

An application is usually shared through a developer application and retrieves information such as API keys and API analytics. Initially, only the application’s creator can view and manage the application. By default, APIM includes three membership roles:

Delete and restore applications

To delete an application, the primary owner must:

1. Log in to your APIM Console

2. Select Applications from the left nav

3. Select your application

4. Select Global Settings from the inner left nav

5. In the Danger Zone, click Delete

   

• A deleted application has a status of ARCHIVED, meaning:
  • The link to the primary owner of the application is deleted.
  • Its subscriptions are closed. In the case of a subscription to an API Key plan, the keys are revoked.
  • Notification settings are deleted.
• An ADMINcan restore applications in the APIM Console and will become the primary owner of the application
  • An application’s subscriptions will be restored withPENDING status. The API publisher must manually reactivate previous subscriptions.

Managing and transferring Subscriptions

Introduction

A subscription is a successful contract between an API publisher and an API consumer. A subscription is created when an API consumer uses a registered application to make a subscription request to a published plan and an API publisher either manually or automatically validates the subscription.

This page includes the following sections:

• Subscription requests
• Manage subscriptions
• Transfer subscriptions

Subscription requests

API consumers can subscribe to APIs with published plans during the application creation process, or after the application is created, through the APIM Console or Developer Portal.

To subscribe to an API via the APIM Console:

1. Log in to your APIM Console

2. Select Applications from the left nav

3. Select Subscriptions from the inner left nav

4. Click the + Create a subscription button

   

5. Search for the API you want to subscribe to. To be searchable the API consumer must have access to the API, i.e., the API must be public or the API consumer must be a member of it.

6. Select the plan you would like to request a subscription to

   

7. Click Create to see the subscription details

Manage subscriptions

When creating a plan, you can enable subscription auto-validation to immediately approve subscription requests. If Auto validate subscription is disabled, the API publisher must approve all subscription requests.

To manage subscriptions in APIM Console:

1. Log in to your APIM Console
2. Select APIs from the left nav
3. Select the API with subscriptions to manage
4. Select Consumers from the inner left nav
5. Click the Subscriptions header tab
6. Select the request or subscription you want to manage
7. Validate or reject the subscription

   • If validating, fill out the Validate your subscription form, then click Validate

     

API Key plans

Subscriptions to API Key plans include additional security management settings:

• Renew: Generate a new API key or provide a custom API key. The existing API key will be automatically invalidated after two hours.

  

• Revoke: Immediately invalidate an existing API key. This option is reversible.

  

• Expire: Set a date/time to automatically invalidate an existing API key

  

Transfer subscriptions

API publishers can transfer active subscriptions to a new plan with the same security type:

1. Log in to your APIM Console

2. Select APIs from the left nav

3. Select the API with the subscription to transfer

4. Select Consumers from the inner left nav

5. Click the Subscriptions header tab

6. Click the pencil icon of the subscription you want to transfer

7. At the bottom of the Subscription details section, click Transfer

   

8. Select the plan to transfer the subscription to, then click Transfer

   

API Measurement, Tracking, and Analytics

DSAPI offers several options for measuring, tracking, and analyzing APIs to easily maintain visibility into performance and consumption.

Dashboards

Overview

The DSAPI Dashboard is an area in the UI where you can create custom dashboards reflecting API performance, status, lifecycle stage, etc. The Dashboard is comprised of 3 modules: Overview, APIs health-check, and My tasks.

• Overview: Shows a summary of API metrics for the selected time interval via configurable charts and information, followed by a paginated list of API events
• APIs health-check: Shows API status and availability data based on filter criteria and the selected time interval
• My tasks: Starting with the most recent, shows the list of tasks to be validated

Create a dashboard

You can configure your DSAPI Dashboard by creating dashboard charts for three different categories: Platform, API, and Applications. To create a chart:

1. Log in to your APIM Console

2. Click on Settings in the left nav

3. Click on Analytics in the inner left nav

4. Choose to ADD A NEW PLATFORM DASHBOARD, ADD A NEW API DASHBOARD, or ADD A NEW APPLICATION DASHBOARD

   

5. Define your Dashboard name and Query filter (optional), then click SAVE

   

6. Click the plus icon at the bottom of the screen to add a widget

7. Click the pencil icon to configure the widget:

   

   • Give your widget a Name and (optionally) a Subtitle
   • Select a Widget type from the drop-down menu, e.g., table
   • Select a Field from the drop-down menu, e.g., API, or use a custom field
   • Choose the information to display for your selected field
   • Clice SAVE

8. (Optional) Click ENABLE PREVIEW to preview your new dashboard and widget

View your dashboard

To view your new dashboard and chart:

1. Log in to your APIM Console

2. Click on Analytics in the left nav

3. Under the Dashboard header, select your dashboard from the Select a dashboard drop-down menu

   

Edit an existing dashboard

To modify existing dashboards:

1. Log in to your APIM Console
2. Click on Settings in the left nav
3. Click on Analytics in the inner left nav
4. Click on the hyperlink of an existing dashboard
5. Use the pencil icons to edit widget settings, or the plus icon to add a new widget
6. Click SAVE

API Quality

Overview

The DSAPI API Quality feature enables API governance by allowing you to create and automatically assign customizable scores based on certain variables determined to impact API quality. If API Quality is enabled, APIs that you create in DSAPI will automatically be assigned an API quality score.

Configure API Quality

API Quality is configured at the Portal Settings level. To access these settings:

1. Log in to your API Management Console.

2. Select Settings from the left nav.

3. Select API Quality from the inner left nav

4. Configure pre-built quality characteristics that DSAPI automatically enforces:

   

   • Enable API review: Toggle ON to build API Quality review into your workflow and not allow an API to be published without review
   • Enable API Quality Metrics: Toggle ON to enable quality to be measured and viewable within an APIs details
   • Description: Description weight assigns a weight to the overall description, while Description minimum length, Logo weight, Categories weight, and Labels weight assign weights to description characteristics
   • Documentation: Specify Functional documentation weight and Technical documentation weight
   • Endpoint: Specify Healthcheck weight

5. Click + Add new quality rule to configure a custom rule that will be enforced manually:

   

   • Specify the rule name, description, and weight
   • Click Create

API Quality view and review

To view an API Quality score:

1. Log in to the API Management Console

2. Select APIs from the left nav

3. Select your API

4. From the inner left nav, select Info under General

5. Scroll to the Quality section to view the API Quality score and rules that are impacting it

   

DSAPI Expression Language

Overview

DSAPI Expression Language (EL) is used to query and manipulate object graphs and dynamically configure various aspects and policies of an API. It allows you to reference values from the current API transaction to use expressions to create dynamic filters, routing rules, and policies that respond to specific conditions or parameters.

EL is an extended version of the Spring Expression Language (SpEL) that augments standard SpEL capabilities by providing additional object properties inside the expression language context. As an extension of SpEL, all capabilities detailed in the SpEL documentation are available in EL. However, DSAPI has implemented customizations that are detailed below.

The following sections define the scope and usage of EL:

• Basic usage
• APIs
• Request
• Response
• Message
• Nodes
• Mixin
• Policies
• Conditions
• Debugging

Basic usage

The information below summarizes:

• Object properties added to the EL context
• How attributes are accessed for v4 and v2 APIs
• Commonly used operators and functions

{
  "store": {
    "book": [
      {
        "category": "fiction",
        "author": "Herman Melville",
        "title": "Moby Dick",
        "isbn": "0-553-21311-3",
        "price": 8.99
      },
      {
        "category": "fiction",
        "author": "J. R. R. Tolkien",
        "title": "The Lord of the Rings",
        "isbn": "0-395-19395-8",
        "price": 22.99
      }
    ]
  }
}

APIs

Using EL, you can access information about an API transaction through several root-level objects that are injected into the EL context: custom properties, dictionaries, and endpoints.

Request

EL can be used to access request properties and attributes as described below.

Request object properties

The object properties you can access from the {#request} root-level object property and use for API requests are listed below.

Request context attributes

When APIM Gateway handles an incoming API request, some object properties are automatically created or added during the execution phase through the Assign Attributes policy. These object properties are known as attributes. Attributes can be accessed from the {#context.attributes} root-level object property.

Some policies (e.g., the OAuth2 policy) register other attributes in the request context. For more information, refer to the documentation for individual policies.

Request context attributes and examples are listed below.

SSL object properties

The object properties you can access in the ssl session object from the {#request.ssl} root-level object property are listed below.

Principal objects

The client and server objects are of type Principal. A Principal object represents the currently authenticated user who is making the request to the API and provides access to various user attributes such as username, email address, roles, and permissions.

The Principal object is typically used with security policies such as OAuth2, JWT, or basic authentication to enforce access control and authorization rules on incoming requests. For example, a policy can check if the current user has a specific role or permission before allowing them to access a protected resource.

If the Principal object is not defined, client and server object values are empty. Otherwise, there are domain name attributes you can access from the {#request.ssl.client} and {#request.ssl.server} Prinicipal objects as shown in the table below:

Response

The object properties you can access for API responses from the {#response} root-level object property are listed below.

Message

The object properties you can access for API messages from the {#message} root-level object property are listed below. A message (either sent or received) may also contain attributes that can be retrieved via {#message.attributes[key]}.

Nodes

A node is a component that represents an instance of the DSAPI Gateway. Each node runs a copy of the Gateway that is responsible for handling incoming requests, executing policies, and forwarding requests to the appropriate upstream services. The object properties you can access for nodes from the {#node} root-level object property are listed below.

Mixin

In previous examples, we showed various ways to manipulate objects available in the EL context. You can also mix root-level object property usage to provide an increasingly dynamic configuration.

For example, to retrieve the value of an HTTP header where the name is based on an API custom property named my-property, use {#request.headers[#api.properties['my-property']]}.

Policies

You can use the EL to update some aspects of policy configuration. The policy specifies if it supports EL or not by including a Condition section in the Policy Studio configuration.

Conditions

You can use the EL to set a condition of execution (see 'conditional policies and flows conditions') and it is possible to use logical operators such as && or ||, as shown in the example below:

{#request.headers['my-header'] != null && #request.headers['my-header'][0] =="my-value"}

Debugging

In case of an error when using EL, an exception will be raised :

The template evaluation returns an error. Expression: {#context.error}

If debugging your expression is difficult, consider the following example for guidance:

Assume {#request.content.length() >= 10} is the conditional expression on a flow. When testing, you are expecting the condition to evaluate to false and stop the flow from executing, but the flow continues to function unexpectedly.