usos_auth_lib 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 135ee424533e6fee6163985ab9116940d3809e107ede2ebde5deb42afcf40489
+  data.tar.gz: c1a3fc3af4ac488228bb79b8f48919cbd79eccb8ba8a81ab8773285b458134c5
+SHA512:
+  metadata.gz: a1d8a55ce5caa3b6a1482d3df93bb9fc03e75289b5b89dd2a51ee83c05a87075fa30c9b0703af57dcd126a198db79ebac69511d7ce90441b2fcf50fde52066d3
+  data.tar.gz: 193c8ea2b7907f5e361ce266c50acd78e88d27270ea345313dd247f86af95defd11ad17f62537198c96040e1181df3add71698d1bf15ffd64b128b90871ecb5e

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright mikolajczu
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,145 @@
+# UsosAuthLib
+Introducing "UsosAuthLib" a powerful Ruby on Rails library designed to streamline user authentication and seamlessly handle requests through the USOS API. This library simplifies the integration process, allowing developers to effortlessly authenticate users using USOS credentials within their Rails applications. With a focus on security and efficiency, Rails USOS Auth ensures a smooth user experience while providing robust support for USOS API interactions. Elevate your application's functionality by effortlessly incorporating user authentication and USOS API communication with the convenience of Rails USOS Auth.
+
+## USOS API
+The USOS API, a cornerstone of academic data access, opens up a world of possibilities for developers seeking to integrate educational information into their applications. Following the OAuth 1.0a workflow as outlined in the official documentation from 'https://apps.usos.edu.pl/developers/api/authorization/', developers can securely implement user authentication and gain authorized access to the wealth of data stored in the USOS system.
+
+The OAuth 1.0a workflow ensures a robust and secure authentication process, safeguarding user credentials while granting seamless access to the USOS API. By adhering to the guidelines provided in the official source, developers can confidently build applications that tap into the extensive educational resources offered by USOS, enriching their projects with academic data in a reliable and user-friendly manner. Explore the possibilities of educational integration through the USOS API and OAuth 1.0a, empowering your applications with a wealth of valuable information.
+
+## Usage
+Here's an example for adding the configuration to a Rails app in `config/initializers/usos_auth_lib.rb`:
+```ruby
+UsosAuthLib.configure do |config|
+  config.api_key = "ENV.fetch('API_KEY', nil)"
+  config.api_secret = "ENV.fetch('API_SECRET', nil)"
+  config.usos_base_url = 'https://usosapps.umk.pl/'
+  config.scopes = 'email|grades'
+  config.redirect_path = '/usos_auth'
+end
+```
+
+`config.api_key` -> Consumer api key generated by USOS. <br>
+`config.api_key` -> Consumer secret key generated by USOS. <br>
+`config.usos_base_url` -> Your consumer secret key generated by USOS. <br>
+`config.api_key` -> Your consumer secret key generated by USOS. <br>
+`config.api_key` -> Your consumer secret key generated by USOS. <br>
+
+The next step is to mount our routes for `authorize_user` and `callback` to a Rails app in `config/routes.rb`:
+```ruby
+mount UsosAuthLib::Engine => '/usos_auth_lib'
+get '/authorize_user', to: 'usos_auth_lib/usos#authorize_user'
+get '/callback', to: 'usos_auth_lib/usos#callback'
+```
+
+`get '/authorize_user'` -> replace it with your route or leave it, this is the route used to authorize the user via the USOS API <br>
+`get '/callback'` -> replace it with your route or leave it, this is the route used to return from USOS, <span style="color: red;">THIS IS NOT THE ROUTE RETURN FROM THE LIBRARY!</span>, this route is the one we added to the configuration
+
+Here's an example for creating a user or obtain it from our database in `models/users.rb`:
+
+```ruby
+class User < ApplicationRecord
+  def self.from_usos(token)
+    user = User.where(email: token[:email]).first
+    user = User.create(
+      email: token[:email],
+      first_name: token[:first_name],
+      last_name: token[:last_name],
+      usos_id: token[:id],
+      img_url: token[:photo_url] || nil
+    ) unless user
+
+    user
+  end
+end
+```
+
+Here's an example for callback method in `controllers/users_controller.rb`:
+```ruby
+class UsersController < ApplicationController
+  def usos_auth
+    session[:access_token] = params[:token]
+    session[:access_token_secret] = params[:secret]
+    @user = User.from_usos(params)
+  end
+end
+```
+
+Here's an example for use of handle_request method in `controllers/users_controller.rb`:
+```ruby
+class UsersController < ApplicationController
+  include UsosAuthCommon
+  def usos_auth
+    session[:access_token] = params[:token]
+    session[:access_token_secret] = params[:secret]
+    @user = User.from_usos(params)
+  end
+
+  def grades
+    response = handle_request(session[:access_token], session[:access_token_secret], '/services/grades/terms2?term_ids=2023/24Z')
+
+    render json: response
+  end
+end
+```
+In this example, we want to retrieve all grades from the 2023/2024Z semester.
+
+## Scopes
+When you request a Request Token, you may pass the scopes parameter, which describes the things you want the User to share with you. Many API methods require you to have the access to multiple scopes.
+
+When you ask a User to authorize your Request Token, USOS API will notify the User which scopes your application requires. Choose wisely - users may discard your request if you want too much!
+
+Currently available scope keys:
+
+- What you get by default: Permission to read basic user information (such as user's name and ID). You don't need to request this permission explicitly - you receive it by default with each Access Token.
+- cards: Provides access to user's ID cards data, such as chip uid or expiration date
+- change_all_preferences: Allows you to change user preferences (via the uprefs module). You may need some other scopes in order to change or view some of the preferences. Also, the access to some important preferences may be restricted in other ways, i.e. only Administrative Consumers may be allowed to change them.
+- crstests: Provides access to details and results of user's course tests.
+- dorm_admin: Provides access to administrative housing operations on user's behalf. For more information, please visit the housing module.
+- edit_user_attrs: Allows editing user's attributes (the same thet the user can edit on his USOSweb profile page).
+- email: Provides access to user's email address.
+- events: Allows access to user's preferences, push notifications, etc.
+- grades: Provides access to grades information.
+- grades_write: Allows access to read and write exam reports.
+- mailclient: Provides access to the mailclient module (in the name of your user). Currently only a small set of methods is available for non-administrative consumers, but this set will be growing.
+- mobile_numbers: Provides access to user's personal mobile phone number(s).
+- offline_access: Enables your application to perform authorized requests on behalf of the user at any time. By default, Access Tokens expire after a short time period to ensure applications only make requests on behalf of users when they are actively using the application. This scope makes Access Tokens long-lived.
+- other_emails: Provides access to email addresses of other users (i.e. the ones related to your user).
+- payments: Allows access to your payments.
+- personal: Provides access to user's personal data, such as PESEL number, date of birth, etc.
+- photo: Provides read access to user's photo and his/her photo visibility preferences ("who can see my photo?").
+- placement_tests: Provides access to results of user's placement tests in foreign languages.
+- session_debugging_perms: (for Administrative Consumers only) Allows access to official permissions related to the user's session debugging rights. Allows you to get the answer to the question "Is my user permitted to debug the session of user X?". See "can_i_debug" field of the services/users/user method for more information.
+- slips: Provides access to most of the actions within the Clearance Slips module. With this scope you can view, create and edit slips, answer questions and perform any non-administrative action which the user can perform via USOSweb. You will need an additional 'slips_admin' scope if you want to manage slip templates too.
+- slips_admin: Provides access to template management of the "slips" module. That is, it allows you to create and edit questions, mark templates as obsolete etc.
+- staff_perspective: If your user is a staff member, then this scope provides access to some common student-related data usually visible only to staff members, e.g. student numbers, or broader lists of students' study programmes.
+- student_exams: Provides access to lists of student's exams, information on their examiners, places the exams take place etc.
+student_exams_write: Allows to register and unregister the student from his exams.
+- studies: Provides access to lists of programmes, courses, classes and groups which the user attends (as a student).
+- surveys_filling: Allows access to surveys from students point of view. With this scope you can fetch and fill out surveys.
+- surveys_reports: Allows access to reports on surveys that concern user as a lecturer.
+- theses_protocols_write: Allows access to editing diploma exam protocols, e.g. signing protocols.
+
+Source: `https://apps.usos.edu.pl/developers/api/authorization/`
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "usos_auth_lib"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install usos_auth_lib
+```
+
+## Contributing
+Contribution directions go here.
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+require 'bundler/setup'
+
+APP_RAKEFILE = File.expand_path('spec/dummy/Rakefile', __dir__)
+load 'rails/tasks/engine.rake'
+
+load 'rails/tasks/statistics.rake'
+
+require 'bundler/gem_tasks'

data/app/assets/config/usos_auth_lib_manifest.js

@@ -0,0 +1 @@
+//= link_directory ../stylesheets/usos_auth_lib .css

data/app/assets/stylesheets/usos_auth_lib/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/controllers/usos_auth_lib/usos_controller.rb

@@ -0,0 +1,36 @@
+module UsosAuthLib
+  class UsosController < ActionController::Base
+    def authorize_user
+      authorization_url = usos_authorizer.authorize(session, request)
+
+      redirect_to authorization_url, allow_other_host: true
+    end
+
+    def callback
+      verifier = params[:oauth_verifier]
+      access_token = usos_authorizer.access_token(session, verifier, nil, nil)
+
+      response = access_token.get('/services/users/user?fields=id|first_name|last_name|email|photo_urls')
+      parsed_response = JSON.parse(response.body)
+
+      puts parsed_response
+
+      redirect_path = UsosAuthLib.configuration.redirect_path
+
+      url = url_for(redirect_path)
+
+      url << "?id=#{parsed_response['id']}&email=#{parsed_response['email']}"
+      url << "&first_name=#{parsed_response['first_name']}&last_name=#{parsed_response['last_name']}"
+      url << "&photo_url=#{parsed_response['photo_urls']['50x50']}"
+      url << "&token=#{access_token.token}&secret=#{access_token.secret}"
+
+      redirect_to url, allow_other_host: true
+    end
+
+    private
+
+    def usos_authorizer
+      UsosAuthLib::UsosAuthorizer.new
+    end
+  end
+end

data/app/helpers/usos_auth_lib/application_helper.rb

@@ -0,0 +1,4 @@
+module UsosAuthLib
+  module ApplicationHelper
+  end
+end

data/app/jobs/usos_auth_lib/application_job.rb

@@ -0,0 +1,4 @@
+module UsosAuthLib
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/mailers/usos_auth_lib/application_mailer.rb

@@ -0,0 +1,6 @@
+module UsosAuthLib
+  class ApplicationMailer < ActionMailer::Base
+    default from: 'from@example.com'
+    layout 'mailer'
+  end
+end

data/app/models/concerns/usos_auth_common.rb

@@ -0,0 +1,18 @@
+module UsosAuthCommon
+  extend ActiveSupport::Concern
+
+  def handle_request(access_token, access_token_secret, service_path)
+    access_token = usos_authorizer.access_token(session, nil, access_token, access_token_secret)
+
+    puts access_token
+
+    response = access_token.get(service_path)
+    JSON.parse(response.body)
+  end
+
+  private
+
+  def usos_authorizer
+    UsosAuthLib::UsosAuthorizer.new
+  end
+end

data/app/models/usos_auth_lib/application_record.rb

@@ -0,0 +1,5 @@
+module UsosAuthLib
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/views/layouts/usos_auth_lib/application.html.erb

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Usos auth lib</title>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+
+  <%= stylesheet_link_tag    "usos_auth_lib/application", media: "all" %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,5 @@
+UsosAuthLib::Engine.routes.draw do
+  post '/authorize_user', to: 'usos#authorize_user'
+  post '/callback', to: 'usos#callback'
+  post '/handle_request', to: 'usos#handle_request'
+end

data/lib/tasks/usos_auth_lib_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :usos_auth_lib do
+#   # Task goes here
+# end

data/lib/usos_auth_lib/engine.rb

@@ -0,0 +1,5 @@
+module UsosAuthLib
+  class Engine < ::Rails::Engine
+    isolate_namespace UsosAuthLib
+  end
+end

data/lib/usos_auth_lib/version.rb

@@ -0,0 +1,3 @@
+module UsosAuthLib
+  VERSION = '0.1.0'
+end

data/lib/usos_auth_lib.rb

@@ -0,0 +1,82 @@
+require 'usos_auth_lib/version'
+require 'usos_auth_lib/engine'
+require 'oauth'
+
+module UsosAuthLib
+  class Configuration
+    attr_accessor :api_key, :api_secret, :usos_base_url, :scopes, :redirect_path
+
+    def initialize
+      @api_key = nil
+      @api_secret = nil
+      @usos_base_url = nil
+      @scopes = nil
+      @redirect_path = nil
+    end
+  end
+
+  class << self
+    attr_accessor :configuration
+
+    def configure
+      self.configuration ||= Configuration.new
+      yield(configuration)
+    end
+  end
+
+  class UsosAuthorizer
+    def initialize
+      config = UsosAuthLib.configuration
+      @api_key = config.api_key
+      @api_secret = config.api_secret
+      @usos_base_url = config.usos_base_url
+      @scopes = config.scopes
+    end
+
+    def authorize(session, request)
+      callback_url = "#{request.protocol}#{request.host_with_port}/callback"
+      request_token = consumer.get_request_token(
+        { oauth_callback: callback_url },
+        { scopes: @scopes }
+      )
+      session[:request_token] = request_token.token
+      session[:request_token_secret] = request_token.secret
+
+      request_token.authorize_url
+    end
+
+    def access_token(session, verifier, access_token, access_token_secret)
+      token = nil
+
+      if verifier.nil?
+        token = OAuth::AccessToken.new(
+          consumer,
+          access_token,
+          access_token_secret
+        )
+      else
+        request_token = OAuth::RequestToken.new(
+          consumer,
+          session.delete(:request_token),
+          session.delete(:request_token_secret)
+        )
+        token = request_token.get_access_token(oauth_verifier: verifier)
+      end
+
+      token
+    end
+
+    private
+
+    def consumer
+      OAuth::Consumer.new(
+        @api_key,
+        @api_secret,
+        site: @usos_base_url,
+        request_token_path: '/services/oauth/request_token',
+        authorize_path: '/services/oauth/authorize',
+        access_token_path: '/services/oauth/access_token'
+      )
+    end
+  end
+end

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: usos_auth_lib
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- mikolajczu
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2024-01-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: oauth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.2
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: "\n    Enhance your Ruby applications with UsosAuthLib, a robust gem
+  for streamlined user authentication\n    via the USOS API. Simplify your workflow,
+  contribute to the community,\n    and power up your Ruby projects effortlessly with
+  UsosAuthLib.\n  "
+email:
+- mikeyczu@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/config/usos_auth_lib_manifest.js
+- app/assets/stylesheets/usos_auth_lib/application.css
+- app/controllers/usos_auth_lib/usos_controller.rb
+- app/helpers/usos_auth_lib/application_helper.rb
+- app/jobs/usos_auth_lib/application_job.rb
+- app/mailers/usos_auth_lib/application_mailer.rb
+- app/models/concerns/usos_auth_common.rb
+- app/models/usos_auth_lib/application_record.rb
+- app/views/layouts/usos_auth_lib/application.html.erb
+- config/routes.rb
+- lib/tasks/usos_auth_lib_tasks.rake
+- lib/usos_auth_lib.rb
+- lib/usos_auth_lib/engine.rb
+- lib/usos_auth_lib/version.rb
+homepage: https://github.com/mikolajczu/usos_auth_lib
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/mikolajczu/usos_auth_lib
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key: 
+specification_version: 4
+summary: 'UsosAuthLib: Simplify user authentication in Ruby applications with this
+  powerful gem tailored for seamless integration with the USOS API. Streamline your
+  workflow and elevate your projects effortlessly.'
+test_files: []