gitkit-ruby-client 1.0.0

data/README.rdoc

@@ -0,0 +1,64 @@
+= Google Identity Toolkit Ruby Client
+
+Google Identity Toolkit (Gitkit) ruby client library is for third party sites to easily integrate with Gitkit service.
+
+=== Installation
+
+  gem install gitkit-ruby-client
+
+=== Examples
+
+  # Create a server config file or download it from Google Developer Console
+  # The config file contains Gitkit library config in json format
+  # {
+  #   "clientId" : "oauth2-web-client-id.apps.googleusercontent.com",
+  #   "serviceAccountEmail" : "service-account-email@developer.gserviceaccount.com",
+  #   "serviceAccountPrivateKeyFile" : "path-to-service-account-private-key-file.p12",
+  #   "widgetUrl" : "full-url-of-gitkit-widget-on-your-site",
+  #   "cookieName" : "gtoken",
+  #   "serverKey" : "devconsole-server-key"
+  # }
+
+  # Create a Gitkit client
+  gitkit_client = GitkitLib::GitkitClient.create_from_config_file 'gitkit-server-config.json'
+
+  # Verify the Gitkit token in the incoming http request
+  token = request.cookies["gtoken"]
+  user = gitkit_client.verify_gitkit_token token
+  
+  # Upload passwords
+  def calc_sha1(key, plain_text, salt)
+    hmac = OpenSSL::HMAC.new key, 'sha1'
+    hmac << plain_text
+    hmac << salt
+    hmac.digest
+  end
+  
+  hash_key = 'hash-key'
+  
+  user1 = GitkitLib::GitkitUser.new
+  user1.email = '1234@example.com'
+  user1.user_id = '1234'
+  user1.salt = 'salt-1'
+  user1.password_hash = calc_sha1(hash_key, '1111', 'salt-1')
+  
+  user2 = GitkitLib::GitkitUser.new
+  user2.email = '5678@example.com'
+  user2.user_id = '5678'
+  user2.salt = 'salt-2'
+  user2.password_hash = calc_sha1(hash_key, '5555', 'salt-2')
+  user2.name = '56 78'
+  
+  gitkit_client.upload_users 'HMAC_SHA1', hash_key, [user1, user2]
+  
+  # Get user by email
+  user = gitkit_client.get_user_by_email('1234@example.com')
+  
+  # Get user by id
+  user = gitkit_client.get_user_by_id('5678')
+  
+  # Delete a user
+  gitkit_client.delete_user '5678'
+  
+  # Download all accounts
+  gitkit_client.get_all_users(2) { |account| pp account}

data/lib/gitkit_client.rb

