passageidentity

Enables verification of server-side authentication and user management for applications using Passage


License
MIT
Install
gem install passageidentity -v 0.0.0

Documentation

Passage logo

Gem Version

passage-ruby

This Ruby SDK allows for verification of server-side authentication and user management for Ruby applications build with Passage.

Install this package using RubyGems.

gem install passageidentity

Instantiating the Passage Class

Initialize the Passage Client as follows:

PassageClient =
  Passage::Client.new(
    app_id: 'YOUR APP ID',
    api_key: 'YOUR APIKEY',
    auth_strategy: Passage::HEADER_AUTH,
  )

Passage has three arguments that can be used for initialization: app_id, api_key, and auth_strategy.

  • 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. 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.

Authenticating a Request

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.

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.

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.

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.

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

Activate/Deactivate User

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.

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).

require 'passageidentity'

PassageClient =
  Passage::Client.new(app_id: PASSAGE_APP_ID, api_key: PASSAGE_API_KEY)

user = PassageClient.user.create(email: 'exampleEmail@domain.com')
user = PassageClient.user.create(phone: '+15005550007')

Delete User

You can delete a user using the Passage SDK.

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.

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)

List User Devices

You can list the devices associated with a particular Passage User.

require 'passageidentity'

PassageClient = Passage::Client.new(app_id: PASSAGE_APP_ID, api_key: PASSAGE_API_KEY)

success = PassageClient.user.delete_device(user_id: user_id, device_id)
if success
    puts "passage user device was successfully deleted"
end

Create an Embeddable Magic Link

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.

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: 'example@domain.com',
    send: true,
    channel: Passage::EMAIL_CHANNEL,
    ttl: 120,
  )

Available Functions

Class Method Description
ClientApi get_app Get App
ClientApi create_magic_link Create Embeddable Magic Link
AuthApi auth.authenticate_request Validates user jwt token
AuthApi auth.validate_jwt Validates user jwt token
UserAPI user.delete_device Delete a device for a user
UserAPI user.list_devices List User Devices
UserAPI user.activate Activate User
UserAPI user.create Create User
UserAPI user.deactivate Deactivate User
UserAPI user.delete Delete User
UserAPI user.get Get User
UserAPI user.update Update User
UserAPI user.signout Signout User