API Policy Manager

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.

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.

Authentication Policy Requirement

All authentication policies require the Authorize By Role policy to authenticate the API caller.

  • 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.

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.

  • HTTP 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. 

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:

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.