#Understanding Service Roles and References in Vidos

Service roles and their references form part of Vidos's security model, enabling controlled communication between services while maintaining proper isolation and security boundaries. Understanding this concept is essential for building secure, well-structured Vidos deployments.

#What are Service Roles?

A service role is a security principal that grants a service instance the permissions it needs to interact with other resources in Vidos. Service roles:

• Define the permissions boundary for service-to-service communication
• Allow services to act on behalf of specific security contexts
• Enable secure, principle-of-least-privilege access patterns
• Provide clear security boundaries between different services

Each service role has a defined set of permissions expressed through IAM policy documents, determining exactly what actions the service can perform when using that role.

#Types of Service Roles

Vidos supports two primary types of service roles, each serving different operational needs:

#Account Roles

Account roles are owned and managed by your account, providing you with complete control over their permissions and lifecycle:

• Created and managed by account administrators
• Customizable permissions for specific use cases
• Explicit control over role permissions and policies
• Suitable for custom access patterns that require fine-grained control
• Visible in your account's IAM configuration

#Managed Roles

Managed roles are provided and maintained by Vidos, offering pre-configured permissions for common service interactions:

• Automatically created and managed by Vidos
• Pre-configured for standard service communication patterns
• Updated automatically with service updates
• Optimized for typical service interactions
• Simplify security management for standard configurations

Both role types serve important purposes in a comprehensive security strategy, with account roles providing customization and managed roles offering simplicity.

#Service Role References

A service role reference is how one service indicates which role it should use when interacting with another service. These references are declarative pointers that:

• Identify whether to use an account or managed role
• Specify the exact role resource to use
• Are included in service instance configurations
• Enable dynamic role selection in different contexts

By using references rather than embedding roles directly, Vidos enables flexible security configurations and clear role boundaries.

#How Service Role References Work

Service role references use a simple structure that identifies both the role type and the specific role identifier:

{
    "owner": "account",
    "resourceId": "custom-verifier-role"
}

Or for managed roles:

{
    "owner": "managed",
    "resourceId": "resolve_all_actions"
}

When a service needs to communicate with another service, it:

1. Looks up the appropriate service role reference in its configuration
2. Resolves the reference to the actual role
3. Assumes that role for the duration of the communication
4. Operates within the permissions boundary of that role

This pattern ensures that services only have the permissions they need, when they need them.

#Service Roles in Action

Service roles facilitate secure interactions across various scenarios:

#Gateway Service Routing

When a gateway routes requests to backend services, it uses service role references to determine which role to assume:

{
    "paths": {
        "verify": {
            "destination": {
                "type": "instance",
                "service": "verifier",
                "resourceId": "main-verifier",
                "serviceRole": {
                    "owner": "managed",
                    "resourceId": "verifier_all_actions"
                }
            }
        }
    }
}

In this example, the gateway assumes the "verifier-role" managed role when routing requests to the verifier service.

#Service Dependencies

When one service depends on another, it uses service role references to define the security context for those dependencies:

{
    "policies": {
        "validate": {
            "validator": {
                "type": "instance",
                "resourceId": "main-validator",
                "serviceRole": {
                    "owner": "account",
                    "resourceId": "custom-validator-role"
                }
            }
        }
    }
}

Here, an authorizer service specifies that it should use a custom account role when communicating with the validator service.

#Benefits of Service Roles

The service role system provides several key benefits for Vidos deployments:

#Security Boundaries

• Creates clear permission boundaries between services
• Enforces the principle of least privilege
• Prevents privilege escalation between services
• Enables precise permission auditing

#Operational Flexibility

• Allows different roles for different communication patterns
• Supports role rotation without service reconfiguration
• Enables gradual permission refinement
• Facilitates clear security documentation

#Simplified Management

• Centralizes permission management in IAM
• Provides consistency across service interactions
• Makes security intent explicit in configurations
• Separates security concerns from functional configuration

#Best Practices

When working with service roles and references in Vidos:

#Role Selection

• Use managed roles for standard interactions to benefit from automatic updates
• Create account roles for custom permission requirements
• Document why custom roles are needed when not using managed roles
• Regularly review if custom roles can be replaced with managed roles

#Permission Scoping

• Apply the principle of least privilege to all role permissions
• Scope permissions to specific resource patterns rather than using wildcards
• Review and refine permissions regularly
• Consider time-bound permissions for sensitive operations

#Reference Management

• Use consistent naming patterns for role resources
• Document the intent of each service role reference
• Keep service role references in the appropriate configuration context
• Avoid hardcoding role identifiers in application code

#Security Monitoring

• Monitor role assumption patterns for anomalies
• Audit service role permissions regularly
• Test role permissions in non-production environments
• Document expected service communication patterns

#Related Concepts

Service roles and references connect with other important Vidos concepts:

• IAM Policy Documents: Define the permissions associated with service roles
• IAM Scopes: Establish the context in which service roles operate
• Service Instance References: Use service role references to enable secure instance access
• Configurations: Include service role references as part of service configuration
• Instances: Use service roles to interact with other instances

By understanding and effectively using service roles and references, you can build Vidos deployments with clear security boundaries, explicit permission management, and well-structured service interactions.