Merge pull request #440 from solliancenet/cj-rbac-docs

RBAC documentation

docs/role-based-access-control/index.md

@@ -0,0 +1,13 @@
+# FoundationaLLM RBAC documentation
+
+FoundationaLLM role-based access control (FoundationaLLM RBAC) is a system that provides fine-grained access control to FoundationaLLM resources. It is a system that allows you to control who can access what in your FoundationaLLM instance.
+
+## Concepts
+
+[Understand FoundationaLLM role definitions](role-definitions.md)
+
+[Understand FoundationaLLM role assignments](role-assignments.md)
+
+[Understand scope for FoundationaLLM RBAC](scope.md)
+
+[Manage role assignments](role-management.md)

docs/role-based-access-control/role-assignments.md

@@ -0,0 +1,46 @@
+# Understand FoundationaLLM role assignments
+
+Role assignments enable you to grant a principal (such as a user, a group, a managed identity, or a service principal) access to a specific FoundationaLLM resource.
+
+## Role assignment
+
+Acess to FoundationaLLM resources is granted through role assignments, and is reoked by removing a role assignment. A role assignment has several components:
+
+- The _principal_, or _who_ is being given access.
+- The _role definition_ (_role_), or _what_ access is being granted.
+- The _scope_ at which the role is assigned, or _where_ the access applies.
+- The _name_ of the role assignment.
+- The _description_ of the role assignment that helps explain why it exists.
+
+The following is an example of a FoundationaLLM role assignment:
+
+```json
+{
+  "RoleAssignmentName": "00000000-0000-0000-0000-000000000000",
+  "RoleAssignmentId": "/instances/11111111-1111-1111-1111-111111111111/providers/FoundationaLLM.Authorization/roleAssignments/00000000-0000-0000-0000-000000000000",
+  "Scope": "/instances/11111111-1111-1111-1111-111111111111",
+  "RoleDefinitionName": "Contributor",
+  "RoleDefinitionId": "e459c3a6-6b93-4062-85b3-fffc9fb253df",
+  "ObjectId": "22222222-2222-2222-2222-222222222222",
+  "ObjectType": "User",
+  "DisplayName": "Jack The Cat",
+  "SignInName": "[email protected]",
+  "Description": "Jack The Cat has contributor access to the FoundationaLLM instance."
+}
+```
+
+The following table describes the properties of a role assignment.
+
+Property | Description
+--- | ---
+RoleAssignmentName | The name of the role assignment (is always a GUID).
+RoleAssignmentId | The unique identifier of the role assignment which includes the name.
+Scope | The FoundationaLLM resource identifier that the role assignment applies to.
+RoleDefinitionName | The name of the role definition.
+RoleDefinitionId | The unique identifier of the role definition.
+DisplayName | The display name of the principal.
+ObjectId | The unique identifier of the principal (can be a user, a group, a managed identity, or a service principal).
+ObjectType | The type of the principal. Valid values include `User`, `Group`, and `ServicePrincipal`.
+DisplayName | The display name of the principal.
+SignInName | The unique principal name (UPN) of the principal.
+Description | The description of the role assignment.

docs/role-based-access-control/role-definitions.md

@@ -0,0 +1,66 @@
+# Understand FoundationaLLM role definitions
+
+## Role definition
+
+A role defininition (or just role) is a collection of permissions. A role definition lists the actions that can be performed, such as read, write, and delete.
+
+The following table describes the propoerties of a role definition.
+
+Property | Description
+--- | ---
+Name | The display name of the role definition.
+Id | The unique identifier of the role definition.
+Description | The description of the role definition.
+Actions | An array of strings that lists the control plane actions that a role definition can perform. For example, `FoundationaLLM.Agent/agents/create`.
+NotActions | An array of strings that lists the actions that are excluded from the actions listed in the Actions property.
+DataActions | An array of strings that lists the data plane actions that a role definition can perform. For example, `FoundationaLLM.Agent/agents/read`.
+NotDataActions | An array of strings that lists the data plane actions that are excluded from the actions listed in the DataActions property.
+AssignableScopes | An array of strings that lists the scopes that the role definition can be assigned to.
+
+## Actions format
+
+The string that represents an action has the following format:
+
+`FoundationaLLM.{ProviderName}/{resourceType}/{action}`
+
+Examples of actions include `read`, `write`, and `delete`.
+
+The wildcard character (`*`) can be used to match any resource type or action. For example, `FoundationaLLM.Agent/*/read` matches all read actions for all resource types in the `FoundationaLLM.Agent` provider.
+
+## Role definition example
+
+The following example shows the `Contributor` role definition. The wildcard (`*`) character under `Actions` indicates that the principal assigned to the role can perform all actions (i.e., it can manage everything). This includes also actions defined in the future, as FoundationaLLM adds new resource types. The actions under `NotActions` are subtracted from `Actions`. In this specific case, `NotActions` removes the role's ability to manage access to resources.
+
+```json
+{
+  "Name": "Contributor",
+  "Id": "e459c3a6-6b93-4062-85b3-fffc9fb253df",
+  "Description": "Allows you to manage everything except access to resources.",
+  "Actions": [
+    "*"
+  ],
+  "NotActions": [
+    "FoundationaLLM.Authorization/*/delete",
+    "FoundationaLLM.Authorization/*/write"
+  ],
+  "DataActions": [],
+  "NotDataActions": [],
+  "AssignableScopes": [
+    "/"
+  ]
+}
+```
+
+## Control and data actions
+
+Control plane actions are specified in the `Actions` and `NotActions` properties.
+
+Examples of control plane actions in FoundationaLLM include:
+
+- Manage access to an agent
+- Create a new data source
+- Delete a prompt
+
+Data plane actions are specified in the `DataActions` and `NotDataActions` properties.
+
+**NOTE**: FoundationaLLM maintains a strict separation between the control and data planes. Control plane access is not inherited to the data plane. For example, if a user has the `FoundationaLLM.Agent/agents/create` permission, it does not mean that the user has the `FoundationaLLM.Agent/agents/read` permission.

