azure-directory 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d32a18884bf87b55f5efa53ac89c5ef4ad4ee986
+  data.tar.gz: 8e9aebe9a99a520b4ee6482afc67d63bc0d6d247
+SHA512:
+  metadata.gz: f0b24aad5bc930941a09fdb4ea7d83648cffc6773d5394a4183a1c2d536cb0ef81cd3ac89a1c700b587fdc2dac458b104a89572c015cba597954e1a8d4886538
+  data.tar.gz: 855f22fc5e04d932497dff20d94f1b2a4148e04f07810007799fc86ce2770fa21273024a911a47385357179dd6630f882e2c02ad8db1a25fffba7675f613faf1

data/.gitignore

@@ -0,0 +1,16 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+._*
+.DS_Store
+mkmf.log

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in azure-directory.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Omac
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,93 @@
+# Azure Active Directory Graph API
+
+## Description
+
+Simple Azure Active Directory Graph API wrapper for Ruby on Rails. 
+
+The API authentication protocol is a service to service call using OAuth2 client credentials. For more information go to
+[Azure Documentation](https://msdn.microsoft.com/en-us/library/azure/dn645543.aspx).
+
+* This library is in alpha. Future incompatible changes may be necessary. *
+
+## Install
+
+Add the gem to the Gemfile
+
+```ruby
+gem 'azure-directory'
+```
+
+## Configuration
+
+First configure your API client in `config/initializers/azure_directory.rb`
+
+``` ruby
+Azure::Directory.configure do
+	
+	# OPTIONAL. Use a YAML file to store the requested access tokens. When the token is refreshed, this file will be updated.
+	use_yaml Rails.root.join('config', 'google_directory.yaml')
+
+	# Required attributes
+	client_id       ''
+	client_secret   ''
+	tenant_id       ''
+	resource_id     ''
+
+end
+```
+
+### Multiple API clients using scopes
+
+Specify a single or multiple scopes in the configuration file. 
+
+``` ruby
+Azure::Directory.configure do
+	
+	scope :domain_one do
+		client_id       ''
+		client_secret   ''
+		# [...]
+	end
+
+	scope :domain_two do
+		client_id       ''
+		client_secret   ''
+		# [...]
+	end
+
+end
+```
+
+## Usage
+
+``` ruby
+azure = Azure::Directory::Client.new
+
+azure.find_users
+
+azure.create_user("email", "given_name", "family_name", "password")
+
+azure.update_user("email", update_data)
+
+azure.update_user_password("email", "new_password")
+
+```
+
+### Multiple Scopes
+
+``` ruby
+domain_one = Azure::Directory::Client.new(:domain_one)
+domain_one.find_users
+
+domain_two = Azure::Directory::Client.new(:domain_two)
+domain_two.find_users
+```
+
+## TO DO
+
+* `use_active_model` for database token store
+* Build the configuration generator
+* Implement the Azure's REST API calls
+* Abstract the API's Entities into ruby models [Entity Reference](https://msdn.microsoft.com/en-us/library/azure/dn151470.aspx)
+* Better error handling
+* Testing

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/azure-directory.gemspec

@@ -0,0 +1,29 @@
+$:.push File.expand_path("../lib", __FILE__)
+
+require 'azure/directory/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "azure-directory"
+  spec.version       = Azure::Directory::VERSION
+  spec.authors       = ["Omar Osorio"]
+  spec.email         = ["omar@kioru.com"]
+  spec.homepage      = "https://github.com/kiomac/azure-directory"
+
+  spec.summary       = "Azure Active Directory Graph API client for Ruby on Rails"
+  spec.description   = "Setup your Rails application with one or multiple clients for Azure AD Graph API using OAuth2 service-to-service calls."
+  
+  spec.rdoc_options = ["--main", "README.md"]
+
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency 'oauth2', '~> 1.0'
+
+  spec.add_development_dependency 'rails', '~> 4.2'
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency 'yard', '~> 0.8'
+end

data/lib/azure/directory.rb

@@ -0,0 +1,242 @@
+require 'azure/directory/version'
+require 'azure/directory/config'
+require 'oauth2'
+
+module Azure
+	module Directory
+		
+		GRAPH_API_VERSION = '1.5'
+
+		class Client
+
+			attr_reader :oauth, :oauth_token, :config
+
+			##
+			# @param [Symbol] scope (:main) The scope to use with this client.
+			#
+			def initialize(scope = :main)
+				@config = Azure::Directory.configuration
+				@config = @config.using(scope) if @config.scope_name != scope
+
+				@oauth = OAuth2::Client.new( @config.client_id, @config.client_secret, 
+					                         :site => 'https://login.windows.net/', 
+					                         :authorize_url =>  "/#{@config.tenant_id}/oauth2/authorize", 
+					                         :token_url => "/#{@config.tenant_id}/oauth2/token" )
+
+				
+				if token_hash = @config.load_token
+					@oauth_token = OAuth2::AccessToken.from_hash(@oauth, token_hash)
+
+				else
+					fetch_access_token!
+				end
+				
+			end
+
+
+			##
+			# Do the service-to-service access token request and 
+			# save it to the Token Store defined in the configuration.
+			#
+			# @return [OAuth2::AccessToken] a access token for the current session.
+			#
+			def fetch_access_token!
+				@oauth_token = oauth.get_token( :client_id => config.client_id, 
+					                            :client_secret => config.client_secret, 
+					                            :grant_type => 'client_credentials', 
+					                            :response_type => 'client_credentials', 
+					                            :resource => config.resource_id )
+
+				token_hash = { 'access_token' => oauth_token.token, 'token_type' => oauth_token.params['token_type'], 'expires_at' => oauth_token.expires_at }
+				config.save_token(token_hash)
+				oauth_token
+			end
+
+
+			##
+			# Get all users from the active directory
+			#
+			# @return [Array]
+			#
+			# @see https://msdn.microsoft.com/en-us/library/azure/hh974483.aspx User
+			def find_users(params = nil)
+				users = get('/users', params)
+				users['value'] if users.is_a?(Hash)
+			end
+
+
+
+			##
+			# Get user by email
+			#
+			# @return [Hash] The user's information or nil if not found
+			#
+			# @see https://msdn.microsoft.com/en-us/library/azure/hh974483.aspx User
+			def find_user_by_email(email, params = nil)
+				get("/users/#{email}", params)
+			end
+
+
+
+			## 
+			# Creates a unique user on the Active Directory
+			#
+			# @param [String] email User unique email inside the AD Domain.
+			# @param [String] given_name 
+			# @param [String] family_name
+			# @param [String] password The password will set up with `forceChangePasswordNextLogin = true`by default.
+			# @param [Hash] params If you wish to add or override specific parameters from the Graph API.
+			# 
+			# @option params [Boolean] 'accountEnabled' (true)
+			# @option params [String] 'displayName' Will concatenate given_name and family_name
+			# @option params [String] 'mailNickname' Username extracted from the email.
+			# @option params [String] 'passwordProfile' { "password" => password, "forceChangePasswordNextLogin" => true }
+			# @option params [String] 'userPrincipalName' email
+			# @option params [String] 'givenName' given_name
+			# @option params [String] 'surname' family_name
+			# @option params [String] 'usageLocation' 'US'
+			#
+			# @return [Hash] The user's information or nil if unsuccessful 
+			#
+			# @see https://msdn.microsoft.com/en-us/library/azure/hh974483.aspx User
+			#
+			def create_user(email, given_name, family_name, password, params = {})
+				params = { 'accountEnabled'    => true,
+				           'displayName'       => "#{given_name} #{family_name}",
+				           'mailNickname'      => email.split('@').first,
+				           'passwordProfile'   => { "password" => password, "forceChangePasswordNextLogin" => true },
+				           'userPrincipalName' => email,
+				           'givenName'         => given_name,
+				           'surname'           => family_name,
+				           'usageLocation'     => 'US'
+				}.merge(params)
+
+				post('users', params)
+			end
+
+
+
+			##
+			# Updates the current user with specified parameters
+			#
+			# @param [String] params See the create_user method's params
+			#
+			# @return [Boolean] True if update was successful
+			#
+			def update_user(email, params = nil)
+				patch("users/#{email}", params) == :no_content
+			end
+
+
+
+			##
+			# Updates the user's password
+			#
+			# @param [String] email
+			# @param [String] password A valid password
+			# @param [String] force_change_password_next_login True by default
+			#
+			# @return [Hash] The user's information or nil if unsuccessful
+			#
+			def update_user_password(email, password, force_change_password_next_login = true)
+				params = { 'passwordProfile' => { 
+					           'password' => password, 
+					           'forceChangePasswordNextLogin' => force_change_password_next_login } }
+
+				patch("users/#{email}", params) == :no_content
+			end
+
+
+			##
+			# Obtain the SubscribedSkus.
+			#
+			def get_subscribed_skus
+				get('subscribedSkus')
+			end
+
+
+			##
+			# Assignment of subscriptions for provisioned user account.
+			#
+			# @param [String] sku_part_number Using this name we get the skuId to do the proper assignment. 
+			#
+			# @example
+			#   assign_license('username@domain.com', 'STANDARDWOFFPACK_STUDENT')
+			#
+			def assign_license(email, sku_part_number)
+				skus = get('subscribedSkus')['value']
+				return nil unless sku = skus.detect{ |_sku| _sku['skuPartNumber'] == sku_part_number }
+				
+				post("users/#{email}/assignLicense", { "addLicenses" => [ {"disabledPlans" => [], "skuId" => sku['skuId'] }], "removeLicenses" => [] })
+			end
+
+
+			##
+			# Deletes an existing user by email
+			#
+			# @param [String] email User email
+			#
+			# @return [Boolean] True if the user was deleted
+			#
+			def delete_user(email)
+				delete("users/#{email}") == :no_content
+			end
+
+
+
+			private 
+
+				def get(path, params = nil)
+					request(:get, path, params)
+				end
+
+				def post(path, params)
+					request(:post, path, nil, params)
+				end
+
+				def patch(path, params)
+					request(:patch, path, nil, params)
+				end
+
+				def delete(path)
+					request(:delete, path)
+				end
+
+				def request(method, path, params = nil, body = nil)
+					fetch_access_token! if oauth_token.expired?
+
+					response = oauth_token.request(method, graph_url(path), build_params(params, body).merge(:raise_errors => false) )
+					if response.error
+						unless (error = response.parsed).is_a?(Hash) and error['odata.error']['code'] == 'Request_ResourceNotFound'
+							Rails.logger.error("OAuth2 Error (#{response.status}): #{response.parsed}" )
+						end
+						return nil 
+					end
+					
+					case response.status
+					when 200, 201 then return response.parsed
+					when 204 then return :no_content
+					end
+
+					response
+
+				end
+
+
+				def graph_url(path)
+					"https://graph.windows.net/#{config.tenant_id}/#{path}"
+				end
+
+				def build_params(params = nil, body = nil)
+					params ||= {}
+					body = body.to_json if body and body.class.method_defined?(:to_json)
+
+					{ :params => params.merge!( 'api-version' => GRAPH_API_VERSION ),
+					  :body => body,
+					  :headers => {'Content-Type' => 'application/json'} }
+				end
+		end
+
+
+	end
+end

data/lib/azure/directory/config.rb

@@ -0,0 +1,148 @@
+require 'yaml'
+
+module Azure
+
+	module Directory
+	
+		class MissingConfiguration < StandardError
+			def initialize
+				super('No configuration found for Azure Directory')
+			end
+		end
+
+		def self.configure(&block)
+			@config = Config::Builder.new(&block).build
+		end
+
+		def self.configuration
+			@config || (fail MissingConfiguration.new)
+		end
+
+
+
+		class Config
+
+			attr_reader :scope_name, :client_id, :client_secret, :tenant_id, :resource_id
+
+			def initialize(scope_name = :main)
+				@scope_name = scope_name
+			end
+
+			def using(scope)
+				@scopes[scope]
+			end
+
+
+			def save_token(token_hash)
+				token_hash = token_hash.slice('access_token', 'token_type', 'expires_at')
+				@token_store and @token_store.save(@scope_name, token_hash)
+			end
+
+			def load_token
+				@token_store and @token_store.load(@scope_name)
+			end
+
+
+			class Builder
+				
+				def initialize(&block)
+					@config = @current_config = Config.new
+					@config.instance_variable_set('@scopes', { })
+					instance_eval(&block)
+				end
+
+				def build
+					@config
+				end
+
+				##
+				# Use a YAML file to store the requested access tokens. When the token is refreshed, this file will be updated.
+				# You must declare this configuration attribute before any scope.
+				#
+				# @param [String] The YAML file path (keep this file secure).
+				#
+				def use_yaml( yaml_file )
+					
+					File.exist?(yaml_file) || FileUtils.touch(yaml_file)
+					@token_store = YamlTokenStore.new( yaml_file )
+					@current_config.instance_variable_set('@token_store', @token_store)
+
+				end
+
+				##
+				# OAuth: Application Client ID
+				#
+				def client_id( client_id )
+					@current_config.instance_variable_set('@client_id', client_id)
+				end
+
+				##
+				# OAuth: Application Client Secret
+				#
+				def client_secret( client_secret )
+					@current_config.instance_variable_set('@client_secret', client_secret)
+				end
+
+				##
+				# OAuth: Azure's Tenant ID.
+				#
+				# @param [String] tenant_id Tenant identifier (ID) of the Azure AD tenant that issued the token.
+				#
+				def tenant_id( tenant_id )
+					@current_config.instance_variable_set('@tenant_id', tenant_id)
+				end
+
+				##
+				# Required Resource Access
+				#
+				# @param [String] Get the resourceAppId from the manifest of your application added to the Active Directory.
+				#
+				def resource_id( resource_id )
+					@current_config.instance_variable_set('@resource_id', resource_id)
+				end
+
+				##
+				# Set a new configuration for a specific scope, in order to support multiple connections to different applications.
+				# Provide a block with the configuration parameters.
+				#
+				# @param [Symbol] scope_name Scope name
+				#
+				def scope( scope_name, &block )
+					scopes = @config.instance_variable_get('@scopes')
+					scopes[scope_name] = @current_config = Config.new(scope_name)
+
+					@current_config.instance_variable_set('@token_store', @token_store)
+
+					instance_eval(&block)
+					@current_config = @config
+				end
+
+			end
+
+		end
+
+
+		class YamlTokenStore
+
+			def initialize(yaml_file)
+				@yaml_file = yaml_file
+				@yaml_data = YAML::load( yaml_file.open )
+				@yaml_data = {} unless @yaml_data.is_a?(Hash)
+			end
+
+			def save( scope_name, token_hash )
+				data = (@yaml_data[Rails.env.to_s] ||= {})
+				data[scope_name.to_s] = token_hash
+				File.open(@yaml_file, 'w') { |file| file.write( YAML::dump(@yaml_data) ) }
+			end
+
+			def load( scope_name )
+				data = @yaml_data[Rails.env.to_s] and data = data[scope_name.to_s] and data.slice('access_token', 'token_type', 'expires_at')
+			end
+
+		end
+
+	end
+
+
+end

data/lib/azure/directory/version.rb

@@ -0,0 +1,5 @@
+module Azure
+  module Directory
+    VERSION = "0.0.1"
+  end
+end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification
+name: azure-directory
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Omar Osorio
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-04-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: oauth2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+description: Setup your Rails application with one or multiple clients for Azure AD
+  Graph API using OAuth2 service-to-service calls.
+email:
+- omar@kioru.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- azure-directory.gemspec
+- lib/azure/directory.rb
+- lib/azure/directory/config.rb
+- lib/azure/directory/version.rb
+homepage: https://github.com/kiomac/azure-directory
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--main"
+- README.md
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Azure Active Directory Graph API client for Ruby on Rails
+test_files: []
+has_rdoc: