In this article

Overview

The API Policy Manager enables you to apply a range of authentication/authorization, traffic management, request transformation, and request validation policies to APIs. You can configure these API policies to be applicable at different levels in the hierarchy in the API Manager console, APIs, and API version. The API policies can also be applied to Org, the shared folder in a Project Space, and Project folders. For example, when you apply a Request Size Limit policy to a Project, the policy validates any request with a request body sent to the Tasks in that Project that does not exceed the limit.

In addition to validating requests, you can use API policies to authenticate and authorize requests using various authentication methods. Without the API Policy Manager, an API can only be invoked by a user registered with the SnapLogic® platform or by using a bearer token. With an APIM authenticator policy, clients can be authenticated through an OAuth2 server or a REST service, and also other available authentication policies.

APIM supports OpenID Connect (OIDC) as an authentication method for your Generic OAuth2 API policy. Multiple Identity Providers are supported. When you set up Generic OAuth2 as the authorization agent with OIDC, your OIDC application becomes the authentication provider for the API.

Policies Snap Pack

API Policies are available in your Org when you subscribe to the APIM feature and Policies Snap Pack. Despite its name, the Policies Snap Pack does not contain Snaps, but it does function like other Snap Packs.

You can configure Snap Pack to use one of the two following distributions:

• Stable contains policies that have been available for a few releases. This distribution is updated quarterly release.

• Latest contains the newest policies and policy features. This distribution is typically updated every month.

The distributions are determined by the Snaplex version updates, which coincide with the monthly and quarterly releases.

The following resources provide more information about the SnapLogic release process:

• Learn more about Snap Packs

• Learn more about Snaplex versions

• Learn more about the SnapLogic Release Calendar

Policies Snap Pack Settings in Classic Manager

You can change Snap Pack versions in the Snap Packs page, which includes a View distribution menu. Options include: 

• New: This option shows Snap Pack choices (Latest or Stable) for an updated Snaplex. 

• Old: This option shows Snap Pack choices (Latest or Stable) for a deprecated Snaplex. 

You can set the View Distribution and Policies Snap Pack version here.

Open

Policies Snap Pack Settings in Admin Manager

You can change the View Distribution and Policies Snap Pack settings in Admin Manager. Learn More.

Supported API Policies

Authentication and Authorization

These policies manage the authorization and authentication of the API caller. The Generic OAuth2 policy is the most common. It requires a third-party service in its setup. You can also use OpenID Connect provider with Generic OAuth2. The OAuth 2.0 Client Credentials policy is a variation on OAuth 2.0 workflow where the authentication flow is based on the Client Credential flow from Okta. The API Key Authenticator provides another authentication mechanism in its use of a key that serves as a license for using the API. The Callout Authenticator provides an alternative to the Generic OAuth2 authentication flow.

• Anonymous Authenticator: Allows anonymous access to a Task. The user’s roles are taken from the Anonymous Authenticator API policy configuration.

• API Key Authenticator: Authenticates a client using API keys passed as a header or query parameter. 

• Authorize By Role: Authorizes a request based on the role associated with the client. If a request is not authorized, it is rejected with a 403 Forbidden error.

• Callout Authenticator: Authenticates a client by calling out to a REST service to validate a token in the request and then authenticating the user.

• Generic OAuth2: Authenticates requests from users registered in an existing identity provider. 

• JWT Validator: Authenticates a request with a token.

• OAuth 2.0 Client Credentials: Authenticates users with a token in your OAuth 2.0 environment.

Inbound/Outbound

These policies provide authentication and enhanced security for inbound and outbound traffic across your Snaplexes and 3rd-party endpoint servers.

Inbound TLS: Use this policy with APIM Proxies to ensure that inbound endpoints are verified by TLS certificates during API processing. Supported by Groundplexes only.

Outbound Basic Auth: Use the Outbound Basic Auth Policy to set up a Basic Authentication account for verification at a proxy endpoint level when you establish a connection with a service or a system.

Outbound OAuth2: Use this policy to set specific OAuth2 parameters such as authorization URL's which are generated through access tokens with client credentials (client ID and client secret) to enforce OAuth2 authentication for upstream API calls.

Outbound TLS: Use this policy with APIM Proxies to ensure that outbound endpoints are verified by TLS certificates during API processing.

Validation

Validation policies apply validation criteria during the process of policy application. Some policies provide additional layers of security, for example, the SQL Threat Detector and Request Size Limit policies. Other policies, such as JSON and XML validator policies, enforce compliance. The Early and Authorized Request policies provide generic mechanisms for enforcing compliance. For example, if a request must contain a specific HTTP header, you can configure either of these policies to reject the request if it does not contain the header.

• Authorized Request Validator: Validates a request after authorization and returns a customized response. 

• Early Request Validator: Validates a request before authentication and returns a customized response. 

• JSON Validator: Validates a request against a JSON schema

• SQL Threat Detector: Protects APIs against SQL commands injected in the header, path, query, and payload of incoming HTTP requests.

• XML XSD Validator: Validates a request against an XML XSD schema.

• XML DTD Validator: Validates a request against an XML DTD schema.

Traffic Shaping

These policies enable the manipulation of incoming request traffic. You can use these policies to protect your API gateways from being overloaded with too many requests (Request Size Limit) or even eliminate traffic from specific sources (IP Restriction). The HTTP Redirect policy allows you to divert requests by customizing the HTTP 300 codes when your API is down because of maintenance.

• Client Throttling: Limits Task invocations for a specific client during a specific time period by throttling or rejecting requests from that client. Install this API policy to help protect a Snaplex from being overloaded by too many requests.

• Request Size Limit: Limits the size of each request. 

• IP Restriction: Restricts access based on the client IP address of the request. If the request does not meet the configured requirements, it is rejected with a 403 Forbidden error.

• CORS Restriction: Sets the appropriate headers for requests coming from a different domain so that the response is not blocked by the browser.

• HTTP Redirect: Manages HTTP redirection for API requests.

• Response Cache: Use this policy for highly reoccurring and static responses to manage latency and response times, which can reduce the load on the upstream API as well as the proxy server.

• HTTP Retry: Use this policy to set up retry logic for requests made to your Proxy and Proxy endpoints.

Transformation

These policies enable you to change the requests or responses based on criteria. You can use these policies to add or modify headers.

• Request Transformer: Transforms a request before it is passed onto the remaining API policies and, finally, the Pipeline to be executed.

• Response Mapper: Transforms the response body. The policy controls provide expression/target path mappings and a Pass Through option for unaffected mappings.

• Response Transformer: Transforms the response headers of the API. You can use this policy to add, remove, or modify response headers.

SnapLogic Expression Language Support

All API policies leverage the SnapLogic Expression Language. Every policy has an expression-enabled field   for the When this policy should be applied setting, where you can create an expression using the built-in operators in the platform. Clicking displays the selector for various operators, document values, and arrow functions, providing greater flexibility to use conditional logic to apply the policy. Several API policies also support expression-enabled fields for their settings. 

Additionally, you can also use API Manager Functions to create an expression based on the asset, Snaplex, or request itself. When the expressions field icon is disabled (), you can enter a string. 

Support for Secrets Management Tools

Starting in the August 2024 release, APIM supports Secrets Management. The Secrets Management feature allows you to leverage existing Secrets Manager third-party tools in your environment. This allows you to retrieve the secrets for your accounts without specifying credentials.

When you configure the Secrets Manager, you select the third-party vendor. No additional work is required to extend the use of secrets in these API policies.

Supported Vendors

Support for Secrets Management extends to the following vendors:

• AWS Secrets Manager

• Azure Key Vault

• CyberArk Conjur (Enterprise or Open Source)

• HashiCorp Vault (Cloud, Enterprise, or Open Source)

Learn more about configuration details.

Supported Policies

The following API policies are supported:

• API Key Authenticator Policy: Enter the secret in the API Key field.

• OAuth 2 .0 Client Credentials Policy: Enter the secret in the Client Secret field.

Usage Guidelines

• You can reference secrets in expression enabled fields. Make sure that the button is toggled on.

• Use an expression that calls secrets.read with the alias name for the secret object.

• Because Groundplex nodes communicate with the secrets manager, make sure that the policies which reference secrets are applied to API Versions and Proxies that run on that Groundplex.

Open ID Connect Support

OpenID Connect (OIDC) is an authentication protocol that operates with the OAuth 2.0 protocol to allow clients to authenticate end-users and obtain basic user profile information. In conjunction with OAuth 2.0, OIDC verifies users' identity across multiple websites without needing to create a separate password for each site. It builds upon the OAuth 2.0 protocol, which was designed for authorization. In simpler terms, while OAuth 2.0 lets applications get permission to access resources on behalf of a user, OpenID Connect confirms who the user is.