docs/role-based-access-control/role-management.md

@@ -0,0 +1,27 @@
+# Manage role assignments
+
+FoundationaLLM roles are assigned to users, groups, service principals, and managed identities through the Management API. As described in the [role definitions](role-definitions.md) article, administrators can apply fine-grained access control to features and resources to ensure the deployment adheres to least-privilege best practices when properly assigned.
+
+## Role management endpoints
+
+The Management API provides the following role management endpoints:
+
+| Method | Endpoint | Description |
+| --- | --- | --- |
+| GET | `/security/roles` | Returns a list of all roles. |
+| GET | `/security/roles/{RoleDefinitionId}` | Returns the role settings for the specified role. |
+| GET | `/security/roles/{RoleDefinitionId}/assignments` | Returns a list of all role assignments for the specified role. |
+| GET | `/security/roles/{RoleDefinitionId}/assignments/{RoleAssignmentId}` | Returns the role assignment settings for the specified role assignment. |
+| GET | `/security/roles/{Scope}` | Returns a list of all roles at the specified scope. |
+| GET | `/security/roles/{Scope}/assignments` | Returns a list of all role assignments at the specified scope. |
+| POST | `/security/roles/assign` | Assigns a role to an Entra ID user or group. |
+| POST | `/security/roles/revoke` | Revokes a role from an Entra ID user or group. |
+
+> [!NOTE]
+> The Management Portal provides a graphical user interface over the Management API for managing roles and role assignments, among other FLLM configuration settings.
+
+All role assignment changes are audited and can be viewed in the Management Portal. Auditing ensures that all changes to role assignments are tracked and can be reviewed at a later time, which is often required for compliance purposes.
+
+## Role assignment data store
+
+The role-based access control (RBAC) engine uses a dedicated data store to manage role assignments. Doing so ensures isolation from the rest of the FoundationaLLM data platform, which is used to store data sources, prompts, and other resources accessible to users possessing varying levels of access. The isolation also supports the ability to scale the RBAC engine independently from the rest of the FoundationaLLM data platform. The data store is implemented as a dedicated Azure Cosmos DB account or Azure Data Lake Storage Gen2 account.

docs/role-based-access-control/scope.md

@@ -0,0 +1,48 @@
+# Understand scope for FoundationaLLM RBAC
+
+_Scope_ is the set of resources that a role assignment can access. When assigning roles, it is importan to understand how scope works so that you grant security principals only the level of access they need. Limiting scope also limits the potential damage that can be done if a security principal is compromised.
+
+## Scope levels
+
+In FoundationaLLM, you can specify a scope at the following levels:
+
+- _Instance_: The FoundationaLLM deployment itself.
+- _Resource_: A specific resource in FoundationaLLM, such as an agent.
+
+The following rules apply to scope levels:
+
+- Scopes are structured as a hierarchy. For example, a resource scope is always a child of an instance scope.
+- Each level make the scope more specific. For example, a resource scope is more specific than an instance scope.
+- Roles can be assigned at any of these levels of scope.
+- Lower levels inherit the permissions of higher levels. For example, a role assignment at the instance level applies to all resources in the instance.
+
+## Scope format
+
+Scope is a string that identifies the exact scope of the role assignment. The scope is usually referred to as the _resource identifier_ or _resource ID_.
+
+The scope consists of a series of identifiers separated by the slash (/) character. You can think of this string as expressing the following hierarchy, where text without placeholders (`{}`) are fixed identifiers:
+
+```text
+/instances
+    /{instanceId}
+        /providers
+            /{providerName}
+                /{resourceType}
+                    /{resourceSubType1}
+                        /{resourceSubType2}
+                            /{resourceName}
+```
+
+- `{instanceId}` is unique identifier of the FoundationaLLM deployment (a GUID).
+- `{providerName}` is the name of the FoundationaLLM resource provider (for example, `FoundationaLLM.Agent`).
+- `{resourceType}` and `{resourceSubType*}` identify levels within the resource provider.
+- `{resourceName}` is the name of a specific resource.
+
+## Scope examples
+
+Scope | Example
+--- | ---
+Instance | `/instances/11111111-1111-1111-1111-111111111111`
+Resource | `/instances/11111111-1111-1111-1111-111111111111/providers/FoundationaLLM.Agent/agents/agent1`
+Resource | `/instances/11111111-1111-1111-1111-111111111111/providers/FoundationaLLM.DataSource/dataSources/datasource1`
+Resource | `/instances/11111111-1111-1111-1111-111111111111/providers/FoundationaLLM.Agent/agents/agent1/models/gpt4`.