This topic shows how you can convert common use cases into service policies and policy fragments on the

CA API Gateway

.

The

CA API Gateway

can publish a variety of different services. These can be broadly categorized as:

The simple use case is also very common. A policy for this just involves three policy elements: Gather credentials, validate the credentials, and finally send the original request to a back end server. In this case, we're allowing all valid users to access the back end resource, so Authorization is implied by Authentication. The final act of the Gateway returning the back end server's response to the user is implied by the policy finishing successfully.

As there's no optional events and no decisions that result in anything other than "This is not a valid request", there's no need for any composite assertions, no branches into conditional states.  The policy looks like this:

Our simple example policy requires no composite assertions nor conditional branching. There are no optional events nor decisions resulting in anything other than "This is not a valid request". The sample looks like this in the Policy Manager:

The

CA API Gateway

supports many types of credentials, including: usernames and  passwords, various single sign-on tokens, X.509 certificates, SAML tokens, JWT, and other more obscure ones.  

Credentials must be available in the policy before an assertion that validates them executes. That underscores the sequential nature of policy execution: the Gateway cannot validate credentials if it has not extracted them from the inbound context yet.

Validation implies mostly the authentication step, but some tooling, like RADIUS implies both Authentication and Authorization. It is best practice to validate all credentials. The Policy Manager warns you when you extract credentials without validating them.

There may be instances where gathering credentials and validating them with custom tooling triggers the warning–for example, the policy validates credentials via direct database lookup. If this happens, ignore the warning. You can still save the policy even when validation warnings are present.

Note that gathering and validating credentials is done via data structures that are always available, often referred to as the "message context". This is largely automatic, but there are cases where specifically referring to this context is done via context variables. For more information about these variables, see Authentication Context Variables.

Authorization can be thought of as either explicit or implicit.

Explicit

authorization examines the results of authentication for certain attributes. Implicit authorization uses an external decision tool such as CA Single Sign-on, or a local authorization tool built by the organization.

LDAP is very common in organizations. These are organized into "LDAP Identity Providers", which provide a convenient way to authenticate and extract attributes. These attributes are then used in decision trees in the policy.

Note that SSO tools often combine both Authorization and Authentication into a single call. This results in cleaner, simpler-looking policies, but at the expense of "dividing" the policy: in the Gateway as a policy enforcement point and in the SSO tool as a policy decision point. This separation may cause some difficulties, but there are good reasons based on corporate governance to keep the SSO tool-based decision point.

Sending a validated request to a back-end service is the most common deployment of the

CA API Gateway

. The Policy Manager provides a variety of routing assertions: see Message Routing Assertions for details. In the most common scenarios, the Gateway authorizes access to the back end, to pass request credentials, role accounts, or mutually-authenticated SSL.

The

CA API Gateway

is designed as a message processing engine that is optimize for HTTP uses cases, but is not exclusively a "HTTP gateway". The message processor accepts any message that enters the flow and simply executes the policy until it exits. Policy authors use the AND/OR logic rules to construct a policy with specific input/output needs and the Gateway processes all the steps.

A relatively common use case involves receiving a message over HTTP and then sending the message to a queue like MQ Series or Tibco EMS. The policy for this is nearly identical to the common case shown previously, but instead of the Route via HTTP(S) Assertion, you use the Route via JMS Assertion or Route via MQ Native Assertion.

Expanding on the simple case, you can add a policy step to create or obtain a different kind of credential or token once credentials are validated. This can be as simple as HTTP Basic credentials inbound, or SOAP with WS-Basic Authentication to the back end. The Policy Manager provides assertions for token creation and single sign-on authorization.

You can add the credential tokens to any of the following:

Note that the Gateway does not require redirects to add HTTP cookies to the back-end request context, because the Gateway does this work via direct requests and specific policy configuration. It generally does not involve the browser.

Federation in the Gateway can be simply token mediation: Instead of a simple token, a cryptographic token is generated in policy, like a SAML token or JSON web token.

The Gateway can also request from an external token service. Example: The Gateway submits a WS-Trust message to a SAML STS (Secure Token Service). It receives the response, parses the SAML token, and then places the token into the WS-Security header of the SOAP message. The Gateway then sends the combined message to the real back end service.

The flow is conceptually the same in JSON: replace the WS Trust with whatever the JWT STS needs as a request,. The JSON web token and structure of the message is manipulated as JSON.

The Gateway Federation is strictly claims based, without requiring a backing identity.  The decision to issue a token comes from the policy. It can be derived from identity or simply from the credential presented.

Policy fragments are standard policy logic designed to work with more than one service. A fragment also referred to as an "included policy" or simply "include". Programmers can liken them to library routines, with strictly defined inputs and outputs and limited side effects.

Policy fragments can have role-based access control rules, similar to service policies. This allows them to be authored by domain experts, while being read-only to the policy authors. This provides the same benefits as standard software development: domain experts define common policy elements (for example, like Authentication, Authorization, Audit) and policy authors simply insert the appropriate fragments into their policies. Fragments help reduce errors and simplifies testing, validation, and governance.

A close variation of policy fragments are encapsulated assertions. These can be viewed as "home made" assertions that is powered by an underlying policy fragment. The main difference is that the policy fragment is completely concealed within an encapsulated assertion, accepting input from the user interface crafted for that assertion.

Encapsulated assertions allow you to strictly define your inputs and outputs, and are a critical tool to create strong, locally-relevant best practices.

Deciding on auditing is a critical part of developing any policy. Business concerns often require complete auditing, but be aware that auditing is not "free". There are serious implications to consider when auditing every request. The default audit setup consumes significant disk space, which may be in limited supply on appliance Gateways (physical or virtual). Carefully consider your auditing early in the service deployment plan.  

Keep in mind these core concepts for auditing: