{"id":36223654,"url":"https://github.com/raskell-io/sentinel-agent-auth","last_synced_at":"2026-01-18T09:19:07.303Z","repository":{"id":331314933,"uuid":"1122795868","full_name":"raskell-io/sentinel-agent-auth","owner":"raskell-io","description":"Authentication agent for Sentinel reverse proxy - JWT, API keys, and OIDC","archived":false,"fork":false,"pushed_at":"2026-01-10T21:58:36.000Z","size":94,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-11T10:49:49.190Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/raskell-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-25T14:26:46.000Z","updated_at":"2026-01-10T21:58:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/raskell-io/sentinel-agent-auth","commit_stats":null,"previous_names":["raskell-io/sentinel-agent-auth"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/raskell-io/sentinel-agent-auth","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raskell-io%2Fsentinel-agent-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raskell-io%2Fsentinel-agent-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raskell-io%2Fsentinel-agent-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raskell-io%2Fsentinel-agent-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/raskell-io","download_url":"https://codeload.github.com/raskell-io/sentinel-agent-auth/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raskell-io%2Fsentinel-agent-auth/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28534156,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-11T05:02:25.655Z","updated_at":"2026-01-18T09:19:07.285Z","avatar_url":"https://github.com/raskell-io.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sentinel-agent-auth\n\nAuthentication and authorization agent for [Sentinel](https://github.com/raskell-io/sentinel) reverse proxy. Supports JWT/Bearer tokens, OIDC/OAuth 2.0, API keys, Basic authentication, SAML SSO, and mTLS client certificates.\n\n## Features\n\n### Authentication (AuthN)\n- **JWT/Bearer tokens** - HS256, RS256, ES256 and other algorithms\n- **OIDC/OAuth 2.0** - OpenID Connect with automatic JWKS key rotation\n- **API keys** - Simple header-based authentication\n- **Basic auth** - Username/password authentication\n- **SAML SSO** - Enterprise single sign-on with session persistence\n- **mTLS Client Certificates** - X.509 certificate-based authentication\n\n### Authorization (AuthZ)\n- **Cedar Policy Engine** - Policy-as-code authorization with fine-grained access control\n\n### Token Services\n- **Token Exchange (RFC 8693)** - Convert between token types (SAML to JWT, external to internal JWT)\n\n### General\n- Configurable user ID and auth method headers\n- Fail-open mode for graceful degradation\n- Comprehensive audit logging\n\n## Documentation\n\n- [Configuration Reference](docs/configuration.md) - Complete configuration options\n- [SAML Authentication](docs/saml.md) - SAML SSO setup and IdP integration\n- [Session Management](docs/session-management.md) - Session persistence and lifecycle\n- [OIDC Authentication](docs/oidc.md) - OIDC/OAuth 2.0 with JWKS\n- [mTLS Authentication](docs/mtls.md) - Client certificate authentication\n- [Authorization](docs/authorization.md) - Cedar policy engine guide\n- [Token Exchange](docs/token-exchange.md) - RFC 8693 token exchange\n\n## Installation\n\n### From crates.io\n\n```bash\ncargo install sentinel-agent-auth\n```\n\n### From source\n\n```bash\ngit clone https://github.com/raskell-io/sentinel-agent-auth\ncd sentinel-agent-auth\ncargo build --release\n```\n\n## Usage\n\n```bash\nsentinel-auth-agent --socket /var/run/sentinel/auth.sock \\\n  --jwt-secret \"your-secret-key\" \\\n  --api-keys \"key1:app1,key2:app2\"\n```\n\n### Command Line Options\n\n| Option | Environment Variable | Description | Default |\n|--------|---------------------|-------------|---------|\n| `--socket` | `AGENT_SOCKET` | Unix socket path | `/tmp/sentinel-auth.sock` |\n| `--jwt-secret` | `JWT_SECRET` | JWT secret key (for HS256) | - |\n| `--jwt-public-key` | `JWT_PUBLIC_KEY` | JWT public key file (for RS/ES) | - |\n| `--jwt-algorithm` | `JWT_ALGORITHM` | JWT algorithm | `HS256` |\n| `--jwt-issuer` | `JWT_ISSUER` | Required JWT issuer | - |\n| `--jwt-audience` | `JWT_AUDIENCE` | Required JWT audience | - |\n| `--api-keys` | `API_KEYS` | API keys (key:name,key:name) | - |\n| `--api-key-header` | `API_KEY_HEADER` | API key header name | `X-API-Key` |\n| `--basic-auth-users` | `BASIC_AUTH_USERS` | Basic auth users (user:pass) | - |\n| `--user-id-header` | `USER_ID_HEADER` | Header for user ID | `X-User-Id` |\n| `--auth-method-header` | `AUTH_METHOD_HEADER` | Header for auth method | `X-Auth-Method` |\n| `--fail-open` | `FAIL_OPEN` | Allow on auth failure | `false` |\n| `--verbose` | `AUTH_VERBOSE` | Enable debug logging | `false` |\n\nSee [Configuration Reference](docs/configuration.md) for OIDC, mTLS, Cedar authorization, and token exchange options.\n\n## Authentication Methods\n\n### JWT/Bearer Token\n\n```bash\n# Configure with HS256 secret\nsentinel-auth-agent --jwt-secret \"your-32-char-minimum-secret-key\"\n\n# Configure with RS256 public key\nsentinel-auth-agent --jwt-algorithm RS256 --jwt-public-key /path/to/public.pem\n\n# With issuer and audience validation\nsentinel-auth-agent \\\n  --jwt-secret \"secret\" \\\n  --jwt-issuer \"https://auth.example.com\" \\\n  --jwt-audience \"my-api\"\n```\n\nClient request:\n```bash\ncurl -H \"Authorization: Bearer eyJ...\" http://localhost:8080/api\n```\n\n### API Key\n\n```bash\n# Configure API keys\nsentinel-auth-agent --api-keys \"sk_live_abc123:production,sk_test_xyz:development\"\n```\n\nClient request:\n```bash\ncurl -H \"X-API-Key: sk_live_abc123\" http://localhost:8080/api\n```\n\n### Basic Auth\n\n```bash\n# Configure users\nsentinel-auth-agent --basic-auth-users \"admin:secretpass,user:userpass\"\n```\n\nClient request:\n```bash\ncurl -u \"admin:secretpass\" http://localhost:8080/api\n```\n\n### OIDC/OAuth 2.0\n\nConfigure OIDC with automatic JWKS key fetching and refresh:\n\n```kdl\nconfig {\n    oidc {\n        enabled true\n        issuer \"https://auth.example.com\"\n        jwks-url \"https://auth.example.com/.well-known/jwks.json\"\n        audience \"my-api\"\n        required-scopes \"read,write\"\n    }\n}\n```\n\nClient request:\n```bash\ncurl -H \"Authorization: Bearer \u003coauth2-access-token\u003e\" http://localhost:8080/api\n```\n\n### mTLS Client Certificates\n\nAuthenticate clients using X.509 certificates (requires Sentinel proxy to forward client cert):\n\n```kdl\nconfig {\n    mtls {\n        enabled true\n        client-cert-header \"X-Client-Cert\"\n        allowed-dns \"CN=service.example.com,O=Example\"\n        extract-cn-as-user true\n    }\n}\n```\n\nThe Sentinel proxy forwards the client certificate in a header after TLS termination.\n\n## Authorization\n\nAfter authentication, requests can be authorized using Cedar policies:\n\n```kdl\nconfig {\n    authz {\n        enabled true\n        policy-file \"/etc/sentinel/policies/auth.cedar\"\n        default-decision \"deny\"\n    }\n}\n```\n\nExample Cedar policy:\n```cedar\npermit(\n    principal,\n    action == Action::\"GET\",\n    resource\n) when {\n    resource.path like \"/api/public/*\"\n};\n\npermit(\n    principal,\n    action,\n    resource\n) when {\n    principal.roles.contains(\"admin\")\n};\n```\n\nSee [Authorization Guide](docs/authorization.md) for more details.\n\n## Headers Added\n\nOn successful authentication, the agent adds these headers to the request:\n\n| Header | Description | Example |\n|--------|-------------|---------|\n| `X-User-Id` | Authenticated user ID | `user123` |\n| `X-Auth-Method` | Authentication method used | `jwt`, `oidc`, `mtls`, `api_key`, `basic`, `saml` |\n| `X-Auth-Claim-*` | JWT/OIDC claims (for token auth) | `X-Auth-Claim-role: admin` |\n| `X-Client-Cert-*` | Certificate info (for mTLS) | `X-Client-Cert-CN: service.example.com` |\n\n## Configuration\n\n### Sentinel Proxy Configuration\n\n```kdl\nagents {\n    agent \"auth\" {\n        type \"custom\"\n        transport \"unix_socket\" {\n            path \"/var/run/sentinel/auth.sock\"\n        }\n        events [\"request_headers\"]\n        timeout-ms 50\n        failure-mode \"open\"\n    }\n}\n\nroutes {\n    route \"api\" {\n        matches { path-prefix \"/api\" }\n        upstream \"backend\"\n        agents [\"auth\"]\n    }\n}\n```\n\n### Docker/Kubernetes\n\n```yaml\n# Environment variables\nJWT_SECRET: \"your-secret-key\"\nJWT_ISSUER: \"https://auth.example.com\"\nAPI_KEYS: \"key1:app1,key2:app2\"\nFAIL_OPEN: \"false\"\n```\n\n## Response Codes\n\n| Code | Description |\n|------|-------------|\n| 401 | No valid credentials provided |\n| (passthrough) | Credentials valid, request forwarded |\n\nThe agent adds `WWW-Authenticate: Bearer realm=\"sentinel\"` header on 401 responses.\n\n## Development\n\n```bash\n# Run with debug logging\nRUST_LOG=debug cargo run -- \\\n  --socket /tmp/test.sock \\\n  --jwt-secret \"test-secret-at-least-32-characters\" \\\n  --api-keys \"test-key:test-app\"\n\n# Run tests\ncargo test\n```\n\n## Security Considerations\n\n- Always use strong, random JWT secrets (minimum 32 characters for HS256)\n- Store secrets in environment variables, not command line args\n- Use RS256/ES256 with public keys for production when possible\n- Enable `fail_open` cautiously - only for non-critical paths\n- Consider rate limiting alongside authentication\n\n## License\n\nApache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraskell-io%2Fsentinel-agent-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraskell-io%2Fsentinel-agent-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraskell-io%2Fsentinel-agent-auth/lists"}