{"id":22052700,"url":"https://github.com/digitalnz/omniauth-realme","last_synced_at":"2025-10-11T13:30:21.142Z","repository":{"id":39700804,"uuid":"146816847","full_name":"DigitalNZ/omniauth-realme","owner":"DigitalNZ","description":"Omniauth Realme","archived":false,"fork":false,"pushed_at":"2024-09-19T03:41:00.000Z","size":95,"stargazers_count":2,"open_issues_count":4,"forks_count":2,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-04T15:40:25.996Z","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":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DigitalNZ.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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-08-30T23:21:16.000Z","updated_at":"2024-09-19T03:34:55.000Z","dependencies_parsed_at":"2024-11-30T15:14:08.764Z","dependency_job_id":"5bbbd241-f4be-4b8c-a97d-f03b23c34cf7","html_url":"https://github.com/DigitalNZ/omniauth-realme","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/DigitalNZ/omniauth-realme","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DigitalNZ%2Fomniauth-realme","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DigitalNZ%2Fomniauth-realme/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DigitalNZ%2Fomniauth-realme/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DigitalNZ%2Fomniauth-realme/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DigitalNZ","download_url":"https://codeload.github.com/DigitalNZ/omniauth-realme/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DigitalNZ%2Fomniauth-realme/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279007341,"owners_count":26084282,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"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":[],"created_at":"2024-11-30T15:14:00.078Z","updated_at":"2025-10-11T13:30:20.833Z","avatar_url":"https://github.com/DigitalNZ.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# omniauth-realme\n\n![CI](https://github.com/DigitalNZ/omniauth-realme/workflows/CI/badge.svg)\n\nOmniauth strategy for New Zealand's secure online identity verification service.\n\nThis Gem has been developed for the intention of using [Devise](https://github.com/plataformatec/devise) as the account model with Realme SSO integration.\nThis gem covers all of the SAML client requirements for RealMe integrations including the RealMe's default error messages.\n\nYou will need to set up your frontend login pages to match [RealMe's branding guidelines](https://developers.realme.govt.nz/how-to-integrate/application-design-and-branding-guide/realme-page-elements/)\nWe suggest you use their assets in a zip file on their page.\n\nGetting to Production:\nYou will need to complete the [RealMe Operational handover checklist](https://developers.realme.govt.nz/how-to-integrate/getting-to-production/operational-handover-checklist/) `login service` form to gain access to RealMe production environments.\n\nNot using *Ruby* but need to integrate? Use this gem as a baseline and find a suitable Library on [onelogin's](https://github.com/onelogin) github account.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'devise'\ngem 'omniauth-realme'\n```\n\nAnd then execute:\n\n    $ bundle\n\n### Realme\nTo test that you have installed the Gem correctly integrate with their message testing servies [RealMe MTS](https://mts.realme.govt.nz/logon-mts/home) first, followed by ITE then Production integrations.\n\nYou will need to set up your applications integration via their [developers website](https://developers.realme.govt.nz) for ITE and production.\n\n### Devise\n\nSetup\n\n```ruby\n# config/initializers/devise.rb\nDevise.setup do |config|\n  # ...\n  config.omniauth :realme\nend\n```\n\nHere we configure the [ruby-saml](https://github.com/onelogin/ruby-saml) gem.\nRealme provides the necessary `service-metadata.xml` files for their side of the integration. They can be found on this [page](https://developers.realme.govt.nz/how-realme-works/technical-integration-steps#e75)\n\n```ruby\n# config/initializers/omniauth.rb\n\n# Use OmniAuthCallbacksController#failure as the Rack app which OmniAuth will\n# redirect to in the event of a failure\nOmniAuth.config.on_failure = Proc.new { |env| OmniAuthCallbacksController.action(:failure).call(env) }\n\nOmniAuth.configure do |config|\n  # Always redirect to the failure endpoint if there is an error. Normally the\n  # exception would just be raised in development mode. This is useful for\n  # testing your Realme error handling in development.\n  config.failure_raise_out_environments = []\n\n  # We want to see OmniAuth messages in the log\n  config.logger = Rails.logger\nend\n```\n\n```ruby\n# config/initializers/realme_omniauth.rb\nOmniAuth::Strategies::Realme.configure do |config|\n  # Website issuer namespace\n  config.issuer = 'http://myapp/\u003cissuer\u003e/\u003caccess\u003e'\n\n  # Callback url\n  config.assertion_consumer_service_url = 'http://myapp.com/users/auth/realme/callback'\n\n  # Sign the request saml and decrypt response\n\n  # Read the public+private keypair from a file. This example demonstrates\n  # using the .p12 file Realme provides to help you get up an running with their\n  # MTS environment.\n  p12 = OpenSSL::PKCS12.new(File.read(Rails.root.join(\"realme/Integration-Bundle-MTS-V3.2/mts_saml_sp.p12\")), \"password\")\n\n  # Give the strategy the public key that will identify your SP to Realme (the IdP)\n  config.certificate = p12.certificate.to_s\n\n  # Give the strategy the corresponding private key so it can decrypt messages\n  # sent by Realme which are encrypted with the public key\n  config.private_key = p12.key.to_s\n\n  # Realme login service xml file.\n  # You will need to download the different XML files for the different environments found here: https://developers.realme.govt.nz/how-realme-works/technical-integration-steps/\n  config.idp_service_metadata = Rails.root.join('path', 'to', 'logon-service-metadata.xml')\n\n  # default strength\n  config.auth_strength = 'urn:nzl:govt:ict:stds:authn:deployment:GLS:SAML:2.0:ac:classes:LowStrength'\n\n  # The allowed clock drift is added to the current time at which the response\n  # is validated before it's tested against the NotBefore assertion. Its value\n  # must be given in a number (and/or fraction) of seconds.\n  #\n  # Make sure to keep the value as comfortably small as possible to keep\n  # security risks to a minimum.\n  #\n  # See: https://github.com/onelogin/ruby-saml#clock-drift\n  #\n  config.allowed_clock_drift = 5.seconds # default is 0.seconds\n\n  # It can be very useful to fail noisily in development if there are SAML\n  # validation errors. We recommend enabling this in Rails development env at\n  # least.\n  #\n  config.raise_exceptions_for_saml_validation_errors = Rails.env.development? # default: false\n\n  # Versions 0.1.0 and older of this gem return the FLT or any errors from\n  # Realme in the Rails session. We are migrating away from this to a more\n  # conventional OmniAuth approach of returning the FLT in\n  # `request.env['omniauth.auth'] and errors redirect to the OmniAuth failure\n  # Rack app.\n  #\n  # As of version 0.1.0, using the Rails session is enabled by default to not\n  # break existing installations. If you are configuring this strategy in a new\n  # application, you should set this behaviour to `false` to ensure your app\n  # continues to work seamlessly in future versions of this gem.\n  #\n  config.legacy_rails_session_behaviour_enabled = false\nend\n```\n\nRoutes\n\n```ruby\n# config/routes.rb\n\n# Add/edit the `devise_for` line in your routes file as shown here\ndevise_for :users, controllers: { omniauth_callbacks: 'users/omniauth_callbacks' }\n```\n\nControllers\n```ruby\n# app/controllers/application_controller.rb\nclass ApplicationController \u003c ActionController::Base\n  before_action :configure_permitted_parameters, if: :devise_controller?\n  # ...\n\n  private\n\n  def configure_permitted_parameters\n    # :uid, :provider and any new fields need to be added here\n    devise_parameter_sanitizer.permit(:sign_up, keys: [:password, :password_confirmation, :email, :uid, :provider])\n  end\n\n  # ...\nend\n```\n\nThe customer `uid` will come through in `request.env['omniauth.auth']['uid']`\n\n```ruby\n# app/controllers/users/omniauth_callbacks_controller.rb\n\nmodule Users\n  class OmniauthCallbacksController \u003c ::Devise::OmniauthCallbacksController\n    skip_before_action :verify_authenticity_token\n\n    def realme\n      realme_flt_token = request.env[\"omniauth.auth\"][\"uid\"]\n      @user = User.from_omniauth('realme', realme_flt_token)\n\n      unless @user.valid?\n        @user.errors.each { |err| @user.errors.delete(err) }\n\n        flash.notice = 'RealMe login successful, please fill in your user details.'\n        return render 'devise/registrations/new.html.haml'\n      end\n\n      flash.notice = 'RealMe login successful.'\n\n      sign_in_and_redirect @user\n    end\n\n    def failure\n      exception = request.env[\"omniauth.error\"] # a reference to the exception instance class\n      error_type = request.env[\"omniauth.error.type\"] # the first symbol passed to fail!()\n      erroring_strategy = request.env[\"omniauth.error.strategy\"] # a reference to the strategy instance that threw the error\n\n      flash.alert = \"Realme login failed because #{exception.message}\"\n      redirect_to root_path\n    end\n  end\nend\n```\n\nViews\n  - You will need to update your registration `new` and `edit` views by adding the new fields as well as hidden fields for `provider` and `uid`.\n  - User sign in view will also need to be updated so that it links to the OmniAuth realme pass through using the link helper `user_realme_omniauth_authorize_path`.\n\nModel\n```ruby\n# app/models/user.rb\nclass User \u003c ApplicationRecord\n  # Include default devise modules. Others available are:\n  # :confirmable, :lockable, :timeoutable, :trackable and :omniauthable\n  devise :database_authenticatable, :registerable,\n         :recoverable, :rememberable, :validatable,\n         :omniauthable, omniauth_providers: [:realme]\n\n  validates :provider, presence: true\n  validates :uid,      presence: true, uniqueness: true\n  validates :email,    presence: true, uniqueness: true\n\n  def self.from_omniauth(provider, uid)\n    where(provider: provider, uid: uid).first_or_create do |user|\n      user.provider = provider\n      user.uid      = uid\n    end\n  end\nend\n```\n\nMigrations\n  - You will need to add `provider` and `uid` to your model and index the `uid`\n```ruby\n# db/migrate/\u003ctimestamp\u003e_devise_create_users.rb\nclass DeviseCreateUsers \u003c ActiveRecord::Migration[5.2]\n  def change\n    create_table :users do |t|\n      # ...\n\n      t.string :provider, null: false\n      t.string :uid,      null: false, unique: true\n\n      # ...\n    end\n     # ...\n    add_index :users, :uid, unique: true\n  end\nend\n```\n\nRemove SAMLResponse from Rails log\n```ruby\n#config/initializers/filter_parameter_logging.rb\nRails.application.config.filter_parameters += [:password, 'SAMLResponse']\n```\n\n## Metadata\n\nThis gem includes `OmniAuth::Realme.generate_metadata_xml` which will generate SAML SP metadata in a form suitable for uploading to the [Realme MTS Metadata upload](https://mts.realme.govt.nz/logon-mts/metadataupdate) endpoint using the same settings you used to configure this strategy.\n\nBelow is an example of using it to create a `/saml/metadata.xml` endpoint in your app. This can be convenient but might be unnecessary for your application, depending on your use case so this step is optional.\n\n```ruby\n# config/routes.rb\n\n# Example: curl http://localhost:3000/saml/metadata.xml\nget \"saml/metadata\", to: \"saml_metadata#metadata\"\n```\n\n```ruby\n# app/controllers/saml_metadata_controller.rb\nclass SamlMetadataController \u003c ApplicationController\n  # Skip authentication on the metadata action (this line is only required if\n  # you are using devise)\n  skip_before_action :authenticate_user!, only: [:metadata]\n\n  def metadata\n    respond_to do |format|\n      format.xml  { render xml: OmniAuth::Realme.generate_metadata_xml }\n    end\n  end\nend\n```\n\nIf you don't need an endpoint in your app you can just invoke the function from the console e.g.\n\n```ruby\nrails-console\u003e puts OmniAuth::Realme.generate_metadata_xml\n```\n\n## Realme Context Mapping Service (RCMS)\n\n[Realme Context Mapping Service](https://developers.realme.govt.nz/how-realme-works/whats-realme-rcms/) is an additional service which your app can optionally integrate with.\n\nMost of the work of integrating with RCMS is outside of the scope of what OmniAuth does. If your app is using RCMS then you will receive a _Login Attributes Token_ as well as the normal Realme FLT with the SAMLResponse.\n\nThis strategy facilitates your use of RCMS by making that additional token (if\nit exists) available in\n`request.env['omniauth.auth']['credentials']['realme_cms_lat']` e.g.\n\n```ruby\n# app/controllers/users/omniauth_callbacks_controller.rb\n\nmodule Users\n  class OmniauthCallbacksController \u003c ::Devise::OmniauthCallbacksController\n    skip_before_action :verify_authenticity_token\n\n    def realme\n      realme_flt = request.env['omniauth.auth']['uid']\n      realme_cms_lat = request.env['omniauth.auth']['credentials']['realme_cms_lat']\n\n      # complete your RCMS integration here ...\n    end\n  end\nend\n```\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` 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/DigitalNZ/omniauth-realme.\n\n## License\n  GNU GENERAL PUBLIC LICENSE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitalnz%2Fomniauth-realme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdigitalnz%2Fomniauth-realme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitalnz%2Fomniauth-realme/lists"}