{"id":30020713,"url":"https://github.com/mikolajczu/usos_auth_lib","last_synced_at":"2026-04-18T14:01:58.232Z","repository":{"id":215963580,"uuid":"740073426","full_name":"mikolajczu/usos_auth_lib","owner":"mikolajczu","description":"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.","archived":false,"fork":false,"pushed_at":"2024-02-05T17:55:13.000Z","size":71,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-27T19:35:07.393Z","etag":null,"topics":["gem","on","rails","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mikolajczu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"MIT-LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-01-07T12:57:07.000Z","updated_at":"2025-11-24T22:09:08.000Z","dependencies_parsed_at":"2024-12-19T20:01:35.094Z","dependency_job_id":"cd16c9bf-80ba-499c-87c5-aa059721bbf1","html_url":"https://github.com/mikolajczu/usos_auth_lib","commit_stats":null,"previous_names":["mikolajczu/usos_auth_lib"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mikolajczu/usos_auth_lib","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikolajczu%2Fusos_auth_lib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikolajczu%2Fusos_auth_lib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikolajczu%2Fusos_auth_lib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikolajczu%2Fusos_auth_lib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mikolajczu","download_url":"https://codeload.github.com/mikolajczu/usos_auth_lib/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikolajczu%2Fusos_auth_lib/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31971489,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gem","on","rails","ruby"],"created_at":"2025-08-06T02:03:32.907Z","updated_at":"2026-04-18T14:01:53.220Z","avatar_url":"https://github.com/mikolajczu.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# UsosAuthLib\nIntroducing \"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.\n\n## USOS API\nThe 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.\n\nThe 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.\n\n\n## Installation\nAdd this line to your application's Gemfile:\n\n```ruby\ngem \"usos_auth_lib\"\n```\n\nAnd then execute:\n```bash\n$ bundle\n```\n\nOr install it yourself as:\n```bash\n$ gem install usos_auth_lib\n```\n\n\n## Usage\nHere's an example for adding the configuration to a Rails app in `config/initializers/usos_auth_lib.rb`:\n```ruby\nUsosAuthLib.configure do |config|\n  config.api_key = \"ENV.fetch('API_KEY', nil)\"\n  config.api_secret = \"ENV.fetch('API_SECRET', nil)\"\n  config.usos_base_url = 'https://usosapps.umk.pl/'\n  config.scopes = 'email|grades'\n  config.redirect_path = '/usos_auth'\nend\n```\n\n`config.api_key` -\u003e Consumer api key generated by USOS. \u003cbr\u003e\n`config.api_key` -\u003e Consumer secret key generated by USOS. \u003cbr\u003e\n`config.usos_base_url` -\u003e Your consumer secret key generated by USOS. \u003cbr\u003e\n`config.api_key` -\u003e Your consumer secret key generated by USOS. \u003cbr\u003e\n`config.api_key` -\u003e Your consumer secret key generated by USOS. \u003cbr\u003e\n\nThe next step is to mount our routes for `authorize_user` and `callback` to a Rails app in `config/routes.rb`:\n```ruby\nmount UsosAuthLib::Engine =\u003e '/usos_auth_lib'\nget '/authorize_user', to: 'usos_auth_lib/usos#authorize_user'\nget '/callback', to: 'usos_auth_lib/usos#callback'\n```\n\n`get '/authorize_user'` -\u003e replace it with your route or leave it, this is the route used to authorize the user via the USOS API \u003cbr\u003e\n`get '/callback'` -\u003e replace it with your route or leave it, this is the route used to return from USOS, \u003cspan style=\"color: red;\"\u003eTHIS IS NOT THE ROUTE RETURN FROM THE LIBRARY!\u003c/span\u003e, this route is the one we added to the configuration\n\nHere's an example for creating a user or obtain it from our database in `models/users.rb`:\n\n```ruby\nclass User \u003c ApplicationRecord\n  def self.from_usos(token)\n    user = User.where(email: token[:email]).first\n    user = User.create(\n      email: token[:email],\n      first_name: token[:first_name],\n      last_name: token[:last_name],\n      usos_id: token[:id],\n    ) unless user\n\n    user\n  end\nend\n```\n\nHere's an example for callback method in `controllers/users_controller.rb`:\n```ruby\n  def callback\n    user = User.from_usos(session.delete(:user_data))\n    session[:current_user_id] = user.id\n  end\n```\n\nHere's an example for use of handle_request and get_terms_grades method in `controllers/users_controller.rb`:\n```ruby\nclass UsersController \u003c ApplicationController\n  include UsosAuthCommon\n  def grades\n    response = handle_request(session[:access_token], session[:access_token_secret], '/services/grades/terms2?term_ids=2023/24Z|2022/23L')\n\n    response_2 = get_terms_grades(session[:access_token], session[:access_token_secret], '2023/24Z|2022/23L')\n  end\nend\n```\nIn this example, we want to retrieve all grades from the 2023/2024Z and 2022/2023L semester.\n\n## Scopes\nWhen 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.\n\nWhen 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!\n\nCurrently available scope keys:\n\n- 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.\n- cards: Provides access to user's ID cards data, such as chip uid or expiration date\n- 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.\n- crstests: Provides access to details and results of user's course tests.\n- dorm_admin: Provides access to administrative housing operations on user's behalf. For more information, please visit the housing module.\n- edit_user_attrs: Allows editing user's attributes (the same thet the user can edit on his USOSweb profile page).\n- email: Provides access to user's email address.\n- events: Allows access to user's preferences, push notifications, etc.\n- grades: Provides access to grades information.\n- grades_write: Allows access to read and write exam reports.\n- 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.\n- mobile_numbers: Provides access to user's personal mobile phone number(s).\n- 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.\n- other_emails: Provides access to email addresses of other users (i.e. the ones related to your user).\n- payments: Allows access to your payments.\n- personal: Provides access to user's personal data, such as PESEL number, date of birth, etc.\n- photo: Provides read access to user's photo and his/her photo visibility preferences (\"who can see my photo?\").\n- placement_tests: Provides access to results of user's placement tests in foreign languages.\n- 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.\n- 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.\n- 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.\n- 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.\n- student_exams: Provides access to lists of student's exams, information on their examiners, places the exams take place etc.\nstudent_exams_write: Allows to register and unregister the student from his exams.\n- studies: Provides access to lists of programmes, courses, classes and groups which the user attends (as a student).\n- surveys_filling: Allows access to surveys from students point of view. With this scope you can fetch and fill out surveys.\n- surveys_reports: Allows access to reports on surveys that concern user as a lecturer.\n- theses_protocols_write: Allows access to editing diploma exam protocols, e.g. signing protocols.\n\nSource: `https://apps.usos.edu.pl/developers/api/authorization/`\n\n## Contributing\nContribution directions go here.\n\n## License\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikolajczu%2Fusos_auth_lib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmikolajczu%2Fusos_auth_lib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikolajczu%2Fusos_auth_lib/lists"}