@@ -0,0 +1,290 @@
+# Copyright 2014 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'addressable/uri'
+require 'jwt'
+require 'json'
+require 'rpc_helper'
+require 'uri'
+
+module GitkitLib
+
+  class GitkitClient
+
+    # Create a client from json config file
+    #
+    # @param [String] file file name of the json-format config
+    def self.create_from_config_file(file)
+      config = JSON.parse File.open(file, 'rb') { |io| io.read }
+      p12key = File.open(config['serviceAccountPrivateKeyFile'], 'rb') {
+          |io| io.read }
+      new(
+          config['clientId'],
+          config['serviceAccountEmail'],
+          p12key,
+          config['widgetUrl'],
+          config['serverApiKey'])
+    end
+
+    # Initializes a GitkitClient.
+    #
+    # @param [String] client_id Google oauth2 web client id of this site
+    # @param [String] service_account_email Google service account email
+    # @param [String] service_account_key Google service account private p12 key
+    # @param [String] widget_url url to host the Gitkit widget
+    # @param [String] server_api_key server-side Google API key
+    def initialize(client_id, service_account_email, service_account_key,
+        widget_url, server_api_key = nil)
+      @client_id = client_id
+      @widget_url = widget_url
+      @rpc_helper = RpcHelper.new(service_account_email, service_account_key,
+          server_api_key)
+      @certificates = {}
+    end
+
+    # Verifies a Gitkit token
+    #
+    # @param [String] token_string the token to be verified
+    # @return [GitkitUser, nil] for valid token, [nil, String] otherwise with
+    # error_message.
+    def verify_gitkit_token(token_string)
+      if token_string.nil?
+        return nil, 'no token'
+      end
+      begin
+        parsed_token, _ = JWT.decode(token_string, nil, true) {|header|
+          # key finder
+          key_id = header['kid']
+          unless @certificates.has_key? key_id
+            @certificates = Hash[get_certs.map {|key,cert|
+                [key, OpenSSL::X509::Certificate.new(cert)]}]
+          end
+          @certificates[key_id].public_key
+        }
+        # check expiration time
+        if Time.new.to_i > parsed_token['exp']
+          return nil, 'token expired'
+        end
+        # check audience
+        if parsed_token['aud'] != @client_id
+          return nil, 'audience mismatch'
+        end
+        GitkitUser.parse_from_api_response parsed_token
+      rescue JWT::DecodeError => e
+        return nil, e.message
+      end
+    end
+
+    # Gets Gitkit public certs
+    #
+    # @api private
+    def get_certs
+      @rpc_helper.get_gitkit_certs()
+    end
+
+    # Gets user info by email
+    #
+    # @param [String] email user email
+    # @return [GitkitUser] for the email
+    def get_user_by_email(email)
+      response = @rpc_helper.get_user_by_email email
+      GitkitUser.parse_from_api_response response.fetch('users', [{}])[0]
+    end
+
+    # Gets user info by user id
+    #
+    # @param [String] id user id
+    # @return [GitkitUser] for the id
+    def get_user_by_id(id)
+      response = @rpc_helper.get_user_by_id id
+      GitkitUser.parse_from_api_response response.fetch('users', [{}])[0]
+    end
+
+    # Downloads all user accounts from Gitkit service
+    #
+    # @param [Fixnum] max_results pagination size of each request
+    # @yield [GitkitUser] individual user account
+    def get_all_users(max_results = 10)
+      next_page_token = nil
+      while true
+        next_page_token, accounts = @rpc_helper.download_account(
+            next_page_token, max_results)
+        accounts.each { |account|
+          yield GitkitUser.parse_from_api_response account }
+        if not next_page_token or accounts.length == 0
+          break
+        end
+      end
+    end
+
+    # Uploads multiple accounts to Gitkit service
+    #
+    # @param [String] hash_algorithm password hash algorithm
+    # @param [String] hash_key key of the hash algorithm
+    # @param [Array<GitkitUser>] accounts user accounts to be uploaded
+    def upload_users(hash_algorithm, hash_key, accounts)
+      account_request = accounts.collect { |account| account.to_request }
+      @rpc_helper.upload_account hash_algorithm, JWT.base64url_encode(hash_key),
+          account_request
+    end
+
+    # Deletes a user account from Gitkit service
+    #
+    # @param [String] local_id user id to be deleted
+    def delete_user(local_id)
+      @rpc_helper.delete_account local_id
+    end
+
+    # Get one-time out-of-band code for ResetPassword/ChangeEmail request
+    #
+    # @param [String] full_url the full URL of incoming request
+    # @param [Hash{String=>String}] param dict of HTTP POST params
+    # @param [String] user_ip end user's IP address
+    # @param [String] gitkit_token the gitkit token if user logged in
+    #
+    # @return [Hash] {
+    #    email: user email who is asking reset password
+    #    oobLink: the generated link to be send to user's email
+    #    action: OobAction
+    #    response_body: the http body to be returned
+    #  }
+    def get_oob_result(full_url, param, user_ip, gitkit_token=nil)
+      if param.has_key? 'action'
+        begin
+          if param['action'] == 'resetPassword'
+            oob_link = build_oob_link(full_url,
+                password_reset_request(param, user_ip),
+                param['action'])
+            return password_reset_response(oob_link, param)
+          elsif param['action'] == 'changeEmail'
+            unless gitkit_token
+              return failure_msg('login is required')
+            end
+            oob_link = build_oob_link(full_url,
+                change_email_request(param, user_ip, gitkit_token),
+                param['action'])
+            return email_change_response(oob_link, param)
+          end
+        rescue GitkitClientError => error
+          return failure_msg(error.message)
+        end
+      end
+      failure_msg('unknown request type')
+    end
+
+    def password_reset_request(param, user_ip)
+      {
+        'email' => param['email'],
+        'userIp' => user_ip,
+        'challenge' => param['challenge'],
+        'captchaResp' => param['response'],
+        'requestType' => 'PASSWORD_RESET'
+      }
+    end
+
+    def change_email_request(param, user_ip, gitkit_token)
+      {
+        'email' => param['oldEmail'],
+        'newEmail' => param['newEmail'],
+        'userIp' => user_ip,
+        'idToken' => gitkit_token,
+        'requestType' => 'NEW_EMAIL_ACCEPT'
+      }
+    end
+
+    def build_oob_link(full_url, param, mode)
+      code = @rpc_helper.get_oob_code(param)
+      if code
+        oob_link = Addressable::URI.parse full_url
+        oob_link.path = @widget_url
+        oob_link.query_values = { 'mode' => mode, 'oobCode' => code}
+        return oob_link.to_s
+      end
+      nil
+    end
+
+    def failure_msg(msg)
+      {:response_body => {'error' => msg}}.to_json
+    end
+
+    def email_change_response(oob_link, param)
+      {
+        :oldEmail => param['email'],
+        :newEmail => param['newEmail'],
+        :oobLink => oob_link,
+        :action => :CHANGE_EMAIL,
+        :response_body => {'success' => true}.to_json
+      }
+    end
+
+    def password_reset_response(oob_link, param)
+      {
+        :email => param['email'],
+        :oobLink => oob_link,
+        :action => :RESET_PASSWORD,
+        :response_body => {'success' => true}.to_json
+      }
+    end
+  end
+
+  class GitkitUser
+    attr_accessor :email, :user_id, :name, :photo_url, :provider_id,
+        :email_verified, :password_hash, :salt, :password, :provider_info
+
+    def self.parse_from_api_response(api_response)
+      user = self.new
+      user.email = api_response.fetch('email', nil)
+      user.user_id = api_response.fetch('user_id',
+          api_response.fetch('localId', nil))
+      user.name = api_response.fetch('displayName', nil)
+      user.photo_url = api_response.fetch('photoUrl', nil)
+      user.provider_id = api_response.fetch('provider_id',
+          api_response.fetch('providerId', nil))
+      user.email_verified = api_response.fetch('emailVerified',
+          api_response.fetch('verified', nil))
+      user.password_hash = api_response.fetch('passwordHash', nil)
+      user.salt = api_response.fetch('salt', nil)
+      user.password = api_response.fetch('password', nil)
+      user.provider_info = api_response.fetch('providerUserInfo', {})
+      user
+    end
+
+    # Convert to gitkit api request (a dict)
+    def to_request
+      request = {}
+      request['email'] = @email if @email
+      request['localId'] = @user_id if @user_id
+      request['displayName'] = @name if @name
+      request['photoUrl'] = @photo_url if @photo_url
+      request['emailVerified'] = @email_verified if @email_verified != nil
+      request['passwordHash'] =
+          JWT.base64url_encode @password_hash if @password_hash
+      request['salt'] = JWT.base64url_encode @salt if @salt
+      request['providerUserInfo'] = @provider_info if @provider_info != nil
+      request
+    end
+  end
+
+  class GitkitClientError < StandardError
+    def initialize(message)
+      super
+    end
+  end
+
+  class GitkitServerError < StandardError
+    def initialize(message)
+      super
+    end
+  end
+end

