{"id":26497800,"url":"https://github.com/openchami/tokensmith","last_synced_at":"2025-03-20T13:59:43.287Z","repository":{"id":283041823,"uuid":"949993062","full_name":"OpenCHAMI/tokensmith","owner":"OpenCHAMI","description":"JWT handling code for the OpenCHAMI project","archived":false,"fork":false,"pushed_at":"2025-03-18T08:49:52.000Z","size":1,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-18T09:38:46.941Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenCHAMI.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}},"created_at":"2025-03-17T13:14:01.000Z","updated_at":"2025-03-18T08:49:55.000Z","dependencies_parsed_at":"2025-03-18T09:38:54.813Z","dependency_job_id":"8a9e4c0f-2b99-4a53-b4a1-eca395fb9c4f","html_url":"https://github.com/OpenCHAMI/tokensmith","commit_stats":null,"previous_names":["openchami/tokensmith"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCHAMI%2Ftokensmith","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCHAMI%2Ftokensmith/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCHAMI%2Ftokensmith/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCHAMI%2Ftokensmith/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenCHAMI","download_url":"https://codeload.github.com/OpenCHAMI/tokensmith/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244623937,"owners_count":20483244,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":"2025-03-20T13:59:42.627Z","updated_at":"2025-03-20T13:59:43.278Z","avatar_url":"https://github.com/OpenCHAMI.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TokenSmith\n\nTokenSmith bridges external OIDC user identity with internal identity and access management using signed JWTs. It provides internal service-to-service identity and access management, along with a standalone chi middleware for JWT verification using PKI.\n\n## Token Flow\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant OIDC\n    participant TokenSmith\n    participant ServiceA\n    participant ServiceB\n\n    %% User Authentication Flow\n    User-\u003e\u003eOIDC: Authenticate\n    OIDC--\u003e\u003eUser: ID Token\n    User-\u003e\u003eTokenSmith: Exchange ID Token\n    TokenSmith--\u003e\u003eUser: Internal JWT\n    User-\u003e\u003eServiceA: Request with Internal JWT\n\n    %% Service-to-Service Flow\n    ServiceA-\u003e\u003eTokenSmith: Request Service Token\n    TokenSmith--\u003e\u003eServiceA: Service JWT\n    ServiceA-\u003e\u003eServiceB: Request with Service JWT\n    ServiceB-\u003e\u003eServiceB: Verify JWT (Middleware)\n```\n\n## Features\n\n- **Identity Bridging**\n  - Exchange external OIDC tokens for internal JWTs\n  - Map external identities to internal service identities\n  - Group-based authorization and scope management\n  - Support for multiple OIDC providers (Keycloak, Hydra, Authelia)\n\n- **Service-to-Service Authentication**\n  - Secure internal service communication\n  - PKI-based JWT signing and verification\n  - Service-specific claims and scopes\n  - Automatic token validation\n\n- **JWT Middleware**\n  - Standalone chi middleware for JWT verification\n  - PKI-based signature validation\n  - Support for RSA key pairs and JWKS\n  - Scope-based authorization\n  - Service-to-service authentication\n  - Extensible claims handling\n\n- **OIDC Provider Support**\n  - Keycloak integration\n  - Hydra integration\n  - Authelia integration\n  - Extensible provider interface\n\n## Container Deployment\n\nTokenSmith can be deployed using Docker. The following environment variables can be used to configure the service:\n\n### Required Environment Variables\n\n| Environment Variable | Description | Default |\n|---------------------|-------------|---------|\n| `TOKENSMITH_ISSUER` | The issuer URL for the token service | `https://tokensmith.openchami.dev` |\n| `TOKENSMITH_CLUSTER_ID` | The ID of the cluster | `default-cluster` |\n| `TOKENSMITH_OPENCHAMI_ID` | The ID of the OpenCHAMI instance | `default-openchami` |\n| `TOKENSMITH_CONFIG` | Path to the configuration file | `/tokensmith/config.json` |\n| `TOKENSMITH_KEY_DIR` | Directory for storing JWT keys | `/tokensmith/keys` |\n| `TOKENSMITH_OIDC_PROVIDER` | OIDC provider type (hydra, keycloak, authelia) | `hydra` |\n| `TOKENSMITH_PORT` | HTTP server port | `8080` |\n\n### OIDC Provider Credentials\n\nDepending on your chosen OIDC provider, you'll need to set the following credentials:\n\n#### Hydra\n- `HYDRA_CLIENT_ID` - Client ID for Hydra\n- `HYDRA_CLIENT_SECRET` - Client Secret for Hydra\n\n#### Keycloak\n- `KEYCLOAK_CLIENT_ID` - Client ID for Keycloak\n- `KEYCLOAK_CLIENT_SECRET` - Client Secret for Keycloak\n\n#### Authelia\n- `AUTHELIA_CLIENT_ID` - Client ID for Authelia\n- `AUTHELIA_CLIENT_SECRET` - Client Secret for Authelia\n\n### Example Docker Run Command\n\n```bash\ndocker run -d \\\n  -p 8080:8080 \\\n  -e TOKENSMITH_ISSUER=\"https://tokensmith.example.com\" \\\n  -e TOKENSMITH_CLUSTER_ID=\"my-cluster\" \\\n  -e TOKENSMITH_OPENCHAMI_ID=\"my-openchami\" \\\n  -e TOKENSMITH_OIDC_PROVIDER=\"hydra\" \\\n  -e HYDRA_CLIENT_ID=\"your-client-id\" \\\n  -e HYDRA_CLIENT_SECRET=\"your-client-secret\" \\\n  -v /path/to/config.json:/tokensmith/config.json \\\n  -v /path/to/keys:/tokensmith/keys \\\n  tokensmith:latest\n```\n\n### Important Notes\n\n1. The `keys` directory is used to store JWT signing keys. Make sure to:\n   - Mount a persistent volume for the keys directory\n   - Set appropriate permissions on the host directory\n   - Back up the keys directory regularly\n\n2. The configuration file should be mounted from the host system and contain your group scope mappings.  Tokensmith can generate a configuration file to start with: `tokensmith generate-config --config=config.json`\n\n3. For security:\n   - Never commit OIDC credentials to version control\n   - Use Docker secrets or a secure secrets management system in production\n\n## Project Structure\n\n```\ntokensmith/\n├── cmd/\n│   └── tokensmith/          # Main application entry point\n├── pkg/\n│   ├── jwt/                 # JWT package (shared)\n│   │   ├── oidc/           # OIDC provider implementations\n│   │   │   ├── authelia/   # Authelia provider\n│   │   │   ├── hydra/      # Hydra provider\n│   │   │   └── keycloak/   # Keycloak provider\n│   │   └── provider.go     # Provider interface\n│   ├── tokenservice/       # Token exchange service\n│   └── middleware/         # JWT middleware (standalone)\n└── example/                # Example applications\n    └── middleware/         # Example of middleware usage\n```\n\n## Local Installation\n\n### Main Service\n\n```bash\ngo get github.com/openchami/tokensmith\n```\n\n### JWT Middleware\n\n```bash\ngo get github.com/openchami/tokensmith/middleware\n```\n\nSee the [middleware documentation](middleware/README.md) for detailed usage instructions.\n\n## Usage\n\n### Token Service\n\nThe token service can be run as a standalone application. First, generate a default configuration file:\n\n```bash\ntokensmith generate-config --config config.json\n```\n\nThen start the service with the configuration file:\n\n```bash\ntokensmith serve \\\n  --provider=keycloak \\\n  --issuer=http://tokensmith:8080 \\\n  --port=8080 \\\n  --cluster-id=test-cluster-id \\\n  --openchami-id=test-openchami-id \\\n  --config=config.json\n```\n\n#### Configuration File\n\nThe configuration file (JSON format) contains settings that don't change frequently:\n\n```json\n{\n  \"groupScopes\": {\n    \"admin\": [\"admin\", \"write\", \"read\"],\n    \"operator\": [\"write\", \"read\"],\n    \"viewer\": [\"read\"],\n    \"user\": [\"read\"]\n  }\n}\n```\n\nConfiguration options:\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `--provider` | OIDC provider type (keycloak, hydra, authelia) | `hydra` |\n| `--issuer` | Token issuer identifier | `http://tokensmith:8080` |\n| `--port` | HTTP server port | `8080` |\n| `--cluster-id` | Unique identifier for this cluster | `cl-F00F00F00` |\n| `--openchami-id` | Unique identifier for this instance of OpenCHAMI | `oc-F00F00F00` |\n| `--hydra-url` | Hydra admin API URL | `http://hydra:4445` |\n| `--authelia-url` | Authelia admin API URL | `http://authelia:9091` |\n| `--keycloak-url` | Keycloak admin API URL | `http://keycloak:8080` |\n| `--keycloak-realm` | Keycloak realm | `openchami` |\n| `--config` | Path to configuration file | `\"\"` |\n\n| Environment Variable | Description |\n|------|-------------|\n| `HYDRA_CLIENT_ID` | Client ID for hydra |\n| `HYDRA_CLIENT_SECRET` | Client Secret for hydra |\n| `KEYCLOAK_CLIENT_ID` | Client ID for Keycloak |\n| `KEYCLOAK_CLIENT_SECRET` | Client Secret for Keycloak |\n| `AUTHELIA_CLIENT_ID` | Client ID for Authelia |\n| `AUTHELIA_CLIENT_SECRET` | Client Secret for Authelia |\n\n### JWT Middleware\n\n```bash\ngo get github.com/openchami/tokensmith/middleware\n```\n\n## Development\n\n### Prerequisites\n\n- Go 1.21 or later\n- Access to an OIDC provider (Keycloak, Hydra, or Authelia)\n\n### Build \u0026 Install\nThis project uses [GoReleaser](https://goreleaser.com/) to automate releases and embed additional build metadata (commit info, build time, versioning, etc.).\n\n#### 1. Environment Variables\nBefore building, make sure to set the following environment variables to include detailed build metadata:\n\n- **GIT_STATE**: Indicates whether there are uncommitted changes. (`clean` if no changes, `dirty` if there are.)\n- **BUILD_HOST**: Hostname of the machine performing the build.\n- **GO_VERSION**: The version of Go used.\n- **BUILD_USER**: The username of the person or system performing the build.\n\nExample:\n```bash\nexport GIT_STATE=$(if git diff-index --quiet HEAD --; then echo 'clean'; else echo 'dirty'; fi)\nexport BUILD_HOST=$(hostname)\nexport GO_VERSION=$(go version | awk '{print $3}')\nexport BUILD_USER=$(whoami)\n```\n\n#### 2. Installing GoReleaser\nFollow the official [GoReleaser installation instructions](https://goreleaser.com/install/) to set up GoReleaser locally.\n\n#### 3. Building Locally with GoReleaser\nUse snapshot mode to build locally without releasing:\n\n```bash\ngoreleaser release --snapshot --clean\n```\n\n- The build artifacts (including embedded metadata) will be placed in the `dist/` directory.\n- Inspect the resulting binaries to ensure the metadata was correctly embedded.\n\n\n### Testing\n\n```bash\n# Run all tests\ngo test ./...\n\n# Run specific package tests\ngo test ./pkg/tokenservice\ngo test ./pkg/middleware\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nSee the [OpenCHAMI Contributors Guide](https://github.com/OpenCHAMI/.github/blob/main/CONTRIBUTING.md) for more information.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Acknowledgments\n\n- OpenCHAMI community\n- OIDC provider maintainers\n- Contributors and maintainers of this project\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenchami%2Ftokensmith","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenchami%2Ftokensmith","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenchami%2Ftokensmith/lists"}