Download the PHP package tigusigalpa/yandex-lockbox-php without Composer

Yandex Lockbox PHP SDK

🇷🇺 Русская версия документации

PHP/Laravel client library for Yandex Lockbox — a secure secrets storage service in Yandex Cloud.

Note: This package uses yandex-cloud-client-php for Yandex Cloud infrastructure management (authentication, organizations, clouds, folders).

📚 Documentation

• Yandex Lockbox Docs
• Quickstart Guide
• API Reference
• OAuth Token Guide
• API Endpoint: https://lockbox.api.cloud.yandex.net/lockbox/v1

✨ Features

• ✅ Full Yandex Lockbox API support
• ✅ Automatic IAM token generation from OAuth token
• ✅ Cloud infrastructure management via yandex-cloud-client-php
• ✅ Async operation handling (wait for operations to complete)
• ✅ Folder permissions management (list/assign access bindings)
• ✅ PHP 8.0+ with strict types
• ✅ Laravel 8-12 integration (service provider, facade, config)
• ✅ Extensible token provider interface
• ✅ Typed exceptions for better error handling
• ✅ PSR-3 logger support
• ✅ Comprehensive test coverage

📦 Installation

Development (path repository)

For mono-repo development, add to your root composer.json:

Then run:

⚙️ Configuration (Laravel)

Publish the configuration file:

Add environment variables to your .env:

🔐 Authorization & API Connection Guide

Step 1: Getting OAuth Token

Documentation: OAuth Token Guide

Get token via OAuth request:

1. Open the URL above in your browser
2. Authorize the application
3. Copy the OAuth token from the response URL (format: y0_..., y1_..., y2_..., y3_...)
4. Add token to .env (Laravel):

Or pass directly to OAuthTokenProvider:

Step 2: Getting IAM Token (Optional)

Documentation: How to get IAM token

IAM token is generated automatically from OAuth token. But you can get it manually:

Alternative - using Yandex CLI:

⚠️ Note: IAM tokens expire after 12 hours

Step 3: Getting Cloud ID

Documentation: Retrieves the list of Cloud resources

List all clouds:

Or get first cloud directly:

Step 4: Getting Folder ID

Documentation: Retrieves the list of Folder resources in the specified cloud

List all folders in cloud:

Or get first folder directly:

Step 5: Add permissions to a folder

Documentation: Access management in Yandex Lockbox

You need to get Subject ID (user account ID that you want to assign permissions to) first

Documentation: Subjects that roles are assigned to

Documentation: Retrieves the list of Yandex Passport user accounts

Documentation: lockbox.editor

Documentation: Setting up folder access permissions

Step 6: Working with Yandex Lockbox API

Documentation: Lockbox API, REST: Secret

Now you can use the folder ID to work with secrets:

Handling Asynchronous Operations

Some Yandex Cloud operations (like assignRoleToFolder) are asynchronous and return an operation object with done=false. You have two options:

Option 1: Wait for completion automatically

Option 2: Poll operation status manually

Managing Folder Permissions

List and manage access bindings (permissions) for folders:

Response structure:

Laravel Facade

Laravel Artisan Commands

🔒 Exception Handling

The library provides specific exceptions for different error types:

🧪 Testing

Artisan Commands

lockbox:test - Comprehensive Testing

Runs complete test suite with 8 tests:

Output:

lockbox:list - List Secrets

lockbox:show - Show Secret Details

lockbox:create - Create Secret

lockbox:add-version - Add Version

JSON file format:

lockbox:delete - Delete Secret

Common Testing Scenarios

Scenario 1: First Run

Scenario 2: Create New Secret

Scenario 3: Update Secret

PHPUnit Tests

📚 API Reference

OAuthTokenManager Methods

Authentication & Token Management

• getIamToken(): string - Get IAM token (cached automatically)
• listClouds(): array - List all clouds
• getFirstCloud(): array - Get first cloud
• getFirstCloudId(): string - Get first cloud ID

Folder Management

• listFolders(string $cloudId): array - List folders in cloud
• getFolder(string $folderId): array - Get folder details
• getFirstFolder(string $cloudId): array - Get first folder
• getFirstFolderId(string $cloudId): string - Get first folder ID
• getFirstFolderIdFromFirstCloud(): string - Get first folder ID from first cloud
• createFolder(string $iamToken, string $cloudId, string $name, ?string $description = null): array - Create folder

Access Control (Permissions)

- assignRoleToFolder(string $iamToken, string $folderId, string $subjectId, string $role = 'lockbox.editor', string $subjectType = 'userAccount', bool $waitForCompletion = false, int $maxWaitSeconds = 60): array - Assign role to folder

listFolderAccessBindings(string $iamToken, string $folderId, int $pageSize = 100, ?string $pageToken = null): array - List folder access bindings (paginated)

• getAllFolderAccessBindings(string $iamToken, string $folderId): array - Get all folder access bindings ( auto-pagination)

User Management

• getUserByLogin(string $login): array - Get full user info by Yandex login
• getUserIdByLogin(string $login): string - Get user ID (Subject ID) by Yandex login

Async Operations

- waitForOperation(string $iamToken, string $operationId, int $maxWaitSeconds = 60, int $pollIntervalSeconds = 2): array - Wait for operation to complete

• getOperation(string $iamToken, string $operationId): array - Get operation status

Client Methods

Secret Management

• listSecrets(string $folderId): array - List secrets in folder
• getSecret(string $secretId): array - Get secret metadata
• createSecret(array $data): array - Create new secret
• updateSecret(string $secretId, array $data): array - Update secret
• deleteSecret(string $secretId): void - Delete secret

Version Management

• addVersion(string $secretId, array $data): array - Add new version to secret
• getPayload(string $secretId, ?string $versionId = null): array - Get secret payload

📝 Requirements

• PHP 8.0 or higher
• Laravel 8.x - 12.x (optional, for Laravel integration)
• Guzzle HTTP client 7.x or 8.x

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This package is open-sourced software licensed under the MIT license.

👤 Author

Igor Sazonov

• GitHub: @tigusigalpa
• Email: [email protected]

🔗 Links

• Packagist
• GitHub Repository
• Issue Tracker
• Yandex Cloud Documentation