chore: address PR feedback

authorization/overview.mdx

@@ -10,11 +10,11 @@ Flipt authorization is **experimental** and **disabled** (not required) by defau
 
 To enable authorization, you must set the `experimental.authorization.enabled` configuration option to `true` in your Flipt [configuration file](/configuration/overview#configuration-file).
 
-See the [Experimental](/configuration/experimental) section for more information on how to enable experimental features.
+See the [experimental](/configuration/experimental) section for more information on how to enable experimental features.
 
 </Info>
 
-Once enabled, all routes beneath the Management API prefix will require a [client token](/authentication/overview#client-tokens) or [JWT](/authentication/overview#json-web-tokens) to authenticate requests along with the required permissions:
+Once enabled, all routes beneath the Management API prefix will require a [policy](#policies) to be evaluated before the request is allowed to proceed. The policy must evaluate to `allowed == true` for the request to be allowed.
 
 - `/api/v1/`
 
@@ -37,15 +37,18 @@ Flipt uses OPA to enforce authorization policies for the Management API. The pol
 
 Part of the power of OPA is that it's extremely flexible as it allows you to define fine-grained policies tailored to your exact needs.
 
-Here's an example of a simple policy that checks whether a user has the `admin` role:
+Here's an example of a simple policy that checks whether custom claims provided at authentication time include a key `roles` containing a value `admin`:
 
 ```rego policy.rego
 package flipt.authz.v1
 
+import rego.v1
+
 default allow = false
 
-allow {
-    input.authentication.metadata["io.flipt.auth.claims"].roles[_] == "admin"
+allow if {
+    claims := json.unmarshal(input.authentication.metadata["io.flipt.auth.claims"])
+    "admin" in claims.roles
 }
 ```
 
@@ -71,7 +74,7 @@ Flipt provides the raw authentication information to OPA for evaluation. This in
 
 For example, if you're using the [OIDC authentication method](/authentication/methods#openid-connect), the `input.authentication.metadata` field may contain the user's name and email as well as custom claims assigned to the user.
 
-Here is an example of the `input.authentication.metadata` field for a request authenticated using a example OIDC provider:
+Here is an example of the `input.authentication.metadata` field for a request authenticated using an example OIDC provider:
 
 ```json
 {
@@ -83,16 +86,20 @@ Here is an example of the `input.authentication.metadata` field for a request au
 }
 ```
 
+<Note>
+The `io.flipt.auth.claims` field is a JSON object that contains custom claims provided by the authentication provider. Each authentication provider may provide different claims, so it's up to you to map these claims as needed in your policies.
+</Note>
+
 The following fields are available in the `input.authentication` field:
 
 - `metadata`: A map of authentication metadata provided by the authentication method. This can include the user's email, name, roles, etc.
   - `io.flipt.auth.email`: The user's email address.
   - `io.flipt.auth.name`: The user's name.
   - `io.flipt.auth.claims`: A map of **all** claims provided by the authentication method. This can include the user's roles, groups, etc. These claims are marshaled into a JSON string before being passed to OPA for evaluation.
 
-#### Mapping User Information
+#### Mapping Identity
 
-Each authentication method used to authenticate requests with Flipt will provide different information about the user. It's up to you to map this information to roles that can be used in your policies.
+Each authentication method configurable within Flipt will provide different information depending on the identity. It's up to you to combine identity information (`authentication`) with the requested resource (`request`) to make an authorization decision whether or not the request should be allowed (`allow`).
 
 Some authentication methods provide user details such as roles directly, while others may provide a user ID or email that you can use to look up roles in your own system. Many authentication providers support adding custom claims to the JWT token, which can be used to provide additional information about the user.
 
@@ -120,9 +127,11 @@ In this example, the `groups` claim is used to provide the user's organizational
 ```rego policy.rego
 package flipt.authz.v1
 
+import rego.v1
+
 default allow = false
 
-allow {
+allow if {
     claims := json.unmarshal(input.authentication.metadata["io.flipt.auth.claims"])
     "IT" in claims.groups
 }
@@ -149,7 +158,7 @@ Roles or groups are not a requirement for writing policies. You can write polici
 
 The `input.request` field contains information about the incoming request. This includes the `namespace`, `resource`, and `verb` of the request.
 
-- `namespace`: The [namespace](/concepts#namespaces) in Flipt of the resource being accessed. If no namespace is provided, the default namespace is used.
+- `namespace`: The [namespace](/concepts#namespaces) in Flipt of the resource being accessed. If no namespace is provided, the default namespace is used, or it is not applicable as the resource is not namespace scoped (e.g. authentication)
 
 - `resource`: The resource being accessed. This can be one of:
 
@@ -192,9 +201,11 @@ Here is an example policy that allows a user to list flags in the default namesp
 ```rego policy.rego
 package flipt.authz.v1
 
+import rego.v1
+
 default allow = false
 
-allow {
+allow if {
     input.request.namespace == "default"
     input.request.resource == "flag"
     input.request.verb == "read"
@@ -206,9 +217,11 @@ Combining the above policy with the user information policy from the previous ex
 ```rego policy.rego
 package flipt.authz.v1
 
+import rego.v1
+
 default allow = false
 
-allow {
+allow if {
     claims := json.unmarshal(input.authentication.metadata["io.flipt.auth.claims"])
     "IT" in claims.groups
     input.request.namespace == "default"
@@ -228,10 +241,12 @@ Here is an example policy that uses an external data source to check if the user
 ```rego policy.rego
 package flipt.authz.v1
 
+import rego.v1
+
 default allow = false
 
-allow {
-    role := data.roles[input.authentication.id]
+allow if {
+    role := data.roles[input.authentication.metadata["io.flipt.auth.name"]]
     role == "admin"
 }
 ```

configuration/authentication.mdx

@@ -113,7 +113,7 @@ Further explanation for using this method can be found in the [Authentication: S
 <Note>The `OIDC` method is a `session compatible` authentication method.</Note>
 
 <Tip>
-  Read our [Login with Google](/guides/login-with-google) guide for a more
+  Read our [Login with Google](/guides/operation/authentication/login-with-google) guide for a more
   in-depth walk-through setting up an OIDC provider.
 </Tip>
 
@@ -218,7 +218,7 @@ To enable this, you must set the [`use_pkce`](/configuration/overview#authentica
 #### Example: OIDC With Google
 
 <Tip>
-  Checkout our [Login with Google](/guides/login-with-google) guide for an
+  Checkout our [Login with Google](/guides/operation/authentication/login-with-google) guide for an
   in-depth look into configuring Google as an OIDC provider.
 </Tip>
 
@@ -276,7 +276,7 @@ Other providers have similar mechanisms for attenuating who can leverage this au
 </Note>
 
 <Tip>
-  Read our [Login with Github](/guides/login-with-github) guide for a more
+  Read our [Login with Github](/guides/operation/authentication/login-with-github) guide for a more
   in-depth walk-through.
 </Tip>
 
@@ -295,7 +295,7 @@ authentication:
         - user:email
 ```
 
-!["GitHub Login"](../images/guides/login-with-github/login-with-github.png)
+!["GitHub Login"](../images/guides/operation/authentication/login-with-github/login-with-github.png)
 
 #### Allowed Organizations
 

configuration/authorization.mdx

@@ -40,7 +40,7 @@ Currently, Flipt only supports local policy files. These policy files must be va
 
 <Note>
   In the future we plan to support other policy source backends such as git,
-  object, and others. If you have a specific use case, please get in touch!
+  object store, and others. If you have a specific use case, please get in touch!
 </Note>
 
 You can specify the path to the policy file in the `policy` object in the `authorization` configuration object.
@@ -54,7 +54,7 @@ authorization:
       path: "policy.rego"
 ```
 
-The policy must have the following package declaration:
+The policy **must** have the following package declaration:
 
 ```rego policy.rego
 package flipt.authz.v1
@@ -88,7 +88,7 @@ Currently, Flipt only supports local data objects. These data objects **must be
 
 <Note>
   In the future we plan to support other data source backends such as git,
-  object, and others. If you have a specific use case, please get in touch!
+  object store, and others. If you have a specific use case, please get in touch!
 </Note>
 
 You can specify the path to the data file in the `data` object in the `authorization` configuration object.

guides/operation/authentication/login-with-github.mdx

@@ -3,7 +3,7 @@ title: Login with GitHub
 description: Configuring Flipt to enable login with GitHub via OAuth 2.0
 ---
 
-If you've read the [Login With Google guide](/guides/login-with-google), you would have learned that Flipt supports many methods of authentication for users to control who has access to Flipt.
+If you've read the [Login With Google guide](/guides/operation/authentication/login-with-google), you would have learned that Flipt supports many methods of authentication for users to control who has access to Flipt.
 
 Alongside the support for generic OIDC login, Flipt has launched support for login with GitHub in version [v1.26.0](https://github.com/flipt-io/flipt/releases/tag/v1.26.0), through their OAuth 2.0 flow. This guide will serve as a walk-through on how to set this flow up for users of Flipt in your organization.
 

guides/operation/authentication/login-with-keycloak.mdx

@@ -5,7 +5,7 @@ description: Configuring Flipt to enable login with Keycloak via OIDC
 
 ![Flipt UI presenting login with Keycloak button](/images/guides/login-with-keycloak/login-with-keycloak.png)
 
-If you've read the [Login With Google guide](/guides/login-with-google), you would have learned that Flipt supports many methods of authentication for users to control who has access to Flipt.
+If you've read the [Login With Google guide](/guides/operation/authentication/login-with-google), you would have learned that Flipt supports many methods of authentication for users to control who has access to Flipt.
 
 [Keycloak](https://www.keycloak.org/) is an open-source identity and access management solution that supports OpenID Connect (OIDC). This guide will serve as a walk-through on how to set up Keycloak for authentication of users of Flipt in your organization.
 
@@ -23,7 +23,7 @@ By the end of this guide, we will have:
 For this guide you're going to need the following:
 
 - [Docker](https://www.docker.com/)
-- Read the [Login With Google guide](/guides/login-with-google)
+- Read the [Login With Google guide](/guides/operation/authentication/login-with-google)
 
 ## Setting Up Keycloak
 
@@ -183,4 +183,6 @@ Once you successfully authenticate with the username/password you created earlie
 
 🎉 Congratulations, you've successfully run Flipt and enabled login with Keycloak as the OIDC provider.
 
-Many of the same production considerations from the [Login With Google guide](/guides/login-with-google) apply here. You should follow the same steps to secure your Flipt instance and ensure that only authorized users can access it.
+Many of the same production considerations from the [Login With Google guide](/guides/operation/authentication/login-with-google) apply here. You should follow the same steps to secure your Flipt instance and ensure that only authorized users can access it.
+
+Next, you might want to consider enabling authorization and setting up policies to control who can access what in Flipt. You can learn more about this in the [Role-Based Access Control with Keycloak guide](/guides/operation/authorization/rbac-with-keycloak).