myinfo 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9c42852df0d1859a05e3b6626cc2abb19945cc2072d5cf2313bacc09ce15eb0b
+  data.tar.gz: 10b5b50b6882dad300511581299872d330df87b3d2df66734af3391406562ead
+SHA512:
+  metadata.gz: dbee0afc819ced257f4392c0983c787e72347e9248cff74e3d1ff4885314005adc744fb4f14c04e5dff6e35da58aa80df7db74e440600636bc0b6cb727cfca80
+  data.tar.gz: be29694339f25994661aafa7d2c581ee94a0179d3b66c4db123ccc71a3fc8b51a925dd21a662c3fd9bc44f12d62fea052c736d7c3c1957ff9dab06bbae7cd952

data/README.md

@@ -0,0 +1,112 @@
+# Rails wrapper for MyInfo API
+
+![tests](https://github.com/GovTechSG/myinfo/workflows/tests/badge.svg?branch=main)
+
+
+[MyInfo Documentation (Public)](https://public.cloud.myinfo.gov.sg/myinfo/api/myinfo-kyc-v3.1.0.html)
+
+[MyInfo Documentation (Government)](https://public.cloud.myinfo.gov.sg/myinfo/tuo/myinfo-tuo-specs.html)
+## Basic Setup (Public)
+
+1. `bundle add myinfo`
+2. Create a `config/initializers/myinfo.rb` and add the required configuration based on your environment.
+```ruby
+  MyInfo.configure do |config|
+    config.app_id = ''
+    config.client_id = ''
+    config.client_secret = ''
+    config.base_url = 'test.api.myinfo.gov.sg' # don't set https://
+    config.redirect_uri = 'https://localhost:3001/callback'
+    config.public_facing = true
+    config.private_key = File.read(Rails.root.join('private_key_location'))
+    config.public_cert = File.read(Rails.root.join('public_cert_location'))
+    config.sandbox = false # optional, false by default
+    config.proxy = { address: 'proxy_address', port: 'proxy_port' } # optional, nil by default
+  end
+```
+
+3. To obtain a person's MyInfo information, we need to authorise the query first:
+```ruby
+redirect_to MyInfo::V3::AuthoriseUrl.call(
+      purpose: 'set your purpose here',
+      state: SecureRandom.hex # set a state to check on callback
+    )
+```
+
+4. On `redirect_url`, obtain a `MyInfo::V3::Token`. This token can only be used once.
+```ruby
+    response = MyInfo::V3::Token.call(
+      code: params[:code],
+      state: params[:state]
+    )
+```
+
+5. Obtain the `access_token` from the `response` and query for `MyInfo::V3::Person`:
+```ruby
+result = MyInfo::V3::Person.call(access_token: response.data) if response.success?
+```
+
+## Basic Setup (Government)
+
+1. `bundle add myinfo`
+2. Create a `config/initializers/myinfo.rb` and add the required configuration based on your environment.
+```ruby
+  MyInfo.configure do |config|
+    config.app_id = ''
+    config.client_id = ''
+    config.client_secret = ''
+    config.base_url = 'test.api.myinfo.gov.sg' # don't set https://
+    config.redirect_uri = 'https://localhost:3001/callback'
+    config.singpass_eservice_id = 'MYINFO-CONSENTPLATFORM'
+    config.private_key = File.read(Rails.root.join('private_key_location'))
+    config.public_cert = File.read(Rails.root.join('public_cert_location'))
+    config.sandbox = false # optional, false by default
+    config.proxy = { address: 'proxy_address', port: 'proxy_port' } # optional, nil by default
+  end
+```
+
+3. To obtain a person's MyInfo information, we need to authorise the query first:
+```ruby
+redirect_to MyInfo::V3::AuthoriseUrl.call(
+      nric_fin: "user's NRIC", # see documentation for list of sample NRICs
+      purpose: 'set your purpose here',
+      state: SecureRandom.hex # set a state to check on callback
+    )
+```
+
+4. On `redirect_url`, obtain a `MyInfo::V3::Token`. This token can only be used once.
+```ruby
+    response = MyInfo::V3::Token.call(
+      code: params[:code],
+      state: params[:state]
+    )
+```
+
+5. Obtain the `access_token` from the `response` and query for `MyInfo::V3::Person`:
+```ruby
+result = MyInfo::V3::Person.call(access_token: response.data) if response.success?
+```
+
+## Sample App Demo
+
+1. `git clone git@github.com:GovTechSG/myinfo-rails.git`
+2. `cd myinfo-rails`
+3. `bundle install`
+4. `cd spec/dummy && rails s`
+5. Navigate to `localhost:3001`
+
+## Advanced
+- `attributes` can be passed to `AuthoriseUrl` and `Person` as an array to override the default attributes queried - check MyInfo for a list of available attributes.
+
+- `success?` can be called on `MyInfo::V3::Response` to determine whether the query has succeeded or failed. Check MyInfo API for a list of responses and how to handle them.
+
+## Disclaimer
+Provided credentials in the repository are either obtained from [MyInfo Demo App](https://github.com/ndi-trusted-data/myinfo-demo-app) or samples online, and are only for testing purposes. They should not be re-used for staging or production environments. Visit the [official MyInfo tutorial](https://www.ndi-api.gov.sg/library/myinfo/tutorial3) for more information.
+
+## Contributing
+
+Contributions are welcome!
+
+1. Fork the repository
+2. Write code and tests
+3. Submit a PR

data/lib/myinfo.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+
+require_relative 'myinfo/errors'
+
+require_relative 'myinfo/helpers/callable'
+require_relative 'myinfo/helpers/attributes'
+
+require_relative 'myinfo/v3/response'
+require_relative 'myinfo/v3/api'
+require_relative 'myinfo/v3/token'
+require_relative 'myinfo/v3/person'
+require_relative 'myinfo/v3/person_basic'
+require_relative 'myinfo/v3/authorise_url'
+
+# Base MyInfo class
+module MyInfo
+  class << self
+    attr_accessor :configuration
+  end
+
+  def self.configure
+    self.configuration ||= Configuration.new
+    yield(configuration)
+  end
+
+  # Configuration to set various properties needed to use MyInfo
+  class Configuration
+    attr_accessor :singpass_eservice_id, :app_id, :base_url, :client_id, :proxy,
+                  :private_key, :public_cert, :client_secret, :redirect_uri
+
+    attr_writer :public_facing, :sandbox
+
+    def initialize
+      @public_facing = false
+      @sandbox = false
+      @proxy = { address: nil, port: nil }
+    end
+
+    def base_url_with_protocol
+      "https://#{base_url}"
+    end
+
+    def public?
+      @public_facing
+    end
+
+    def sandbox?
+      @sandbox
+    end
+  end
+end

data/lib/myinfo/errors.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module MyInfo
+  class MissingConfigurationError < StandardError; end
+
+  class UnavailableError < StandardError; end
+end

data/lib/myinfo/helpers/attributes.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module MyInfo
+  # Attributes parsing
+  module Attributes
+    DEFAULT_VALUES = %i[name sex race dob residentialstatus email mobileno regadd].freeze
+
+    def self.parse(attributes)
+      attributes ||= DEFAULT_VALUES
+
+      attributes.is_a?(String) ? attributes : attributes.join(',')
+    end
+  end
+end

data/lib/myinfo/helpers/callable.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module MyInfo
+  # Service Object
+  module Callable
+    def call(**kwargs)
+      new(**kwargs).call
+    end
+  end
+end

data/lib/myinfo/v3/api.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'jwe'
+require 'jwt'
+
+module MyInfo
+  module V3
+    # Base API class
+    class Api
+      extend Callable
+
+      def endpoint
+        raise NotImplementedError, 'abstract'
+      end
+
+      def params(_args)
+        raise NotImplementedError, 'abstract'
+      end
+
+      def http_method
+        'GET'
+      end
+
+      def support_gzip?
+        false
+      end
+
+      def header(params:, access_token: nil)
+        {
+          'Content-Type' => 'application/json',
+          'Accept' => 'application/json',
+          'Cache-Control' => 'no-cache'
+        }.tap do |values|
+          values['Authorization'] = auth_header(params: params, access_token: access_token) unless config.sandbox?
+
+          if support_gzip?
+            values['Accept-Encoding'] = 'gzip'
+            values['Content-Encoding'] = 'gzip'
+          end
+        end
+      end
+
+      def parse_response(response)
+        if response.code == '200'
+          yield
+        elsif errors.include?(response.code)
+          json = JSON.parse(response.body)
+
+          Response.new(success: false, data: "#{json['code']} - #{json['message']}")
+        else
+          Response.new(success: false, data: "#{response.code} - #{response.body}")
+        end
+      end
+
+      protected
+
+      def decrypt_jwe(text)
+        if config.sandbox?
+          JSON.parse(text)
+        else
+          JWE.decrypt(text, private_key)
+        end
+      end
+
+      def decode_jws(jws)
+        # TODO: verify signature
+        JWT.decode(jws, public_key, true, algorithm: 'RS256').first
+      end
+
+      def http
+        @http ||= if config.proxy.blank?
+                    Net::HTTP.new(config.base_url, 443)
+                  else
+                    Net::HTTP.new(config.base_url, 443, config.proxy[:address], config.proxy[:port])
+                  end
+
+        @http.use_ssl = true
+        @http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+
+        @http
+      end
+
+      def config
+        MyInfo.configuration
+      end
+
+      private
+
+      def private_key
+        raise MissingConfigurationError, :private_key if config.private_key.blank?
+
+        OpenSSL::PKey::RSA.new(config.private_key)
+      end
+
+      def public_key
+        raise MissingConfigurationError, :public_cert if config.public_cert.blank?
+
+        OpenSSL::X509::Certificate.new(config.public_cert).public_key
+      end
+
+      def to_query(headers)
+        headers.sort_by { |k, v| [k.to_s, v] }
+               .map { |arr| arr.join('=') }
+               .join('&')
+      end
+
+      def auth_header(params:, access_token: nil)
+        auth_headers = {
+          app_id: config.app_id,
+          nonce: SecureRandom.hex,
+          signature_method: 'RS256',
+          timestamp: (Time.now.to_f * 1000).to_i
+        }.merge(params)
+
+        auth_headers[:signature] = sign(auth_headers)
+
+        header_elements = auth_headers.map { |k, v| "#{k}=\"#{v}\"" }
+        header_elements << "Bearer #{access_token}" if access_token.present?
+
+        "PKI_SIGN #{header_elements.join(',')}"
+      end
+
+      def sign(headers)
+        headers_query = to_query(headers)
+        base_string = "#{http_method}&#{config.base_url_with_protocol}/#{slug}&#{headers_query}"
+        signed_string = private_key.sign(OpenSSL::Digest.new('SHA256'), base_string)
+        Base64.strict_encode64(signed_string)
+      end
+    end
+  end
+end

data/lib/myinfo/v3/authorise_url.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module MyInfo
+  module V3
+    # https://public.cloud.myinfo.gov.sg/myinfo/tuo/myinfo-tuo-specs.html#operation/getauthorise
+    class AuthoriseUrl
+      extend Callable
+
+      attr_accessor :nric_fin, :attributes, :purpose, :state, :authmode, :login_type
+
+      def initialize(purpose:, state:, nric_fin: nil, authmode: 'SINGPASS', login_type: 'SINGPASS', attributes: nil)
+        @nric_fin = nric_fin
+        @attributes = Attributes.parse(attributes)
+        @purpose = purpose
+        @authmode = authmode
+        @login_type = login_type
+        @state = state
+      end
+
+      def call
+        query_string = {
+          authmode: authmode,
+          login_type: login_type,
+          purpose: purpose,
+          client_id: config.client_id,
+          attributes: attributes,
+          sp_esvcId: config.singpass_eservice_id,
+          state: state,
+          redirect_uri: config.redirect_uri
+        }.compact.to_param
+
+        endpoint(query_string)
+      end
+
+      def endpoint(query_string)
+        if config.public?
+          "#{config.base_url_with_protocol}/#{slug}/?#{query_string}"
+        else
+          "#{config.base_url_with_protocol}/#{slug}/#{nric_fin}/?#{query_string}"
+        end
+      end
+
+      def slug
+        slug_prefix = config.public? ? 'com' : 'gov'
+
+        "#{slug_prefix}/v3/authorise"
+      end
+
+      def config
+        MyInfo.configuration
+      end
+    end
+  end
+end

data/lib/myinfo/v3/person.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module MyInfo
+  module V3
+    # Calls the Person API
+    class Person < Api
+      attr_accessor :access_token, :decoded_token, :attributes, :txn_no
+
+      def initialize(access_token:, txn_no: nil, attributes: nil)
+        @access_token = access_token
+        @decoded_token = decode_jws(access_token)
+        @attributes = Attributes.parse(attributes)
+        @txn_no = txn_no
+      end
+
+      def call
+        headers = header(params: params, access_token: access_token)
+        endpoint_url = "/#{slug}?#{params.to_query}"
+
+        response = http.request_get(endpoint_url, headers)
+        parse_response(response)
+      end
+
+      def slug
+        slug_prefix = config.public? ? 'com' : 'gov'
+
+        "#{slug_prefix}/v3/person/#{nric_fin}/"
+      end
+
+      def support_gzip?
+        true
+      end
+
+      def params
+        {
+          txnNo: txn_no,
+          attributes: attributes,
+          client_id: config.client_id,
+          sp_esvcId: config.singpass_eservice_id
+        }.compact
+      end
+
+      def nric_fin
+        @nric_fin ||= decoded_token['sub']
+      end
+
+      def errors
+        %w[401 403 404]
+      end
+
+      def parse_response(response)
+        super do
+          json = decrypt_jwe(response.body)
+          json = decode_jws(json.delete('"')) unless config.sandbox?
+
+          Response.new(success: true, data: json)
+        end
+      end
+    end
+  end
+end

data/lib/myinfo/v3/person_basic.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module MyInfo
+  module V3
+    # Calls the PersonBasic API
+    class PersonBasic < Api
+      attr_accessor :nric_fin, :attributes, :txn_no
+
+      def initialize(nric_fin:, txn_no: nil, attributes: nil)
+        raise UnavailableError, 'person-basic endpoint is not available for public-facing APIs.' if config.public?
+
+        @attributes = Attributes.parse(attributes)
+        @nric_fin = nric_fin
+        @txn_no = txn_no
+      end
+
+      def call
+        headers = header(params: params)
+        endpoint_url = "/#{slug}?#{params.to_query}"
+
+        response = http.request_get(endpoint_url, headers)
+        parse_response(response)
+      end
+
+      def slug
+        "gov/v3/person-basic/#{nric_fin}/"
+      end
+
+      def support_gzip?
+        true
+      end
+
+      def params
+        {
+          txnNo: txn_no,
+          attributes: attributes,
+          client_id: config.client_id,
+          sp_esvcId: config.singpass_eservice_id
+        }.compact
+      end
+
+      def errors
+        %w[401 403 404 428 default]
+      end
+
+      def parse_response(response)
+        super do
+          json = decrypt_jwe(response.body)
+          json = decode_jws(json.delete('\"')) unless config.sandbox?
+
+          Response.new(success: true, data: json)
+        end
+      end
+    end
+  end
+end

data/lib/myinfo/v3/response.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module MyInfo
+  module V3
+    # Simple response wrapper
+    class Response
+      attr_accessor :success, :data
+
+      def initialize(success:, data:)
+        @success = success
+        @data = data
+      end
+
+      def success?
+        @success
+      end
+
+      def to_s
+        data
+      end
+    end
+  end
+end

data/lib/myinfo/v3/token.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module MyInfo
+  module V3
+    # Called after authorise to obtain a token for API calls
+    class Token < Api
+      attr_accessor :code, :state
+
+      def initialize(code:, state: nil)
+        @code = code
+        @state = state
+      end
+
+      def call
+        headers = header(params: params).merge({ 'Content-Type' => 'application/x-www-form-urlencoded' })
+        response = http.request_post("/#{slug}", params.to_param, headers)
+
+        parse_response(response)
+      end
+
+      def http_method
+        'POST'
+      end
+
+      def slug
+        slug_prefix = config.public? ? 'com' : 'gov'
+
+        "#{slug_prefix}/v3/token"
+      end
+
+      def params
+        {
+          code: code,
+          state: state,
+          client_id: config.client_id,
+          client_secret: config.client_secret,
+          grant_type: 'authorization_code',
+          redirect_uri: config.redirect_uri
+        }.compact
+      end
+
+      def errors
+        %w[400 401]
+      end
+
+      def parse_response(response)
+        super do
+          json = JSON.parse(response.body)
+          access_token = json['access_token']
+
+          Response.new(success: true, data: access_token)
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,179 @@
+--- !ruby/object:Gem::Specification
+name: myinfo
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Lim Yao Jie
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2020-01-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jwe
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.10'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.11'
+description: Rails wrapper for MyInfo API
+email: limyaojie93@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/myinfo.rb
+- lib/myinfo/errors.rb
+- lib/myinfo/helpers/attributes.rb
+- lib/myinfo/helpers/callable.rb
+- lib/myinfo/v3/api.rb
+- lib/myinfo/v3/authorise_url.rb
+- lib/myinfo/v3/person.rb
+- lib/myinfo/v3/person_basic.rb
+- lib/myinfo/v3/response.rb
+- lib/myinfo/v3/token.rb
+homepage: https://rubygems.org/gems/myinfo
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.4
+signing_key:
+specification_version: 4
+summary: MyInfo gem
+test_files: []