https://engine.speedle.io/categories/docs/ Recent content in Docs on Speedle Hugo -- gohugo.io en-us Fri, 18 Jan 2019 21:19:44 +0800 https://engine.speedle.io/docs/api/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/docs/api/ Client libraries for Java, Python, Go, .NET, Rust and Node.js/TypeScript are in SDKs. REST APIs These are reference contracts for your configured PMS/ADS or asserter endpoint. speedle.io serves documentation and the browser Playground; it is not a hosted PMS/ADS service. Supply JSON with Content-Type: application/json, and configure TLS/mTLS and caller access controls. Policy management API Authorization decision API Token assertion webhook Policy and role-policy IDs are strings. PMS responses are flat objects; authorization permissions use permissions (plural). https://engine.speedle.io/docs/pms/policy-mgmt/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/docs/pms/policy-mgmt/ What is a Speedle policy? The Policy Management Service (PMS) manages services, authorization policies, role policies and custom functions. A policy store persists those objects using a registered storage backend. Services and authorization policies A service scopes its policies. An authorization policy grants or denies a principal permission to perform an action on a resource, optionally subject to a condition. Except for global role policies, policies do not automatically apply in another service. https://engine.speedle.io/docs/usecases/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/docs/usecases/ Application specific policies Alex Chan is a developer who is implementing a simple application with golang. His application requires Authorization and he doesn’t want to re-invent the wheel. Alex can use an open source choice like Speedle for Authorization. Centalized policy enforcement and management Jin Chen is a security manager of multinational company. His team monitor dozens of internal systems. Different systems use different authorization mechanisms, different policy languages. They are eager to find a solution to manage all these systems efficiently. https://engine.speedle.io/docs/pms/global-policy/ Fri, 18 Jan 2019 21:19:44 +0800 https://engine.speedle.io/docs/pms/global-policy/ When should a role be global? Ordinary roles are scoped to a service. When several services share a role assignment, define the assignment in the specially named global service and use that role in each service’s own authorization policies. Only global role policies are supported. A global role assignment does not itself grant every operation; each ordinary service still defines its permissions. Global authorization policies are not supported. Before running the examples Build . https://engine.speedle.io/docs/overview/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/docs/overview/ Speedle is an open-source authorization engine. Applications send it a question such as “may this user perform this action on this resource?”, and Speedle answers allow or deny according to centrally managed policies. This page connects common authorization terms to the Speedle components that implement them, and links to the guides that cover each one. The examples below use a service named library. Each policy was created through the Policy Management Service REST API and each decision was returned by the Authorization Decision Service REST API. https://engine.speedle.io/docs/pms/diagnosis/ Fri, 18 Jan 2019 15:46:59 +0800 https://engine.speedle.io/docs/pms/diagnosis/ What does diagnosis show? Diagnose explains an authorization evaluation: decision, reason, effective roles, attributes, and the policies examined. It accepts the same request context as IsAllowed; REST uses /authz-check/v1/diagnose, and both Go/gRPC use Diagnose. Diagnosis exposes policy definitions and request context. Restrict it to trusted operators using the API security controls; it is not a public debugging endpoint. Before running the examples Build ./bin/spctl, ./bin/speedle-pms and ./bin/speedle-ads using the quick start. https://engine.speedle.io/docs/decisions/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/docs/decisions/ What is an authorization decision? Speedle evaluates a subject, action and resource within a service. The application must enforce the result. Treat an evaluation error or timeout separately from a normal Deny and fail closed. REST, gRPC and embedded Go APIs have different wire representations; use their respective contracts. Before running the examples Build ./bin/spctl, ./bin/speedle-pms and ./bin/speedle-ads using the quick start. Use Go 1.26.10 or Go 1.27.3 (or a newer patch on the same release branch), Bash, curl and Python 3. https://engine.speedle.io/docs/sdks/go/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/docs/sdks/go/ The Go SDK supports the two latest Go releases and uses only the standard library. Module: github.com/teramoby/speedle-sdk/go v0.1.0, package speedle. Reference: speedle-sdk/go. The examples check the policy described in the SDKs overview. Add the dependency In a new module: go mod init example.com/speedle-example go get github.com/teramoby/speedle-sdk/go@v0.1.0 Call a local Speedle Start Speedle and create the example policy as described in the SDKs overview. Save this program as main.go: package main import ( "context" "fmt" "os" speedle "github. https://engine.speedle.io/docs/sdks/java/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/docs/sdks/java/ The Java SDK needs Java 17 or later and has no runtime dependencies. Package: io.speedle:speedle-sdk 0.1.0 on Maven Central. Reference: speedle-sdk/java. The examples check the policy described in the SDKs overview. Add the dependency Maven, a complete pom.xml: <?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.example</groupId> <artifactId>speedle-example</artifactId> <version>1.0</version> <properties> <maven.compiler.release>17</maven.compiler.release> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> </properties> <dependencies> <dependency> <groupId>io.speedle</groupId> <artifactId>speedle-sdk</artifactId> <version>0.1.0</version> </dependency> </dependencies> </project> Gradle, a complete build.gradle.kts (with a settings.gradle.kts that sets rootProject. https://engine.speedle.io/docs/logging/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/docs/logging/ Overview The following two open source projects are used to process log messages, 1. https://github.com/sirupsen/logrus 2. https://github.com/natefinch/lumberjack Logrus is a structured logger for Go (golang), and completely API compatible with the golang standard library logger. Note that logrus doesn’t support log rotation, and it is exactly the reason why we introduce the second project lumberjack, which provides a rolling logger. Logrus communicates with lumberjack using the io.Writer interface, please refer to the following diagram, https://engine.speedle.io/docs/store/mongodb/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/docs/store/mongodb/ This walkthrough uses MongoDB 7.0.16 as a single-node replica set with a persistent Docker volume. PMS writes policies and ADS follows the same database through a change stream. The example listens on loopback without authentication for local development. Production authentication, TLS and replica set configuration follow the walkthrough. MongoDB must run as a replica set or sharded cluster. ADS watches the database with a change stream, and replacing the whole policy store runs in a transaction; a standalone mongod supports neither. https://engine.speedle.io/docs/store/mysql/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/docs/store/mysql/ This guide uses MySQL 8.4 LTS and two native Speedle processes: PMS writes policies, and ADS reads the same database with a separate read-only account. The local example uses Docker and plain HTTP on loopback. For a remote deployment, use your existing MySQL server and the Security guide. 1. Build Speedle with the MySQL backend Install Git, Bash, curl, Docker and a supported Go toolchain (Go 1.26.10 or Go 1. https://engine.speedle.io/docs/sdks/node/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/docs/sdks/node/ The Node.js SDK needs Node.js 22 or later, ships ESM and CommonJS builds with TypeScript types, and has no runtime dependencies. Package: @speedle/sdk 0.1.0 on npm, available when published. Reference: speedle-sdk/node. The examples check the policy described in the SDKs overview. Add the dependency In a new ES module package (available when published): mkdir speedle-example cd speedle-example npm init -y npm pkg set type=module npm install @speedle/sdk@0.1.0 Call a local Speedle Start Speedle and create the example policy as described in the SDKs overview. https://engine.speedle.io/docs/store/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/docs/store/ Built-in stores and extension contracts The standalone binaries register file, etcd, MongoDB and MySQL implementations under pkg/store. Availability does not mean identical operational guarantees; review backend authentication, persistence, transaction and watch behavior for your deployment. The configuration below illustrates property names; running etcd/MongoDB deployments is outside this local example. A full backend implements pms.PolicyStoreManager: service, authorization-policy, role-policy and function management, snapshot reads and watch/stop. ADS accepts the narrower PolicyStoreManagerADS read/watch interface. https://engine.speedle.io/docs/pms/discover/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/docs/pms/discover/ What discovery does Discovery records requests and returns allowed=true with reason 5 for a successful recording operation. It does not prove that an existing policy authorized the operation. Use it only in an isolated test environment, review generated grants, and restore normal is-allowed enforcement afterwards. Assertion or storage errors must still be handled; never treat an error as an authorization grant. Start a reproducible local example Build the binaries using Quick Start, then run all terminals from the checkout root. https://engine.speedle.io/docs/sdks/python/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/docs/sdks/python/ The Python SDK needs Python 3.10 or later; its only runtime dependency is httpx. It has a sync Client and an asyncio AsyncClient with the same arguments. Package: speedle 0.1.0 on PyPI. Reference: speedle-sdk/python. The examples check the policy described in the SDKs overview. Add the dependency With pip, in a virtual environment: python3 -m venv .venv . .venv/bin/activate pip install speedle==0.1.0 Or with uv, in a uv project: https://engine.speedle.io/docs/spdl/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/docs/spdl/ Syntax Keywords grant, deny, user, group, entity, role, from, on, if and in have special meanings in their syntax positions. Statement keywords are case-insensitive. In conditions, use in or IN; function names are case-sensitive. Principal, action and resource names are also case-sensitive. The current parser accepts keyword-like names in some name positions, so a blanket prohibition is not a validation rule. Prefer unambiguous names for review and client interoperability. https://engine.speedle.io/docs/pms/ Fri, 18 Jan 2019 21:19:44 +0800 https://engine.speedle.io/docs/pms/ Policy Management Global Policy Policy Discovery Policy Diagnosis https://engine.speedle.io/docs/store/etcd/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/docs/store/etcd/ This walkthrough uses an external etcd v3.6.14 server with a persistent Docker volume. PMS writes policies and ADS watches the same key prefix. The single-node example listens on loopback and uses plain HTTP for local development. Production TLS and cluster configuration follow the walkthrough. 1. Build Speedle Prepare Bash, Git, curl, Docker and Go 1.26.10 or Go 1.27.3. Start Docker, then build the native services: git clone --depth 1 https://github. https://engine.speedle.io/docs/idd/ Thu, 17 Jan 2019 13:20:07 +0800 https://engine.speedle.io/docs/idd/ What is an identity domain? An identity domain (idd) is an explicit namespace for a principal. Two users named user1 can belong to different domains. The string is supplied by trusted integration code or a configured token asserter; it is not proof of authentication. Speedle does not infer or validate a provider’s tenant model merely from the domain name. Represent domains in policies and requests grant user user1 from github read book grant user user1 from IDCS. https://engine.speedle.io/docs/sdks/dotnet/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/docs/sdks/dotnet/ The .NET SDK targets .NET 8 or later and has no dependencies. Package: Speedle.Sdk 0.1.0 on NuGet, namespace Speedle.Sdk. Reference: speedle-sdk/dotnet. The examples check the policy described in the SDKs overview. Add the dependency In a new console project: dotnet new console -o SpeedleExample cd SpeedleExample dotnet add package Speedle.Sdk --version 0.1.0 Call a local Speedle Start Speedle and create the example policy as described in the SDKs overview. Replace Program. https://engine.speedle.io/docs/sdks/rust/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/docs/sdks/rust/ The Rust SDK needs Rust 1.75 or later. It is async on tokio and reqwest (rustls); the blocking feature adds the blocking client used below. Crate: speedle 0.1.0 on crates.io. Reference: speedle-sdk/rust. The examples check the policy described in the SDKs overview. Add the dependency In a new package: cargo new speedle-example cd speedle-example cargo add speedle@0.1.0 --features blocking Call a local Speedle Start Speedle and create the example policy as described in the SDKs overview. https://engine.speedle.io/docs/assertor/ Mon, 21 Jan 2019 09:28:30 +0800 https://engine.speedle.io/docs/assertor/ What does a token asserter do? A configured asserter validates a token and returns explicit principals, including their identity domains. Speedle can then evaluate policies using those identities. A production implementation must validate the token’s signature or introspection result, issuer, audience, expiry and any provider-specific requirements. The webhook alone does not establish compatibility with arbitrary OAuth/OIDC tokens. The Token Assertion Plugin API uses integer errCode and an optional attribute object, not a typed attribute array. https://engine.speedle.io/docs/deployment/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/docs/deployment/ Choose a deployment mode Use embedded mode to run the evaluator in your Go process. Use standalone PMS and ADS when applications call Speedle over REST or gRPC. The Quick Start provides a complete local policy-management and authorization walkthrough. Build with current Go Use Go 1.26.10 or Go 1.27.3 (or a newer patch on the same release branch) (Go 1.27.3 is recommended), Git and a shell on Linux or macOS. https://engine.speedle.io/docs/sdks/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/docs/sdks/ The Speedle SDKs are client libraries for the decision API POST /authz-check/v1/is-allowed. They work with a self-hosted Speedle ADS and with Speedle Cloud. Each language page shows how to add the package and gives a complete, tested program for both. The source and the full reference are in teramoby/speedle-sdk. Packages All packages are version 0.1.0. Each language page shows the install command. Java: Maven Central io.speedle:speedle-sdk, published. Python: PyPI speedle, published. https://engine.speedle.io/docs/security/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/docs/security/ Protect both API transports Speedle’s standalone PMS and ADS expose REST and gRPC. Both now use the same --insecure, --cert, --key, --client-cert and --force-client-cert transport settings. Invalid certificates or trust configuration cause startup to fail; secure mode does not fall back to plaintext. TLS encrypts the connection and authenticates the server. To require authenticated clients, provide a client CA with --client-cert and set --force-client-cert=true. Without that flag, a configured CA validates a client certificate only when the client supplies one. https://engine.speedle.io/docs/versions/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/docs/versions/ Speedle releases Use the GitHub Releases page for published versions and release notes. v1.6.0 is the version pinned by the current embedded Go walkthrough. Use an explicit released version for reproducible module dependencies; the embedded guide explains the setup. Historical Oracle Speedle release Version 0.1.0 was the original open-source release, including policy management, authorization decisions, the command-line tool and integration samples. The historical 0.2.0 planning note is not the current Speedle release roadmap. https://engine.speedle.io/docs/custom-function/ Mon, 21 Jan 2019 10:43:02 +0800 https://engine.speedle.io/docs/custom-function/ Why use a custom function? SPDL conditions can call a configured function when built-in operators or functions do not express the required rule. Speedle calls its REST endpoint with POST {"params":[...]} and expects {"result":...} or {"error":"..."}. Parameter order/types and the result type must match the condition. Function failures are evaluation errors; applications must fail closed. Start the local example This example accepts numeric values from 100 to 50000. Wrong parameter types or an empty parameter list return an HTTP error. https://engine.speedle.io/docs/api/decision_api/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/docs/api/decision_api/ Reference for your configured ADS. Request attributes are typed arrays; diagnostic attributes are objects. Security and endpoint configuration. This is a contract reference, not a backend hosted by speedle.io. (function() { var url = "\/swagger\/policy-check.yaml"; const ui = SwaggerUIBundle({ url: url, dom_id: '#swagger-ui', deepLinking: true, presets: [ SwaggerUIBundle.presets.apis ], plugins: [ SwaggerUIBundle.plugins.DownloadUrl ], validatorUrl: null, layout: " https://engine.speedle.io/integrations/ Mon, 10 Apr 2017 16:41:54 +0100 https://engine.speedle.io/integrations/ https://engine.speedle.io/docs/api/management_api/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/docs/api/management_api/ Reference for your configured PMS. Requests and responses are JSON; policy IDs are strings and responses are flat objects. Security and endpoint configuration. This is a contract reference, not a backend hosted by speedle.io. (function() { var url = "\/swagger\/policy-manage.yaml"; const ui = SwaggerUIBundle({ url: url, dom_id: '#swagger-ui', deepLinking: true, presets: [ SwaggerUIBundle.presets.apis ], plugins: [ SwaggerUIBundle. https://engine.speedle.io/docs/ Thu, 17 Jan 2019 13:20:07 +0800 https://engine.speedle.io/docs/ https://engine.speedle.io/docs/api/asserter_api/ Mon, 01 Jan 0001 00:00:00 +0000 https://engine.speedle.io/docs/api/asserter_api/ Webhook reference. errCode is an integer and attributes is an object. Configure the actual endpoint in the ADS asserter configuration. Security and endpoint configuration. This is a contract reference, not a backend hosted by speedle.io. (function() { var url = "\/swagger\/asserter.yaml"; const ui = SwaggerUIBundle({ url: url, dom_id: '#swagger-ui', deepLinking: true, presets: [ SwaggerUIBundle.presets.apis ], plugins: [ SwaggerUIBundle.