{"id":38542284,"url":"https://github.com/mitigate-dev/smart-id-ruby","last_synced_at":"2026-01-17T07:12:19.026Z","repository":{"id":51448033,"uuid":"244621396","full_name":"mitigate-dev/smart-id-ruby","owner":"mitigate-dev","description":"Smart ID API Wrapper for Ruby applications","archived":false,"fork":false,"pushed_at":"2024-01-22T10:27:11.000Z","size":44,"stargazers_count":3,"open_issues_count":0,"forks_count":8,"subscribers_count":6,"default_branch":"master","last_synced_at":"2026-01-13T08:17:04.405Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/mitigate-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2020-03-03T11:43:13.000Z","updated_at":"2023-10-30T07:00:59.000Z","dependencies_parsed_at":"2023-11-12T21:44:54.717Z","dependency_job_id":null,"html_url":"https://github.com/mitigate-dev/smart-id-ruby","commit_stats":null,"previous_names":["zippyvision/smart-id-ruby"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/mitigate-dev/smart-id-ruby","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitigate-dev%2Fsmart-id-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitigate-dev%2Fsmart-id-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitigate-dev%2Fsmart-id-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitigate-dev%2Fsmart-id-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mitigate-dev","download_url":"https://codeload.github.com/mitigate-dev/smart-id-ruby/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitigate-dev%2Fsmart-id-ruby/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28503176,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T06:57:29.758Z","status":"ssl_error","status_checked_at":"2026-01-17T06:56:03.931Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-01-17T07:12:18.360Z","updated_at":"2026-01-17T07:12:19.012Z","avatar_url":"https://github.com/mitigate-dev.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SmartId\n\nThis gem provides a wrapper around [Smart ID API](https://github.com/SK-EID/smart-id-documentation). All the necessary checks, listed in point 3.5 are implemented. Currently this gem only supports authentication actions.\n\n# TODO\n- [x] Add authentication functionality\n- [ ] Add Signing functionality (see if possible)\n- [ ] More test coverage\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'smart_id', \"~\u003e 0.1\"\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install smart_id\n\n## Usage\n\n### Configuration\n\nconfiguration can be done, by creating an initializer file and loading it before the application starts.\n\n```ruby\nSmartId.configure do |config|\n    config.relying_party_uuid = \"MySmartIdUUID\"\n    config.relying_party_name = \"My Smart ID name\"\n    config.environment = \"demo\" # possible options ar \"demo\" and \"production\", uses according smart-id parameters and keys\n    config.default_certificate_level = \"ADVANCED\" # Possible options are \"ADVANCED\" or \"QUALIFIED\". Defaults to \"ADVANCED\"\n    config.poller_timeout_secods = 10 # seconds to wait when fetching authentication confirmation\nend\n\n```\n### Authentication types\n\nAuthentication can be done either with providing user's national identity number or an identity document number\n\nFor national identity number use\n```ruby\nSmartId::Api::Authentication::IdentityNumber\n```\n\nFor document number use\n```ruby\nSmartId::Api::Authentication::Document\n```\nSmart ID authentication is done in 2 steps - **initializing the authentication** and then **getting confimation from Smart ID** service. Those two steps happen asynchronously, so some parameters should be persisted either in session storage or in database\n\n* Back-end initializes authentification - user can see verification code on the app, and receives smart ID request to input PIN in they're mobile \n\n* Back-end authenfication confirmation - check whether user has authenticated by correctly typing in they're PIN on the mobile device\n\n## Authentication Request\n\nTo initialize authentication make a controller action. \n\n#### National identity number\n\n```ruby\nclass UserController \u003c AplicationController\n    #...\n    def authenticate_smart_id\n        # authentication hash by default will generate random bytes, that will be hashed for signature check\n        # if you wish to provide your own randomization, you can pass a parameter to AuthenticationHash with the random string\n        # authentication_hash = SmartId::Utils::AuthenticationHash.new(SecureRandom.hex(64))\n        # each authentication should have a unique random string passed\n        authentication_hash = SmartId::Utils::AuthenticationHash.new\n\n        auth_response = SmartId::Api::Authentication::IdentityNumber.authenticate(\n            country: params[:country], # 2 character ISO 3166-1 alpha-2 format(for example EE, LT, LV, KZ)\n            identity_number: params[:identity_number],\n            authentication_hash: authentication_hash\n        )\n\n        session[:smart_id_session] = auth_response.session_id\n        session[:auth_hash] = authentication_hash.hash_data\n\n        # Screen/page after this call should show the user verification code, to see if it matches\n        # the one they see on their mobile device\n        render json: { verification_code: auth_response.verification_code }\n\n    end\n    #...\nend\n\n```\n\n#### Document number\n\n```ruby\nclass UserController \u003c AplicationController\n    #...\n    def authenticate_smart_id\n        # authentication hash by default will generate random bytes, that will be hashed for signature check\n        # if you wish to provide your own randomization, you can pass a parameter to AuthenticationHash with the random string\n        # authentication_hash = SmartId::Utils::AuthenticationHash.new(SecureRandom.hex(64))\n        # each authentication should have a unique random string passeds\n        authentication_hash = SmartId::Utils::AuthenticationHash.new\n\n        auth_response = SmartId::Api::Authentication::Document.authenticate(\n            document_number: params[:document_number],\n            authentication_hash: authentication_hash\n        )\n\n        session[:smart_id_session] = auth_response.session_id\n        session[:auth_hash] = authentication_hash.hash_data\n\n        # Screen/page after this call should show the user verification code, to see if it matches\n        # the one they see on their mobile device\n        render json: { verification_code: auth_response.verification_code }\n\n    end\n    #...\nend\n\n```\n\n## Authentication Confirmation\nCreate another controller action\n\n```ruby\nclass UserController \u003c AplicationController\n    #...\n    def confirm_smart_id\n        # use hash_data saved on authentication initialization as parameter\n        authentication_hash = SmartId::Utils::AuthenticationHash.new(session[:auth_hash])\n\n        confirmation_response = SmartId::Api::Authentication::ConfirmationPoller.confirm(\n            session_id: session[:smart_id_session],\n            authentication_hash: authentication_hash,\n            # if true, will continously make requests to smart-id and return only after verification is completed\n            # you can set this parameter to false, to handle polling yourself\n            poll: true # default - true \n        )\n    end\n    #...\nend \n```\n\n\n## Response structure\n\nconfirmation response will have the following attributes\n```ruby \nauthentication_hash = SmartId::Utils::AuthenticationHash.new(session[:auth_hash])\n\nconfirmation_response = SmartId::Api::Authentication::ConfirmationPoller.confirm(\n    session_id: session[:smart_id_session],\n    authentication_hash: authentication_hash,\n    # if true, will continously make requests to smart-id and return only after verification is completed\n    # you can set this parameter to false, to handle polling yourself\n    poll: true # default - true \n)\n\nconfirmation_response.confirmation_running? # =\u003e true/false whether the user has finished authentication. Relevant, only if polling is not handled by the gem (with `poll` parameter set to false)\nconfirmation_response.end_result  # =\u003e end result of the verification. possible values are \"OK\"/\"USER_REFUSED\"/\"TIMEOUT\"/\"DOCUMENT_UNUSABLE\", see details in https://github.com/SK-EID/smart-id-documentation#5-session-end-result-codes\nconfirmation_response.document_number #=\u003e document number for user\nconfirmation_response.certificate_level #=\u003e certificate level for user - values are \"ADVANCED\" or \"QUALIFIED\"\n\nconfirmation_response.certificate.content.given_name #=\u003e given name for user\nconfirmation_response.certificate.content.surname #=\u003e surname for user\nconfirmation_response.certificate.content.serial_number #=\u003e string, that includes user's national identity number\nconfirmation_response.certificate.date_of_birth_from_attribute #=\u003e user's date of birth (available even for users who's latvian identity number starts with 32)\n\n```\n\n## Customization options\nYou can provide extra parameters when initializing authentication (for both - identity number and document)\n\n```ruby\nSmartId::Api::Authentication::Document.authenticate(\n    document_number: \"\", # REQUIRED - document number\n    authentication_hash: obj, # REQUIRED - authentification hash object of SmartId::Utils::AuthenticationHash\n    certificate_level: \"\", # OPTIONAL - Either \"ADVANCED\" or \"QUALIFIED\" - if none are provided, default certificate level is used\n    display_text: nil, # OPTIONAL - Text that user will see on their mobile device when asked for authentication\n    multiple_choice: false, # OPTIONAL - If true, user will be asked to choose the correct verification code from supplied options on their device\n)\n\nSmartId::Api::Authentication::IdentityNumber.authenticate(\n    country: \"\", # REQUIRED - 2 character ISO 3166-1 alpha-2 format(for example EE, LT, LV, KZ)\n    identity_number: \"\", # REQUIRED - natioanl identity number\n    authentication_hash: obj, # REQUIRED - authentification hash object of SmartId::Utils::AuthenticationHash\n    certificate_level: \"\", # OPTIONAL - Either \"ADVANCED\" or \"QUALIFIED\" - if none are provided, default certificate level is used\n    display_text: nil, # OPTIONAL - Text that user will see on their mobile device when asked for authentication\n    multiple_choice: false, # OPTIONAL - If true, user will be asked to choose the correct verification code from supplied options on their device\n)\n```\n\n## Exceptions\nAll exceptions inherit from `SmartId::Exception`\n| Exception class | Description | \n| --------------- | :-----------: |\n| `SmartId::InvalidParamsError` | either country or identity_number were not provided when trying to authenticate with identity number |\n| `SmartId::ConnectionError` | authentication/confirmation request failed, when rescuing see `e.original_error` for more details |\n| `SmartId::NoUserFoundError`| user with the supplied parameters (id number, document number, country) does not exist in smart ID system |\n| `SmartId::SSLCertificateNotVerified` | SSL certificate for smart ID service was not verified. Check for newest version of this gem to always keep cerficates updated |\n| `SmartId::InvalidResponseCertificate` | Certificate used in confirmation response is invalid|\n| `SmartId::InvalidResponseSignature` | Signature used in confirmation response is invalid. |\n| `SmartId::IncorrectAccountLevelError` | User's Smart ID account is below the required level by the authentication request ( \"ADVANCED\" \u003c \"QUALIFIED\") |\n| `SmartId::InvalidPermissionsError` | Relying Party has no permission to issue the request. This may happen when Relying Party has no permission to invoke operations on accounts with ADVANCED certificates. |\n| `SmartId::OutdatedApiError` | API used by the gem is outdated, please see if you are running the newest version of the gem |\n| `SmartId::SystemUnderMaintenanceError` | Smart ID System is under maintenance, try again later |\n\n## Testing\nSmart ID demo environment has provided some sample values to use when testing applications see [Smart ID WIKI page](https://github.com/SK-EID/smart-id-documentation/wiki/Environment-technical-parameters)\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/zippyvision/smart-id-ruby.\n\n## License\n\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%2Fmitigate-dev%2Fsmart-id-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmitigate-dev%2Fsmart-id-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmitigate-dev%2Fsmart-id-ruby/lists"}