diff --git a/docs/admin/lock/README.md b/docs/admin/lock/README.md index f3096b0a042..58d3337ccb2 100644 --- a/docs/admin/lock/README.md +++ b/docs/admin/lock/README.md @@ -11,10 +11,48 @@ tags: # Jans Lock Overview -Lock enables domains to enforce policies based on real time OAuth data. Lock -pushes token data from Auth Server to [OPA](https://openpolicyagent.org), enabling -authorization based on real time information from the OAuth infrastructure. In -order to use Lock, admins will have to do a few things: +Jans Lock enables domains to enforce access policies based on real time OAuth +data. + +Centralized policy management is a best practice for authorization for distributed +networks. If security policies are buried in the code of numerous applications, +they are hard to inventory and harder to update. For decades, application +security architects have conceptualized distributed authorization in line with +[RFC 2409](https://datatracker.ietf.org/doc/html/rfc2904#section-4.4) +and [XACML](https://docs.oasis-open.org/xacml/3.0/xacml-3.0-core-spec-cos01-en.html), +which describe several common components: + +|Abbr. | Term | Description | +| ----- | :--: | ----------- | +| PDP | Policy Decision Point | Service which evaluates access requests against authorization policies before issuing access decisions | +| PEP | Policy Enforcement Point | Service, website or API which queries the PDP for authorization | +| PAP | Policy Administration Point | User interface where admins manage authorization policies | +| PIP | Policy Information Point | The "data" about people, clients and resources | +| PRP | Policy Retrieval Point | Repository where policies are stored | + +In the old days of "WAM" (web access management), each web server would query +a centralized PDP over the network. This is ok for course grain authorization. +But for fine grain authorization, it is too slow--each decision requires a round +trip HTTP request/response. A more performant design is to move the PDP to the +edge of the network. Policy definition and administration is still a centralized +activity. Once a policy is defined, it can be executed anywhere on the network. +Although multiple PDP instances exist, they must provide the same access control +decisions given the same inputs. + +Another critical optimization was to move the PIP to the edge, so the PDP +has all the data it needs to make a decision. This aligns with a principle that +each microservice is well-encapsulated--all logic and data is encapsulated into +a single deployment unit. + +![Jans Lock Toplogy](../../assets/lock-design-diagram-02.png) + +To empower this cloud native authorization pattern, Janssen leverages a +component governed under the Linux Foundation: [OPA](https://openpolicyagent.org), +a project at the [CNCF](https://cncf.io). OPA is a popular PDP, whose popularity +grew significantly in response to the need for granular policies for Kubernetes +access control. The Jans Lock solution pushes token data from Auth Server to OPA, +enabling authorization based on real time information from the OAuth +infrastructure. In order to use Lock, admins will have to do a few things: * [Enable Lock in Auth Server](./lock_token_stream.md) * [Configure a Lock client instance](./lock_client.md) diff --git a/docs/assets/lock-design-diagram-00.png b/docs/assets/lock-design-diagram-00.png index 57a364f61f5..8606e7ba932 100644 Binary files a/docs/assets/lock-design-diagram-00.png and b/docs/assets/lock-design-diagram-00.png differ diff --git a/docs/assets/lock-design-diagram-02.png b/docs/assets/lock-design-diagram-02.png new file mode 100644 index 00000000000..b9b2ec7f56b Binary files /dev/null and b/docs/assets/lock-design-diagram-02.png differ