data/lib/rpc_helper.rb

@@ -0,0 +1,209 @@
+# Copyright 2014 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'jwt'
+require 'json'
+require 'faraday'
+require 'gitkit_client'
+require 'openssl'
+
+module GitkitLib
+  class RpcHelper
+    attr_accessor :access_token, :token_issued_at, :token_duration
+
+    TOKEN_ENDPOINT = 'https://accounts.google.com/o/oauth2/token'
+    GITKIT_SCOPE = 'https://www.googleapis.com/auth/identitytoolkit'
+    GITKIT_API_URL =
+        'https://www.googleapis.com/identitytoolkit/v3/relyingparty/'
+
+    def initialize(service_account_email, service_account_key, server_api_key,
+        google_token_endpoint = TOKEN_ENDPOINT)
+      @service_account_email = service_account_email
+      @google_api_url = google_token_endpoint
+      @connection = Faraday::Connection.new
+      @service_account_key =
+          OpenSSL::PKCS12.new(service_account_key, 'notasecret').key
+      @server_api_key = server_api_key
+      @token_duration = 3600
+      @token_issued_at = 0
+      @access_token = nil
+    end
+
+    # GetAccountInfo by email
+    #
+    # @api private
+    # @param [String] email account email to be queried
+    # @return [JSON] account info
+    def get_user_by_email(email)
+      invoke_gitkit_api('getAccountInfo', {'email' => [email]})
+    end
+
+    # GetAccountInfo by id
+    #
+    # @api private
+    # @param [String] id account id to be queried
+    # @return [JSON] account info
+    def get_user_by_id(id)
+      invoke_gitkit_api('getAccountInfo', {'localId' => [id]})
+    end
+
+    # Get out-of-band code for ResetPassword/ChangeEmail etc. operation
+    #
+    # @api private
+    # @param [Hash<String, String>] request the oob request
+    # @return <String> the oob code
+    def get_oob_code(request)
+      response = invoke_gitkit_api('getOobConfirmationCode', request)
+      response.fetch('oobCode', nil)
+    end
+
+    # Download all accounts
+    #
+    # @api private
+    # @param [String] next_page_token pagination token for next page
+    # @param [Fixnum] max_results pagination size
+    # @return [Array<JSON>] user account info
+    def download_account(next_page_token, max_results)
+      param = {}
+      if next_page_token
+        param['nextPageToken'] = next_page_token
+      end
+      if max_results
+        param['maxResults'] = max_results
+      end
+      response = invoke_gitkit_api('downloadAccount', param)
+      return response.fetch('nextPageToken', nil), response.fetch('users', {})
+    end
+
+    # Delete an account
+    #
+    # @api private
+    # @param <String> local_id user id to be deleted
+    def delete_account(local_id)
+      invoke_gitkit_api('deleteAccount', {'localId' => local_id})
+    end
+
+    # Upload batch accounts
+    #
+    # @api private
+    # @param <String> hash_algorithm hash algorithm
+    # @param <String> hash_key hash key
+    # @param <Array<GitkitUser>> accounts account to be uploaded
+    def upload_account(hash_algorithm, hash_key, accounts)
+      param = {
+          'hashAlgorithm' => hash_algorithm,
+          'signerKey' => hash_key,
+          'users' => accounts
+      }
+      invoke_gitkit_api('uploadAccount', param)
+    end
+
+    # Creates a signed jwt assertion
+    #
+    # @api private
+    # @return [String] jwt assertion
+    def sign_assertion
+      now = Time.new
+      assertion = {
+          'iss' => @service_account_email,
+          'scope' => GITKIT_SCOPE,
+          'aud' => @google_api_url,
+          'exp' => (now + @token_duration).to_i,
+          'iat' => now.to_i
+      }
+      JWT.encode(assertion, @service_account_key, 'RS256')
+    end
+
+    # Get an access token, from Google server if cached one is expired
+    #
+    # @api private
+    def fetch_access_token
+      if is_token_expired
+        assertion = sign_assertion
+        post_body = {
+            'assertion' => assertion,
+            'grant_type' => 'urn:ietf:params:oauth:grant-type:jwt-bearer'}
+        headers = {'Content-type' => 'application/x-www-form-urlencoded'}
+        response = @connection.post(RpcHelper::TOKEN_ENDPOINT, post_body,
+            headers)
+        @access_token = JSON.parse(response.env[:body])['access_token']
+        @token_issued_at = Time.new.to_i
+      end
+      @access_token
+    end
+
+    # Check whether the cached access token is expired
+    #
+    # @api private
+    # @return <Boolean> whether the access token is expired
+    def is_token_expired
+      @access_token == nil ||
+          Time.new.to_i > @token_issued_at + @token_duration - 30
+    end
+
+    # Invoke Gitkit API, with optional access token for service account
+    # operations
+    #
+    # @api private
+    # @param [String] method Gitkit API method name
+    # @param [Hash<String, String>] params api request params
+    # @param [bool] need_service_account whether the request needs to be
+    # authenticated
+    # @return <JSON> the Gitkit api response
+    def invoke_gitkit_api(method, params, need_service_account=true)
+      post_body = JSON.generate(params)
+      headers = {'Content-type' => 'application/json'}
+      if need_service_account
+        @connection.authorization :Bearer, fetch_access_token
+      end
+      response = @connection.post(GITKIT_API_URL + method, post_body, headers)
+      check_gitkit_error JSON.parse(response.env[:body])
+    end
+
+    # Download the Gitkit public certs
+    #
+    # @api private
+    # @return <JSON> the public certs
+    def get_gitkit_certs
+      if @server_api_key.nil?
+        @connection.authorization :Bearer, fetch_access_token
+        response = @connection.get(GITKIT_API_URL + 'publicKeys')
+      else
+        response = @connection.get [GITKIT_API_URL, 'publicKeys?key=',
+            @server_api_key].join
+      end
+      MultiJson.load response.body
+    end
+
+    # Checks the Gitkit response
+    #
+    # @api private
+    # @param [JSON] response the response received
+    # @return [JSON] the response if no error
+    def check_gitkit_error(response)
+      if response.has_key? 'error'
+        error = response['error']
+        if error.has_key? 'code'
+          code = error['code']
+          raise GitkitClientError, error['message'] if code.to_s.match(/^4/)
+          raise GitkitServerError, error['message']
+        else
+          raise GitkitServerError, 'null error code from Gitkit server'
+        end
+      else
+        response
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,130 @@
+--- !ruby/object:Gem::Specification 
+name: gitkit-ruby-client
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: 
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Jin Liu
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2014-05-15 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: addressable
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 2
+        - 3
+        - 2
+        version: 2.3.2
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: faraday
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 59
+        segments: 
+        - 0
+        - 9
+        - 0
+        version: 0.9.0
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: multi_json
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 1
+        - 0
+        - 0
+        version: 1.0.0
+  type: :runtime
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: jwt
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        hash: 13
+        segments: 
+        - 0
+        - 1
+        - 11
+        version: 0.1.11
+  type: :runtime
+  version_requirements: *id004
+description: Google Identity Toolkit Ruby client library
+email: 
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- lib/gitkit_client.rb
+- lib/rpc_helper.rb
+- README.rdoc
+homepage: https://developers.google.com/identity-toolkit/v3
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.15
+signing_key: 
+specification_version: 4
+summary: Google Identity Toolkit Ruby client
+test_files: []
+