In the APIM workflow where OIDC and OAuth 2.0 are implemented for authorization and authentication, the API consumer calls your API through a browser, also known as the client, which sends you to the Identity Provider (IdP) to sign in. This service could be Google, Azure, or any organization that supports OIDC through an identity provider. Then, the API consumer logs into the IdP, if not already logged in. If the consumer is calling the API for the first time using this service for the website, the IdP might ask prompt the caller to share certain information with the website. Once the consumer is authenticated and given any necessary consent, the IdP sends an ID token back to the browser. This ID token is a secure piece of data confirming your identity. The browser reads this ID token and confirms your identity.
To keep things secure, the system has several checks and measures in the background. For example, tokens have expiration times, and the information in the tokens is encoded to prevent tampering.

See the following diagram for a representation of the authorization and authentication flow using OIDC with SnapLogic APIM:

Open

OIDC Components

Here's a simplified overview of how OIDC works:

• Authentication Request: A web application (also known as the client) directs the user to the OIDC IdP, requesting authentication. This is typically done through a browser redirect.

• Authentication: The IdP prompts the user to authenticate by entering a username and password.

• Authorization: If the user hasn't already granted the client permission to access their data, the IdP asks them for consent.

• Authentication Response: After successful authentication and authorization, the IdP redirects the user back to the client. This redirect includes an authorization code, which is passed in the URL.

• Token Request: Using the authorization code, the client makes a request directly to the IdP to exchange the code for an ID token and an access token.

• Token Response: The IdP sends the ID token and access token to the client.

• ID Token: The JSON Web Token (JWT) that contains information about who the user is, when they are authenticated, and how long the token is valid.

• Access Token: This is a bearer token that the client can use to access protected resources on behalf of the user. For OIDC, it often allows the client to retrieve more information about the user from the IdP.

• Discovery Document: A document that contains all the endpoints provided by OpenID Connect Providers. It always has the suffix .well-known/openid-configuration

• UserInfo Endpoint: Optionally, the client can use the access token to request additional user information from the IdP's UserInfo endpoint.
  OIDC has been adopted by many leading technology companies and platforms because it offers a standardized and secure way of doing user authentication across different services and applications.

Workflow for Setting up OIDC

The following steps represent a generic workflow for setting up OIDC to work with your Generic OAuth2 API policies.

1. Register Your Application:

   1. Create a new application or client in the OIDC provider's UI.

   2. Ensure that you set the redirect URI to point back to your application where the OIDC Provider can send the authentication response.

   3. OpenID Connect Discovery Document URL. Add your domain to the discovery URL.

2. Integrate OIDC in your client:

   1. Authentication Request: When a user needs to authenticate, redirect them to the OIDC provider's authorization endpoint. The URL could include parameters such as client_id, response_type, scope, and redirect_uri.

   2. Handle Authentication Response: After the user authenticates and authorizes your application, the OIDC provider will redirect back to your specified redirect URI. This will include an authorization code.

   3. Token Exchange: Your application then exchanges this authorization code for an ID token and access token by making a POST request to the OIDC provider's token endpoint.

   4. ID Token Verification: Verify the ID token's signature and validate its claims to ensure the token’s validity.

3. Protect Your API Endpoints with the following:

   1. Token Inspection: When a client sends a request to your API with an access token (typically in the Authorization header as a Bearer token), your API should validate the token. This can be done locally if the OIDC Provider uses a public key for signing tokens or by calling an introspection endpoint provided by the OIDC Provider.

   2. Scope Validation: OIDC allows you to define scopes that represent different permissions. Ensure your API policy checks that the provided token has the required scope for the desired operation.

   3. Extract User Information: From a valid ID token or from the UserInfo endpoint provided by the OIDC using the access token.

Best Practices for OIDC Implementation

• Implement an Application Logout. Implement a logout mechanism that clears tokens from the client and optionally logs the user out of the OIDC provider.

• Secure Your Implementation. Always use HTTPS. Regularly review OIDC best practices and ensure your implementation stays updated. Handle tokens securely by not exposing them unnecessarily and using secure cookie policies and storage mechanisms.

• Test Your Implementation. Before going live, thoroughly test the OIDC flow from the user’s perspective, and verify that tokens are validated correctly on your API.

• Document the authentication process for users or developers that will consume your API. This should include details on how to obtain tokens, how to use them with your API, and any relevant information about token expiration and renewal.
  We recommend that you follow the official documentation of the OIDC Provider and consult security best practices when implementing authentication and authorization mechanisms.