Ory Keto Documentation

repository·master·Indexed 26 days ago

https://github.com/ory/keto

An open-source, cloud-native authorization server based on Google's Zanzibar model. Ory Keto provides scalable, low-latency Relationship-Based Access Control (ReBAC) and supports the Ory Permission Language for defining access control policies. It includes a Go API client, a gRPC client, and can be deployed as a self-hosted service or via the managed Ory Network.

Tokens
53.3K
Snippets
82
Records
230
Agent score
87%

What's inside Ory Keto

  1. Overview of Ory Keto

    master

    Ory Keto is an open source implementation of Google's Zanzibar consistent, global authorization system. It is designed for scalable, high-performance permission management using Relationship-Based Access Control (ReBAC) and the Ory Permission Language.

    Key features include:

    • Low-latency permission checks (sub-10ms).
    • Horizontal scaling to support billions of relationships.
    • Support for the Ory Permission Language to define access control policies.
    • High availability and consistency.
  2. Understand the Ory Ecosystem

    master

    Ory Keto is part of a larger ecosystem of identity and access management services designed to run in container orchestration systems (Kubernetes, CloudFoundry, etc.).

    • Ory Keto: A policy decision point that uses access control policies (similar to AWS IAM) to determine if a subject is authorized to perform an action on a resource.
    • Ory Kratos: Identity and User Management system for login, registration, MFA, and profile management.
    • Ory Hydra: OAuth2 and OpenID Connect provider.
    • Ory Oathkeeper: Identity & Access Proxy (IAP) for authentication, authorization, and request mutation.
  3. Understand the Ory Permission Language syntax

    master

    The Ory Permission Language is a syntactical subset of TypeScript used to define fine-grained permissions in Keto. It allows developers to define namespaces, relations, and permission logic using a familiar, developer-friendly syntax. Because it is a subset of TypeScript, you can use TypeScript type definitions for Namespace or Context to get IDE context help while writing configurations.

    Key characteristics:

    • Namespaces: Defined using class declarations that implements Namespace.
    • Relations: Defined in a related block to specify many-to-many relationships between entities.
    • Permissions: Defined in a permits block as functions that evaluate to a boolean based on a ctx (context) object.
    • Context: The ctx object provides the subject (e.g., a user ID) for which the permission check is being performed.
  4. Access Ory Keto Documentation

    master

    The official Ory Keto documentation provides comprehensive guides for installation, configuration, API usage, and permission modeling. Use these resources to integrate Keto into your application:

    • Installation guides: Instructions for setting up Keto in various environments.
    • Configuration reference: Detailed documentation of all configuration keys and options.
    • HTTP API documentation: Reference for the RESTful API surface.
    • Ory Permission Language guide: Guidance on modeling access control policies using Keto's permission language.
  5. Use the Ory Keto gRPC Client

    master
    The proto package provides the generated gRPC client for Ory Keto. This client allows you to interact with Ory Keto services using gRPC instead of HTTP. To use this client, you may need to ensure the protocol buffer compiler, protoc, is installed on your system to handle .proto files containing service and message definitions.
  6. Deployment options for Ory Keto

    master

    Ory Keto can be deployed in two primary ways:

    1. Ory Network (Managed Service): A cloud-native managed service (branded as Ory Permissions) that is API-compatible with the open source Keto server. It includes built-in identity management, OAuth2/OIDC, and a web-based console.
    2. Self-hosted: You can run the open source version on Linux, macOS, Windows, or Docker, using databases like PostgreSQL, MySQL, or CockroachDB. For business-critical production environments, the Ory Enterprise License (OEL) provides enterprise features, CVE patches, and SLAs.
  7. Quickstart: Set up Ory Keto with Ory CLI

    master

    To quickly experiment with Ory Keto, install the Ory CLI, create a project, and manage relationships using the following steps.

    1. Install the Ory CLI

    # Install the Ory CLI if you do not have it yet:
    bash <(curl https://raw.githubusercontent.com/ory/meta/master/install.sh) -b . ory
    sudo mv ./ory /usr/local/bin/

    2. Authenticate and Create a Project

    # Sign in or sign up
    ory auth
    
    # Create a new project
    ory create project --create-workspace "Ory Open Source" --name "GitHub Quickstart" --use-project

    3. Define a Namespace and Manage Relationships

    Use the Ory Permission Language to define a namespace, apply it, and then create/check permissions.

    # Write a simple configuration with one namespace
    echo "class Document implements Namespace {}" > config.ts
    
    # Apply that configuration
    ory patch opl -f file://./config.ts
    
    # Create a relationship that grants tom access to a document
    echo "Document:secret#read@tom" \
      | ory parse relation-tuples --format=json - \
      | ory create relation-tuples -
    
    # List all relationships
    ory list relation-tuples
    
    # Check if tom can read the document
    ory check permission Document:secret read tom
    # Install the Ory CLI if you do not have it yet:
    bash <(curl https://raw.githubusercontent.com/ory/meta/master/install.sh) -b . ory
    sudo mv ./ory /usr/local/bin/
    
    # Sign in or sign up
    ory auth
    
    # Create a new project
    ory create project --create-workspace "Ory Open Source" --name "GitHub Quickstart" --use-project
    
    # Write a simple configuration with one namespace
    echo "class Document implements Namespace {}" > config.ts
    
    # Apply that configuration
    ory patch opl -f file://./config.ts
    
    # Create a relationship that grants tom access to a document
    echo "Document:secret#read@tom" \
      | ory parse relation-tuples --format=json - \
      | ory create relation-tuples -
    
    # List all relationships
    ory list relation-tuples
    
    # Check if tom can read the document
    ory check permission Document:secret read tom
  8. Install the Ory Keto Go API Client

    master

    To use the Ory Keto Go API client, install the required dependencies and import the package into your project.

    Dependencies:

    go get github.com/stretchr/testify/assert
    go get golang.org/x/oauth2
    go get golang.org/x/net/context

    Import:

    import client "github.com/ory/keto-client-go"

    If you need to use a proxy, set the HTTP_PROXY environment variable:

  9. Upgrade SDKs to version 0.4.0-sandbox

    master

    In version 0.4.0-sandbox, the SDKs previously hosted within the repository were removed. You must now use the official SDKs published on their respective package repositories:

    • Python: ory-keto-client (PyPI)
    • PHP: ory/keto-client (Packagist)
    • Go: ory/keto-client-go (GitHub)
    • NodeJS: @oryd/keto-client (NPM, includes TypeScript definitions)
    • Java: sh.ory.keto/keto-client (Maven)
    • Ruby: ory-keto-client (RubyGems)

    Breaking Changes:

    • Go SDK: Several structs and fields have been renamed. You will need to update your code to match the new names.
    • Other SDKs: These have migrated to openapi-generator. There is no official migration path for these changes, so you may need to manually adjust your implementation to accommodate the new generated code structures.
  10. Configure the Server URL in the Go Client

    master

    The Go client allows you to configure which server to target using context values. By default, it uses the first server defined in the OpenAPI specification.

    Select a specific server index

    To use a server other than the one at index 0, set the client.ContextServerIndex value in your context.

    Configure templated server variables

    You can provide variables (like basePath) for templated URLs by setting client.ContextServerVariables in your context.

    Per-operation URL overrides

    You can override the server URL for a specific operation using the OperationServers map in the Configuration. Operations are identified by the string format "{classname}Service.{nickname}". You can override these via context using:

    • client.ContextOperationServerIndices: A map of operation identifiers to server indices.
    • client.ContextOperationServerVariables: A map of operation identifiers to variable maps.
    // Select server index
    ctx := context.WithValue(context.Background(), client.ContextServerIndex, 1)
    
    // Set templated variables
    ctx := context.WithValue(context.Background(), client.ContextServerVariables, map[string]string{
    	"basePath": "v2",
    })
    
    // Override specific operation server index
    ctx := context.WithValue(context.Background(), client.ContextOperationServerIndices, map[string]int{
    	"{classname}Service.{nickname}": 2,
    })
    
    // Override specific operation server variables
    ctx = context.WithValue(context.Background(), client.ContextOperationServerVariables, map[string]map[string]string{
    	"{classname}Service.{nickname}": {
    		"port": "8443",
    	},
    })