-
Notifications
You must be signed in to change notification settings - Fork 4
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #97 from passageidentity/psg-4893-readme-update
Update Passage-Ruby With New Readme and License
- Loading branch information
Showing
5 changed files
with
63 additions
and
191 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,218 +1,84 @@ | ||
| <img src="https://storage.googleapis.com/passage-docs/passage-logo-gradient.svg" alt="Passage logo" style="width:250px;"/> | ||
|  | ||
|
|
||
| [](https://badge.fury.io/rb/passageidentity) | ||
|  | ||
|  | ||
|  | ||
|
|
||
| # passage-ruby | ||
| ## About | ||
|
|
||
| This Ruby SDK allows for verification of server-side authentication and user management for Ruby applications build with [Passage](https://passage.id). For more information, please visit [Passage Documentation](https://docs.passage.id). | ||
| [Passage by 1Password](https://1password.com/product/passage) unlocks the passwordless future with a simpler, more secure passkey authentication experience. Passage handles the complexities of the [WebAuthn API](https://blog.1password.com/what-is-webauthn/), and allows you to implement passkeys with ease. | ||
|
|
||
| Install this package using [RubyGems](https://rubygems.org/gems/passageidentity). | ||
| Use [Passkey Flex](https://docs.passage.id/flex) to add passkeys to an existing authentication experience. | ||
|
|
||
| ``` | ||
| gem install passageidentity | ||
| ``` | ||
| Use [Passkey Complete](https://docs.passage.id/complete) as a standalone passwordless auth solution. | ||
|
|
||
| ## Instantiating the Passage Class | ||
| Use [Passkey Ready](https://docs.passage.id/passkey-ready) to determine if your users are ready for passkeys. | ||
|
|
||
| Initialize the Passage Client as follows: | ||
|
|
||
| ```ruby | ||
| PassageClient = | ||
| Passage::Client.new( | ||
| app_id: 'YOUR APP ID', | ||
| api_key: 'YOUR APIKEY', | ||
| auth_strategy: Passage::HEADER_AUTH, | ||
| ) | ||
| ``` | ||
| ### In passage-ruby | ||
|
|
||
| Passage has three arguments that can be used for initialization: `app_id`, `api_key`, and `auth_strategy`. | ||
| Use passage-ruby to implement Passkey Complete into your Ruby backend to authenticate requests and manage users. | ||
|
|
||
| - `app_id` is the Passage App ID that specifies which app should be authorized. It has no default value and must to be set upon initialization. | ||
| - `api_key` is an API key for the Passage app, which can be generated in the 'App Settings' section of the [Passage Console](https://console.passage.id). It is an optional parameter and not required for authenticating requests. It is required to get or update user information. | ||
| - `auth_strategy` defines where the Passage SDK should look for the authentication token. It is set by default to `Passage::COOKIE_AUTH`, but can be changed to `Passage::HEADER_AUTH`. | ||
| | Product | Compatible | | ||
| | --- | --- | | ||
| |  Passkey **Flex** | ✖️ For Passkey Flex, check out the [Passkey Flex APIs](https://docs.passage.id/flex/apis) | ||
| |  Passkey **Complete** | ✅ | ||
| |  Passkey **Ready** | ✖️ For Passkey Ready, check out [Authentikit](https://www.npmjs.com/package/@passageidentity/authentikit) | ||
|
|
||
| ## Authenticating a Request | ||
| <br /> | ||
|
|
||
| To authenticate an HTTP request in a Rails application, you can use the Passage library in a middleware function. You need to provide Passage with your App ID in order to verify the JWTs. | ||
| ## Getting Started | ||
|
|
||
| ```ruby | ||
| require 'passageidentity' | ||
|
|
||
| class ApplicationController < ActionController::Base | ||
| PassageClient = Passage::Client.new(app_id: PASSAGE_APP_ID) | ||
| def authorize! | ||
| begin | ||
| user_id = PassageClient.auth.authenticate_request(request) | ||
| # user is authorized | ||
| rescue Exception => e | ||
| # handle exception (user is not authorized) | ||
| end | ||
| end | ||
| end | ||
| ``` | ||
|
|
||
| ## Retrieve App Info | ||
|
|
||
| To retrieve information about an app , you should use the `get_app` method. | ||
|
|
||
| ```ruby | ||
| require 'passageidentity' | ||
|
|
||
| PassageClient = | ||
| Passage::Client.new(app_id: PASSAGE_APP_ID) | ||
| app_info = PassageClient.get_app() | ||
|
|
||
| ``` | ||
|
|
||
| ## Retrieve User Info | ||
|
|
||
| To retrieve information about a user, you should use the `get` method. You will need to use a Passage API key, which can be created in the Passage Console under your Application Settings. This API key grants your web server access to the Passage management APIs to get and update information about users. This API key must be protected and stored in an appropriate secure storage location. It should never be hard-coded in the repository. | ||
|
|
||
| ```ruby | ||
| require 'passageidentity' | ||
|
|
||
| class ApplicationController < ActionController::Base | ||
| PassageClient = | ||
| Passage::Client.new(app_id: PASSAGE_APP_ID, api_key: PASSAGE_API_KEY) | ||
| def authorize! | ||
| begin | ||
| user_id = PassageClient.auth.authenticate_request(request) | ||
| user = PassageClient.user.get(user_id: @user_id) | ||
| # user is authorized | ||
| rescue Exception => e | ||
| # handle exception (user is not authorized) | ||
| end | ||
| end | ||
| end | ||
| ``` | ||
|
|
||
| ## Retrieve User Info By Identifier | ||
|
|
||
| To retrieve information about a user, you can also use the `get_by_identifier` method. You will need to use a Passage API key, which can be created in the Passage Console under your Application Settings. This API key grants your web server access to the Passage management APIs to get and update information about users. This API key must be protected and stored in an appropriate secure storage location. It should never be hard-coded in the repository. | ||
|
|
||
| ```ruby | ||
| require 'passageidentity' | ||
|
|
||
| class ApplicationController < ActionController::Base | ||
| PassageClient = | ||
| Passage::Client.new(app_id: PASSAGE_APP_ID, api_key: PASSAGE_API_KEY) | ||
| def authorize! | ||
| begin | ||
| user_id = PassageClient.auth.authenticate_request(request) | ||
| user = PassageClient.user.get_by_identifier(identifier: @identifier) | ||
| # user is authorized | ||
| rescue Exception => e | ||
| # handle exception (user is not authorized) | ||
| end | ||
| end | ||
| end | ||
| ``` | ||
| ### Check Prerequisites | ||
|
|
||
| ## Activate/Deactivate User | ||
| <p> | ||
| You'll need a free Passage account and a Passkey Complete app set up in <a href="https://console.passage.id/">Passage Console</a> to get started. <br /> | ||
| <sub><a href="https://docs.passage.id/home#passage-console">Learn more about Passage Console →</a></sub> | ||
| </p> | ||
|
|
||
| You can activate or deactivate a user using the Passage SDK. These actions require an API Key and deactivating a user will prevent them from logging into your application | ||
| with Passage. | ||
| ### Install | ||
|
|
||
| ```ruby | ||
| require 'passageidentity' | ||
|
|
||
| PassageClient = | ||
| Passage::Client.new(app_id: PASSAGE_APP_ID, api_key: PASSAGE_API_KEY) | ||
|
|
||
| user = PassageClient.user.deactivate(user_id: user_id) | ||
| user = PassageClient.user.activate(user_id: user_id) | ||
| ``` | ||
|
|
||
| ## Create User | ||
|
|
||
| You can create users using their email address or phone number. Note that their phone number must be in E164 format (example shown below). | ||
|
|
||
| ```ruby | ||
| require 'passageidentity' | ||
|
|
||
| PassageClient = | ||
| Passage::Client.new(app_id: PASSAGE_APP_ID, api_key: PASSAGE_API_KEY) | ||
|
|
||
| user = PassageClient.user.create(email: '[email protected]') | ||
| user = PassageClient.user.create(phone: '+15005550007') | ||
| ```shell | ||
| gem install passageidentity | ||
| ``` | ||
|
|
||
| ## Delete User | ||
|
|
||
| You can delete a user using the Passage SDK. | ||
| ### Import | ||
|
|
||
| ```ruby | ||
| require 'passageidentity' | ||
|
|
||
| PassageClient = | ||
| Passage::Client.new(app_id: PASSAGE_APP_ID, api_key: PASSAGE_API_KEY) | ||
|
|
||
| success = PassageClient.user.delete(user_id: user_id) | ||
| puts 'passage user was successfully deleted' if success | ||
| ``` | ||
|
|
||
| ## List User Devices | ||
|
|
||
| You can list the devices associated with a particular Passage User. | ||
| ### Initialize | ||
|
|
||
| ```ruby | ||
| require 'passageidentity' | ||
|
|
||
| PassageClient = | ||
| Passage::Client.new(app_id: PASSAGE_APP_ID, api_key: PASSAGE_API_KEY) | ||
|
|
||
| devices = PassageClient.user.list_devices(user_id: user_id) | ||
| Passage::Client.new( | ||
| app_id: 'YOUR_PASSAGE_APP_ID', | ||
| api_key: 'YOUR_PASSAGE_API_KEY', | ||
| auth_strategy: Passage::HEADER_AUTH, | ||
| ) | ||
| ``` | ||
|
|
||
| ## List User Devices | ||
|
|
||
| You can list the devices associated with a particular Passage User. | ||
| ### Go Passwordless | ||
|
|
||
| ```ruby | ||
| require 'passageidentity' | ||
| Find all core functions, user management details, and more implementation guidance on our [Passkey Complete Ruby Documentation](https://docs.passage.id/complete/backend-sdks/ruby) page. | ||
|
|
||
| PassageClient = Passage::Client.new(app_id: PASSAGE_APP_ID, api_key: PASSAGE_API_KEY) | ||
| ## Support & Feedback | ||
|
|
||
| success = PassageClient.user.delete_device(user_id: user_id, device_id) | ||
| if success | ||
| puts "passage user device was successfully deleted" | ||
| end | ||
| ``` | ||
| We are here to help! Find additional docs, the best ways to get in touch with our team, and more within our [support resources](https://github.com/passageidentity/.github/blob/main/SUPPORT.md). | ||
|
|
||
| ## Create an Embeddable Magic Link | ||
| <br /> | ||
|
|
||
| To create a magic link, you should use the `create_magic_link` method. You can check out our guide on embeddable magic links in our [docs](https://docs.passage.id/complete/magic-links). | ||
| --- | ||
|
|
||
| ```ruby | ||
| require 'passageidentity' | ||
|
|
||
| PassageClient = | ||
| Passage::Client.new(app_id: PASSAGE_APP_ID, api_key: PASSAGE_API_KEY) | ||
|
|
||
| magic_link = PassageClient.create_magic_link(user_id: user_id) | ||
| magic_link = | ||
| PassageClient.create_magic_link( | ||
| email: '[email protected]', | ||
| send: true, | ||
| channel: Passage::EMAIL_CHANNEL, | ||
| ttl: 120, | ||
| ) | ||
| ``` | ||
| <p align="center"> | ||
| <picture> | ||
| <source media="(prefers-color-scheme: dark)" srcset="https://storage.googleapis.com/passage-docs/github-md-assets/passage-by-1password-dark.png"> | ||
| <source media="(prefers-color-scheme: light)" srcset="https://storage.googleapis.com/passage-docs/github-md-assets/passage-by-1password-light.png"> | ||
| <img alt="Passage by 1Password Logo" src="https://storage.googleapis.com/passage-docs/github-md-assets/passage-by-1password-light.png"> | ||
| </picture> | ||
| </p> | ||
|
|
||
| ## Available Functions | ||
|
|
||
| | Class | Method | Description | | ||
| | ----------- | ---------------------------------------------------------------------------- | ---------------------------- | | ||
| | _ClientApi_ | [**get_app**](docs/custom/ClientApi.md#get_app) | Get App | | ||
| | _ClientApi_ | [**create_magic_link**](docs/custom/Passage/ClientApi.md#create_magic_link) | Create Embeddable Magic Link | | ||
| | _AuthApi_ | [**auth.authenticate_request**](docs/custom/AuthApi.md#authenticate_request) | Validates user jwt token | | ||
| | _AuthApi_ | [**auth.validate_jwt**](docs/custom/AuthApi.md#validate_jwt) | Validates user jwt token | | ||
| | _UserAPI_ | [**user.delete_device**](docs/custom/UserApi.md#delete_device) | Delete a device for a user | | ||
| | _UserAPI_ | [**user.list_devices**](docs/custom/UserApi.md#list_devices) | List User Devices | | ||
| | _UserAPI_ | [**user.activate**](docs/custom/UserApi.md#activate) | Activate User | | ||
| | _UserAPI_ | [**user.create**](docs/custom/UserApi.md#create) | Create User | | ||
| | _UserAPI_ | [**user.deactivate**](docs/custom/UserApi.md#deactivate) | Deactivate User | | ||
| | _UserAPI_ | [**user.delete**](docs/custom/UserApi.md#delete) | Delete User | | ||
| | _UserAPI_ | [**user.get**](docs/custom/UserApi.md#get) | Get User | | ||
| | _UserAPI_ | [**user.update**](docs/custom/UserApi.md#update) | Update User | | ||
| | _UserAPI_ | [**user.signout**](docs/custom/UserApi.md#signout) | Signout User | | ||
| <p align="center"> | ||
| <sub>Passage is a product by <a href="https://1password.com/product/passage">1Password</a>, the global leader in access management solutions with nearly 150k business customers.</sub><br /> | ||
| <sub>This project is licensed under the MIT license. See the <a href="LICENSE">LICENSE</a> file for more info.</sub> | ||
| </p> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,5 @@ | ||
| # frozen_string_literal: true | ||
|
|
||
| module Passage | ||
| VERSION = '0.6.1' | ||
| VERSION = '0.6.2' | ||
| end |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -3,13 +3,13 @@ require_relative 'lib/passageidentity/version' | |
| Gem::Specification.new do |s| | ||
| s.name = 'passageidentity' | ||
| s.version = Passage::VERSION | ||
| s.summary = 'Passage SDK for biometric authentication' | ||
| s.summary = 'Passage Passkey Complete SDK' | ||
| s.description = | ||
| 'Enables verification of server-side authentication and user management for applications using Passage' | ||
| s.authors = ['Passage Identity'] | ||
| 'Passkey Complete for Ruby - Integrate into your Ruby API or service to enable a completely passwordless standalone auth solution with Passage by 1Password.' | ||
| s.authors = ['Passage by 1Password'] | ||
| s.email = '[email protected]' | ||
| s.files = ['lib/passageidentity.rb'] | ||
| s.homepage = 'https://rubygems.org/gems/passageidentity' | ||
| s.homepage = 'http://docs.passage.id/complete' | ||
| s.license = 'MIT' | ||
|
|
||
| s.metadata['source_code_uri'] = | ||
|
|
||