Download the PHP package eludadev/passage without Composer

About The Project

Introducing Passage SDK for PHP:

• Seamless integration with 1Password's Passage API
• Secure storage and retrieval of secrets
• Magic link authentication implementation
• Robust error handling
• Automatic conversion to native PHP DateTime objects
• Middleware support for easy integration
• Powerful SDK features for enhanced security in PHP projects

(back to top)

Getting Started

Prerequisites

Start by creating a laravel/laravel project using PHP composer:

• composer

Installation

1. Create a Passage account
2. Create a new Passage application
3. Retrieve your application's <APP_ID> and <API_KEY>

4. Add <APP_ID> and <API_KEY> to your local .env file:

5. Install package from Packagist

6. Import the Passage class

7. Create an instance of the Passage class. \ Set <AUTH_STRATEGY> to either 'COOKIES' (default) or 'HEADER'.

(back to top)

Usage

Authenticate requests and manage Passage users with Node.js.

Warning To use the Passage PHP SDK, you'll need your Passage App ID. You can create a new Passage App in the console.

Note Assuming you followed the above prerequisites to create a new laravel/laravel project, you can quickly get started using this SDK in your API routes by opening the routes/web.php file and adding the following code:

Authenticating Requests

Passage makes it easy to associate an HTTP request with an authenticated user. The following code can be used to validate that a request was made by an authenticated user.

By default, Passage looks for the user JWT from a cookie that is set by the Passage Element (psg_auth_token). If your application uses Authorization headers instead, you can pass the following option to the Passage PHP SDK.

Authenticating a Request With PHP Middleware

If you used the laravel/laravel project, Passage provides a middleware that can be used directly. This middleware will authenticate a request and return a 401 Unauthorized if the token is invalid. If it succeeds, the Passage User ID will be available in the response. The following code shows how the Passage middleware can be used in a PHP application.

If you are not using eludadev/passage in a request context, or your application is passing the JWT in a custom way, you can pass the JWT directly to the validAuthToken method to perform validation.

App Information

The Passage SDK provides a way to retrieve information about an app.

User Management

In addition to authenticating requests, the Passage PHP SDK also provides a way to securely manage your users. These functions require authentication using a Passage API key. API keys can be managed in the Passage Console.

The functionality currently available on a user is:

• Get a user's information (including any defined user metadata)
• Activate or deactivate a user (a deactivated user will not be able to log in)
• Update a user's information (email address or phone number)
• Delete a user
• Create a user

Warning Passage API Keys are sensitive! You should store them securely along with your other application secrets.

User Device Management

The functionality currently available is:

• List all devices for a user
• Revoke a particular device from a user

Creating Magic Links

The PHP SDK can be used to generate custom magic links (called "smart links") for users, that can be embedded into any content medium. To learn more, see our full guide on Smart Links.

(back to top)

Example Usage

We built an example full-stack application on React and a PHP backend. Get started by opening the following directory: cd ./examples

Warning Make sure you have PHP and Composer installed on your local machine before continuing with these steps.

Configuring a new Passage Project

Create a new Passage project. Make sure to input http://localhost:3000 for the domain, and /dashboard for the redirect URL.

Updating an existing Passage project

Head over to your project settings.

Input http://localhost:3000 for the domain, and /dashboard for the redirect URL, and / for the login URL.

Running the server

1. Go to the backend directory: cd ./backend
2. Install the dependencies: composer install
3. Copy the environment variables file: cp .env.example .env

4. Replace your Passage credentials in .env:

5. Run the server: php artisan serve

Running the frontend

1. Go to the frontend directory: cd ./frontend
2. Install the dependencies: yarn
3. Copy the environment variables file: cp EXAMPLE.env .env

4. Replace your Passage credentials in .env:

5. Run the server: yarn start

How it works

Here's the code powering the PHP backend:

For this particular example, we chose to build the server on the Laravel framework, but the Passage PHP SDK can work on any PHP framework.

The frontend calls the localhost:8000/api/auth URL, which extracts the authentication header, decodes the JWK token, and retrieves the user ID. It then makes calls to the Passage API to retrieve more user information such as email and phone number.

All of this is done behind the scenes by the PHP SDK, so you don't have to worry about the intricate details.

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Younes Laaroussi - Telegram - [email protected]

Project Link: https://github.com/eludadev/Passage

(back to top)

Acknowledgments

Many thanks to 1Password and Hashnode for hosting this amazing hackathon! It was a lot of fun and a fantastic learning experience for me and all the other participants, and hopefully it can happen again! ❤️

(back to top)