@open-policy-agent/opa-react

This package contains helpers for using @open-policy-agent/opa from React.

Features

• High-level, declarative components for embedding authorization decisions in your frontend code.
• Built-in caching, deduplication, and state management based on @tanstack/react-query.
• Optional request batching for backends that support it (Enterprise OPA, or your own implementation of the Batch API).

Installation

npm

npm install @open-policy-agent/opa-react
Copy

yarn

yarn add @open-policy-agent/opa-react
Copy

Scaffolding: <AuthzProvider>

To be able to use the <Authz> component and useAuthz hook, the application needs to be able to access the AuthzContext. The simplest way to make that happen is to wrap your <App> into <AuthzProvider>.

Add these imports to the file that defines your App function:

import { AuthzProvider } from "@open-policy-agent/opa-react";
import { OPAClient } from "@open-policy-agent/opa";
Copy

Then instantiate an OPAClient that is able to reach your OPA server, and pass that along to <AuthzProvider>:

const serverURL = "https://opa.internal";

export default function App() {
  const [opaClient] = useState(() => new OPAClient(serverURL));

  // other initialization logic

  return (
    <AuthzProvider opaClient={opaClient}>
      { /* your application JSX elements */ }
    </AuthzProvider>
  );
Copy

If your OPA instance is reverse-proxied with a prefix of /opa/ instead, you can use window.location to configure the OPAClient:

const [opaClient] = useState(() => {
  const href = window.location.toString();
  const u = new URL(href);
  u.pathname = "opa"; // if /opa/* is reverse-proxied to your OPA service
  u.search = "";
  return new OPAClient(u.toString())
});
Copy

To provide a user-specific header, let's say from your frontend's authentication machinery, you could do this:

const { user, tenant } = useAuthn(); // assuming there's some hook for authentication

const [opaClient] = useState(() => {
  return new OPAClient(serverURL, {
    headers: {
      "X-Tenant": tenant,
      "X-User": user,
    },
  });
}, [user, tenant]);
Copy

Controlling UI elements

The <Authz> component provides a high-level approach to letting your UI react to policy evaluation results.

For example, to disable a button based on the outcome of a policy evaluation of data.things.allow with input {"action": "delete", "resource": "thing"}, you would add this to your JSX:

<Authz
  path="things/allow"
  input={{ action: "delete", resource: "thing" }}
  fallback={
    <button disabled={true}>Delete Thing</button>
  }
>
  <button>Delete Thing</button>
</Authz>
Copy

Full control: useAuthz hook

<Authz> is a convenience-wrapper around the useAuthz hook. If it is insufficient for your use case, you can reach to useAuthz for more control.

Avoid repetition of controlled UI elements in code

In the example above, we had to define <button> twice: once for when the user is authorized, and as fallback when they are not. We can avoid this by using useAuthz:

export default function MyComponent() {
  const { result: allowed, isLoading } = useAuthz("things/allow", {
    action: "delete",
    resource: "thing",
  });

  if (isLoading) return <div>Loading...</div>;

  return <button disabled={!allowed}>Delete Thing</button>;
}
Copy

Community

For questions, discussions and announcements related to Styra products, services and open source projects, please join the Styra community on Slack!