allow dynamic assignment and removal of roles to users and groups

Author: adelowo

common/openapi/models.go

@@ -21,10 +21,6 @@ import (
 	"github.com/theopenlane/utils/passwd"
 )
 
-const (
-	exampleFindingsCount = 5
-)
-
 // ExampleProvider interface allows response models to provide their own examples
 // This eliminates the need for separate Example* variables and static switch statements
 type ExampleProvider interface {
@@ -2534,24 +2530,31 @@ var ExampleScopesReply = ScopesReply{
 // Roles
 // =========
 
+// OrganizationRole contains certain metadata for a role that can be assigned to users.
+type OrganizationRole struct {
+	ID          string `json:"id" description:"The role relation ID" example:"policy_manager"`
+	Name        string `json:"name" description:"The display name for the role" example:"Policy Manager"`
+	Description string `json:"description" description:"The role description" example:"Manage all policies and procedures"`
+}
+
 // RolesRequest contains roles that can be assigned to users on top of org roles
 type RolesRequest struct{}
 
 // RolesReply holds the fields that are sent on a response to the `/roles` endpoint
 type RolesReply struct {
 	// Reply is the reply value.
 	rout.Reply
-	// Scopes is a list of roles that can be assigned
-	Roles []string `json:"roles,omitempty" description:"A map of object types to operations that can be set for an API Token"`
+	// Roles is a list of organization responsibility roles that can be assigned.
+	Roles []OrganizationRole `json:"roles,omitempty" description:"Organization roles and responsibilities that can be assigned"`
 }
 
-// ExampleResponse returns an example ScopesReply for OpenAPI documentation
+// ExampleResponse returns an example RolesReply for OpenAPI documentation
 func (r *RolesReply) ExampleResponse() any {
-	return ExampleScopesReply
+	return ExampleRolesReply
 }
 
 // Validate ensures the required fields are set on the RolesRequest
-func (r *ScopesReply) Validate() error {
+func (r *RolesRequest) Validate() error {
 	return nil
 }
 
@@ -2561,9 +2564,92 @@ var ExampleRolesRequest = RolesRequest{}
 // ExampleRolesReply is an example of a successful `/roles` response for OpenAPI documentation
 var ExampleRolesReply = RolesReply{
 	Reply: rout.Reply{Success: true},
-	Roles: []string{
-		"compliance_manager",
-		"risk_manager",
-		"policy_manager",
+	Roles: []OrganizationRole{
+		{
+			ID:          "policy_manager",
+			Name:        "Policy Manager",
+			Description: "Can manage all policies and procedures",
+		},
+		{
+			ID:          "risk_manager",
+			Name:        "Risk Manager",
+			Description: "Can manage risks, vulnerabilities, and findings",
+		},
 	},
 }
+
+// OrganizationRolesRequest contains roles that can be assigned to users or groups.
+type OrganizationRolesRequest struct {
+	OrganizationID string   `json:"organization_id,omitempty" description:"The ID of the organization to assign roles in. Defaults to the authenticated organization." example:"01J4HMNDSZCCQBTY93BF9CBF5D"`
+	Role           string   `json:"role" description:"The organization responsibility role to assign" example:"policy_manager"`
+	UserIDs        []string `json:"user_ids,omitempty" description:"User IDs to assign the role to"`
+	GroupIDs       []string `json:"group_ids,omitempty" description:"Group IDs to assign the role to"`
+}
+
+// OrganizationRolesReply contains the newly assigned/removed role.
+type OrganizationRolesReply struct {
+	rout.Reply
+	OrganizationID string `json:"organization_id" description:"The ID of the organization the role was applied to" example:"01J4HMNDSZCCQBTY93BF9CBF5D"`
+	Role           string `json:"role" description:"The organization responsibility role" example:"policy_manager"`
+}
+
+// AccountRolesMeRequest contains no input; it uses the authenticated caller.
+type AccountRolesMeRequest struct{}
+
+// AccountRolesMeReply holds the organization responsibility roles assigned to the authenticated caller.
+type AccountRolesMeReply struct {
+	rout.Reply
+	Roles          []OrganizationRole `json:"roles" description:"Organization responsibility roles assigned to the authenticated caller"`
+	OrganizationID string             `json:"organization_id" description:"The ID of the organization the roles apply to" example:"01J4HMNDSZCCQBTY93BF9CBF5D"`
+}
+
+func (r *OrganizationRolesRequest) Validate() error {
+	if r.Role == "" {
+		return rout.NewMissingRequiredFieldError("role")
+	}
+
+	if len(r.UserIDs) == 0 && len(r.GroupIDs) == 0 {
+		return rout.NewMissingRequiredFieldError("user_ids or group_ids")
+	}
+
+	return nil
+}
+
+func (r *AccountRolesMeRequest) Validate() error {
+	return nil
+}
+
+func (r *OrganizationRolesReply) ExampleResponse() any {
+	return ExampleOrganizationRolesReply
+}
+
+func (r *AccountRolesMeReply) ExampleResponse() any {
+	return ExampleAccountRolesMeReply
+}
+
+var ExampleOrganizationRolesRequest = OrganizationRolesRequest{
+	OrganizationID: "01J4HMNDSZCCQBTY93BF9CBF5D",
+	Role:           "policy_manager",
+	UserIDs:        []string{"01J4EXD5MM60CX4YNYN0DEE3Y1"},
+	GroupIDs:       []string{"01J4EXD5MM60CX4YNYN0DEE3Y2"},
+}
+
+var ExampleOrganizationRolesReply = OrganizationRolesReply{
+	Reply:          rout.Reply{Success: true},
+	OrganizationID: "01J4HMNDSZCCQBTY93BF9CBF5D",
+	Role:           "policy_manager",
+}
+
+var ExampleAccountRolesMeRequest = AccountRolesMeRequest{}
+
+var ExampleAccountRolesMeReply = AccountRolesMeReply{
+	Reply: rout.Reply{Success: true},
+	Roles: []OrganizationRole{
+		{
+			ID:          "policy_manager",
+			Name:        "Policy Manager",
+			Description: "Can manage all policies and procedures",
+		},
+	},
+	OrganizationID: "01J4HMNDSZCCQBTY93BF9CBF5D",
+}

fga/generate/modelparse/parse.go

@@ -8,17 +8,25 @@ import (
 )
 
 type RoleInfo struct {
-	ViewRoles    map[string][]string
-	CrudRoles    map[string][]string
-	InheritRoles map[string][]string
-	CreateRoles  map[string][]string
+	ViewRoles         map[string][]string
+	CrudRoles         map[string][]string
+	InheritRoles      map[string][]string
+	CreateRoles       map[string][]string
+	OrganizationRoles []OrganizationRole
+}
+
+type OrganizationRole struct {
+	ID          string
+	Name        string
+	Description string
 }
 
 const (
 	crudAnnotation    = "# @crud:"
 	viewAnnotation    = "# @view:"
 	inheritAnnotation = "# @inherit:"
 	createAnnotation  = "# @create:"
+	roleAnnotation    = "# @role:"
 )
 
 // ParseRoleAnnotations parses relevant annotations and role line from roles/roles.fga to determine which objects to add the roles to
@@ -28,34 +36,50 @@ func ParseRoleAnnotations(rolesFile string) (*RoleInfo, error) {
 		return nil, err
 	}
 
+	return ParseRoleAnnotationsData(data)
+}
+
+func ParseRoleAnnotationsData(data []byte) (*RoleInfo, error) {
 	lines := strings.Split(string(data), "\n")
 
 	crudMap := make(map[string][]string)
 	viewMap := make(map[string][]string)
 	inheritMap := make(map[string][]string)
 	createMap := make(map[string][]string)
+	organizationRoles := []OrganizationRole{}
 
 	var pendingCrud, pendingView, pendingInherit, pendingCreate []string
+	var pendingRoleName, pendingRoleDescription string
 
 	isSeparator := func(c rune) bool {
 		return c == ',' || c == ';' || c == ' '
 	}
 	for _, line := range lines {
 		line = strings.TrimSpace(line)
-		if strings.HasPrefix(line, crudAnnotation) {
-			pendingCrud = strings.FieldsFunc(strings.TrimPrefix(line, crudAnnotation), isSeparator)
+		if annotationValue, ok := strings.CutPrefix(line, crudAnnotation); ok {
+			pendingCrud = strings.FieldsFunc(annotationValue, isSeparator)
+		}
+
+		if annotationValue, ok := strings.CutPrefix(line, viewAnnotation); ok {
+			pendingView = strings.FieldsFunc(annotationValue, isSeparator)
 		}
 
-		if strings.HasPrefix(line, viewAnnotation) {
-			pendingView = strings.FieldsFunc(strings.TrimPrefix(line, viewAnnotation), isSeparator)
+		if annotationValue, ok := strings.CutPrefix(line, inheritAnnotation); ok {
+			pendingInherit = strings.FieldsFunc(annotationValue, isSeparator)
 		}
 
-		if strings.HasPrefix(line, inheritAnnotation) {
-			pendingInherit = strings.FieldsFunc(strings.TrimPrefix(line, inheritAnnotation), isSeparator)
+		if annotationValue, ok := strings.CutPrefix(line, createAnnotation); ok {
+			pendingCreate = strings.FieldsFunc(annotationValue, isSeparator)
 		}
 
-		if strings.HasPrefix(line, createAnnotation) {
-			pendingCreate = strings.FieldsFunc(strings.TrimPrefix(line, createAnnotation), isSeparator)
+		if annotationValue, ok := strings.CutPrefix(line, roleAnnotation); ok {
+			parts := strings.SplitN(strings.TrimSpace(annotationValue), "|", 2)
+			pendingRoleName = strings.TrimSpace(parts[0])
+			pendingRoleDescription = ""
+
+			if len(parts) == 2 {
+				pendingRoleDescription = strings.TrimSpace(parts[1])
+			}
 		}
 
 		if strings.HasPrefix(line, "define ") {
@@ -77,21 +101,32 @@ func ParseRoleAnnotations(rolesFile string) (*RoleInfo, error) {
 				}
 
 				inheritMap[role] = append(inheritMap[role], pendingInherit...)
+
+				if pendingRoleName != "" {
+					organizationRoles = append(organizationRoles, OrganizationRole{
+						ID:          role,
+						Name:        pendingRoleName,
+						Description: pendingRoleDescription,
+					})
+				}
 			}
 
 			// reset pending annotations after processing a role definition
 			pendingCrud = nil
 			pendingView = nil
 			pendingInherit = nil
 			pendingCreate = nil
+			pendingRoleName = ""
+			pendingRoleDescription = ""
 		}
 	}
 
 	return &RoleInfo{
-		CrudRoles:    crudMap,
-		ViewRoles:    viewMap,
-		InheritRoles: inheritMap,
-		CreateRoles:  createMap,
+		CrudRoles:         crudMap,
+		ViewRoles:         viewMap,
+		InheritRoles:      inheritMap,
+		CreateRoles:       createMap,
+		OrganizationRoles: organizationRoles,
 	}, nil
 }
 

fga/model/helpers.go

@@ -4,6 +4,7 @@ import (
 	_ "embed"
 	"encoding/json"
 	"maps"
+	"slices"
 	"sort"
 	"strings"
 	"sync"
@@ -12,6 +13,8 @@ import (
 	language "github.com/openfga/language/pkg/go/transformer"
 	"github.com/pkg/errors"
 	"google.golang.org/protobuf/encoding/protojson"
+
+	"github.com/theopenlane/core/fga/generate/modelparse"
 )
 
 const (
@@ -59,6 +62,10 @@ var (
 	rolesOnce  sync.Once
 	rolesModel *openfga.AuthorizationModel
 	rolesErr   error
+
+	organizationRolesOnce     sync.Once
+	organizationRoles         []modelparse.OrganizationRole
+	organizationRolesParseErr error
 )
 
 func parseAuthorizationModel(embeddedModel []byte) (*openfga.AuthorizationModel, error) {
@@ -77,7 +84,7 @@ func parseAuthorizationModel(embeddedModel []byte) (*openfga.AuthorizationModel,
 	return &model, nil
 }
 
-// GetAuthorizationModel returns the parsed embedded authorization model
+// GetCrudAuthorizationModel returns the parsed embedded authorization model
 func GetCrudAuthorizationModel() (*openfga.AuthorizationModel, error) {
 	crudOnce.Do(func() {
 		crudModel, crudErr = parseAuthorizationModel(embeddedCrudModel)
@@ -302,3 +309,56 @@ func RoleOptions() ([]string, error) {
 
 	return getRelationsOptionsForObject(rels)
 }
+
+// OrganizationRoles returns the roles parsed from fga
+func OrganizationRoles() ([]modelparse.OrganizationRole, error) {
+	organizationRolesOnce.Do(func() {
+		if _, err := GetRolesAuthorizationModel(); err != nil {
+			organizationRolesParseErr = err
+			return
+		}
+
+		roleInfo, err := modelparse.ParseRoleAnnotationsData(embeddedRolesModel)
+		if err != nil {
+			organizationRolesParseErr = err
+			return
+		}
+
+		organizationRoles = roleInfo.OrganizationRoles
+		sort.Slice(organizationRoles, func(i, j int) bool {
+			return organizationRoles[i].ID < organizationRoles[j].ID
+		})
+	})
+
+	if organizationRolesParseErr != nil {
+		return nil, organizationRolesParseErr
+	}
+
+	roles := make([]modelparse.OrganizationRole, len(organizationRoles))
+	copy(roles, organizationRoles)
+	return roles, nil
+}
+
+func getRoleIDs() ([]string, error) {
+	roles, err := OrganizationRoles()
+	if err != nil {
+		return nil, err
+	}
+
+	ids := make([]string, 0, len(roles))
+	for _, role := range roles {
+		ids = append(ids, role.ID)
+	}
+
+	return ids, nil
+}
+
+// IsOrganizationRole checks if a role is valid before it can be assigned or removed from a subject
+func IsOrganizationRole(roleID string) (bool, error) {
+	ids, err := getRoleIDs()
+	if err != nil {
+		return false, err
+	}
+
+	return slices.Contains(ids, roleID), nil
+}