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


## 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
```


## 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],
    ) unless user

    user
  end
end
```

Here's an example for callback method in `controllers/users_controller.rb`:
```ruby
  def callback
    user = User.from_usos(session.delete(:user_data))
    session[:current_user_id] = user.id
  end
```

Here's an example for use of handle_request and get_terms_grades method in `controllers/users_controller.rb`:
```ruby
class UsersController < ApplicationController
  include UsosAuthCommon
  def grades
    response = handle_request(session[:access_token], session[:access_token_secret], '/services/grades/terms2?term_ids=2023/24Z|2022/23L')

    response_2 = get_terms_grades(session[:access_token], session[:access_token_secret], '2023/24Z|2022/23L')
  end
end
```
In this example, we want to retrieve all grades from the 2023/2024Z and 2022/2023L 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/`

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