Oxd Ruby

Ruby Client Library for the Gluu oxD Server RP - v2.4.4 to v3.0.1.

oxdruby is a thin wrapper around the communication protocol of oxD server. This can be used to access the OpenID connect & UMA Authorization end points of the Gluu Server via the oxD RP. This library provides the function calls required by a website to access user information from a OpenID Connect Provider (OP) by using the OxD as the Relying Party (RP).

Using the Library in your website

You are now on the master branch. If you want to use oxd-ruby for production use, switch to the branch of the matching version as the oxd-server you are installing.

oxD RP has complete information about the Code Authorization flow and the various details about oxD RP configuration. This document provides only documentation about the oxd-ruby library.

Prerequisites

Install gluu-oxd-server

Oxd-server needs to be running on your machine to connect with OP.

Enable SSL on your website otherwise this library will not work.

Installation

To install gem, add this line to your application's Gemfile:

gem 'oxd-ruby', '~> 0.1.8'

Run bundle command to install it:

$ bundle install

Configuring

After you installed oxd-ruby, you need to run the generator command to generate the configuration file:

$ rails generate oxd:config

The generator will install oxd_config.rb initializer file in config/initializers directory which conatins all the global configuration options for oxd-ruby plguin. The following configurations must be set in config file before the plugin can be used.

config.oxd_host_ip
config.oxd_host_port
config.op_host
config.authorization_redirect_uri

Usage

Add following snippet to your application_controller.rb file:

require 'oxd-ruby'

before_filter :set_oxd_commands_instance
protected
    def set_oxd_commands_instance
        @oxd_command = Oxd::ClientOxdCommands.new
        @uma_command = Oxd::UMACommands.new
    end

The ClientOxdCommands class of the library provides all the methods required for the website to communicate with the oxD RP through sockets. The UMACommands class provides commands for UMA Resource Server(UMA RS) and UMA Requesting Party(UMA RP) protocol.

Website Registration

The website can be registered with the OpenId Provider using the @oxd_command.register_site call.

Get Authorization URL

The first step is to generate an authorization url which the user can visit to authorize your application to use the information from the OpenId Provider.

authorization_url = @oxd_command.get_authorization_url

Using the above url the website can redirect the user for authentication at the OpenId Provider.

Get access token

The website needs to parse the information from the callback url and pass it on to get the access token for fetching user information.

code = params[:code]
state = params[:state]
access_token = @oxd_command.get_tokens_by_code( code,state )

The values for code are parsed from the callback url query parameters.

Get user claims

Claims (user information fields) made availble by the OpenId Provider can be fetched using the access token obtained above.

user = @oxd_command.get_user_info(access_token)

Using the claims

Once the user data is obtained, the various claims supported by the OpenId Provider can be used as required.

<% user.each do |field,value| %>
    <%= "#{field} : #{value}" %>
<% end %>

The availability of various claims are completely dependent on the OpenId Provider.

Logging out

Once the required work is done the user can be logged out of the system.

logout_uri = @oxd_command.get_logout_uri(state, session_state)

You can then redirect the user to obtained url to perform logout.

Using UMA commands

UMA Protect resources

To protect resources with UMA Resource server, you need to add resources to library using uma_add_resource(path, *conditions) method. Then you can call following method to register resources for protection with UMA RS.

@uma_command.uma_add_resource(path, *conditions)
@uma_command.uma_rs_protect

UMA Check access for a particular resource

To check wether you have access to a particular resource on UMA Resource Sevrer or not, use following method:

@uma_command.uma_rs_check_access(path, http_method)

You must first get RPT before calling this method.

Get Requesting Party Token(RPT)

To gain access to protected resources at the UMA resource server, you must first obtain RPT.

@uma_command.uma_rp_get_rpt(force_new)

Authorize RPT

You must first call uma_rp_get_rpt and uma_rs_check_access methods before authorizing RPT. If you have already obtained the RPT, use uma_rp_authorize_rpt method provided by oxd-ruby library to authorize it.

@uma_command.uma_rp_authorize_rpt

Get Gluu Access Token(GAT)

To obtain GAT(Gluu Access Token) call following method with scopes as parameter.

@uma_command.uma_rp_get_gat(scopes)

Logs

You can find oxd-ruby.log file in rails_app_root/log folder. It contains all the logs about oxd-server connections, commands/data sent to server, recieved response and all the errors and exceptions raised.

Demo Site

The demosite folder contains a demo Ruby on Rails application which uses the oxd-ruby library to demonstrate the usage of the library. The deployment instrctions for the demo site can be found inside the demosite's README file.