When it comes to defining a strategy for web API security, OAG (Oracle API Gateway) and OES (Oracle Entitlements Server) together present a very interesting choice and are a very powerful combination indeed.
In this post we're going to take a look at what each component brings in (the skin) and then get our hands on actually describing the integration in detail (the guts).
OAG is designed to inspect and act on various types of messages that are delivered to it or just pass through it. It's usually positioned to be deployed on the DMZ (the De-Militarized Zone) within corporate networks. As such, it can block malicious traffic, authenticate users with a variety of protocols, integrate with anti-virus products, perform message throttling, thus delivering only the good stuff to your intranet servers and also off-loading them, decisively contributing to achieve some IT operational SLAs. More than that, OAG can switch protocols and transform messages. For instance, an organization may have SOAP-based web services and want to expose them as REST without any re-writing. Or implement SAML federation without touching origin systems. Or talk Kerberos or OAuth with clients and speak SAML with back-end servers. Or use it as an FTP server so that incoming files are immediately sent to a processing pipeline. The possibilities are numerous. Having mentioned these few features and examples, it's not unreasonable to think deploying OAG inside intranets. And that's not unusual, actually. It is a nice bridge with obvious benefits.
OES is designed to provide fine-grained authorization with externalized policies to client applications. It takes the coding of access decisions away from developers. Besides the obvious security pro, it shortens the change cycle, when a new security policy needs to be deployed. You simply avoid going through all the phases required for re-deploying your application just because of that change. It's true the new policy needs testing, but that's nowhere near when compared to what it takes to re-deploy a new application version. The time to market is drastically reduced. Now to the fine-grained part. OES can take a bunch of aspects in consideration when authorizing: the user identity, user roles, user attributes, context information about the request being made (like originating IP address), factors external to the request (like time of day, day of week, etc) and, of course, request data. Those combined makes it a very powerful authorization engine. It's not coincidence that OES is the component behind OAM's (Oracle Access Manager) authorization engine.
While OAG itself brings in authorization capabilities, in this field OES offers a much richer model. And if the organization already employs OES elsewhere, integrating it with OAG makes a lot of sense, because we end up with a single and consistent approach for authorization across applications.
OES basic architecture comprises a server and different client modules, called SMs (Security Modules). The server connects to a repository where policies are physically kept. The SMs are attached to client applications and connect either to OES server or to the repository directly, depending on their configured mode (I will touch up on this later). There are SMs available for Java, RMI, web services, Weblogic server, Websphere, JBoss, MS Sharepoint. When integrating with OAG, a Java SM is used. Despite its core being a C process, OAG forks up a JVM for some of its functions.
The integration hook between OAG and OES is the "OES 11g Authorization" filter, as seen below:
This is how OAG delegates authorization decisions to OES. Under the covers, an OpenAZ API authorization call is made to the SM. In the filter, we observe the following:
- Resource: the OES resource for which authorization is being requested. There's an implicit formation rule here: <OES_APPLICATION_NAME>/<OES_RESOURCE_TYPE>/<OES_RESOURCE_NAME>. Later on I will show how these placeholders map to the OES policy.
- Action: the action supported by the policy. More later on the OES policy.
- Environmental/Context attributes: any extra information that you want to pass in to OES. These map to attributes in the OES policy. In this example, INVOKING_APPLICATION is an attribute used in a policy condition.
As for <OES_RESOURCE_TYPE>, it suffices saying that the target name /resources/empSalaries is of type restapi, as shown:
The authenticated user is implicit in the policy. And in this case, it is going to be authorized only if it has Managers as one of its application roles.
So far, so good, but OAG can only talk to OES if it has the SM properly installed and configured.
Installing and Configuring OES SM for OAG
- oracle.security.jps.runtime.pd.client.policyDistributionMode=controlled-push <change this only if you want to have another distribution mode>
- oracle.security.jps.runtime.pd.client.RegistrationServerHost=<OES Admin Server>
- oracle.security.jps.runtime.pd.client.RegistrationServerPort=<OES Admin Server SSL port>
- controlled-push means that policies are distributed from OES server to the SM. The SM provides a listener that the OES server connects to. In OES Console, once the Distribute button is clicked, policies are *immediately* distributed to the configured SMs. The Distribute button doesn't actually distribute policies. It simply marks policies as "Ready for Distribution". In the case of push, policies are distributed right after. From this point on, SM needs no connection at all to the OES server (it can even be shut down), since policies are all local to the SM.
- controlled-pull means that the SM pulls policies on a defined frequency (default 10 min) directly from the *OES repository* into its local cache. It doesn't get policies through OES server. But still, in other to be pulled, policies do need to be marked "Ready for Distribution" in OES Console.
- uncontrolled means that SMs read policies directly from OES repository on demand and updates the local cache if the requested policy is not available locally. And the SM still pulls new policies and changes from OES repository periodically. As a result, OES repository is supposed to be up and reachable by SMs at all times. Policies don't need to be marked "Ready for Distribution", i.e., there's no further control once policies are created/changed in OES.
Debugging OES SM in OAG
If you ever need to debug OES authorization decisions in OAG, refer back to jvm.xml. There you find the entry
As we can see, OAG and OES are a powerful combination when protecting web APIs. In this post we showed what to expect from this integration, how to configure policies on both sides, how to install OES SM in OAG and how to debug authorization decisions. Hopefully this is useful for some of you loyal readers out there.
See you next time!