stormpath-sdk 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 30a7563696f87d582d6d3f31cc26613ba7730aeb
-  data.tar.gz: 3587598dc7a6959997b14379b6b291fa9a9eac5b
+  metadata.gz: 1d31ad099a140c12a0522f4bca201aebb81838e4
+  data.tar.gz: b1de03018cc6bf723c873dd3c8368cdb197d3ac8
 SHA512:
-  metadata.gz: 080f49f98c6119fe238f9d1e8bb48377a3c1fb14d28b9e72852c571d642c73d6383e7a52efd1c792f25bea88bc8e951704d371ba755488fee2167a1b819fed9e
-  data.tar.gz: 07b8ddd35409fd0ba95a01838e9f8889f40015ff13995e0495561154079e96d50ea771ad0468a9d94c605ebfc55c002c0174e14d96d9b63337e25617bb866afd
+  metadata.gz: a4829ff4c1ac11afff95f83ae2f7adda7ca796bd13369a45635496607da558b6c10e3ca6f8e0e4ec38e7930a3d62b796aad461e157de216381644f3705a60c44
+  data.tar.gz: a437e1bf41aa13588ae014d9dcc9f3730537e31558b2e1b268ca92052098f747228d7f634714b6c9d766e04996cc89a202dade529d6fe9c11d254d0e483dcd56

data/.travis.yml

@@ -1,8 +1,8 @@
 language: ruby
 rvm:
-- 1.9.3
-- 2.0.0
-- 2.1.2
+- 2.1.5
+- 2.2.4
+- 2.3.0
 services:
 - redis-server
 before_install:

data/CHANGES.md

@@ -1,6 +1,17 @@
 stormpath-sdk-ruby Changelog
 ============================
 
+Version 1.1.0
+-------------
+
+Released on May 11, 2016
+
+- Saml integration
+- Support for specifying an organization name_key on login attempts
+- Support for specifying the account store when reseting passwords
+- Add delegate to organizations
+- Add Organization docs to README
+
 Version 1.0.1
 -------------
 

data/README.md

@@ -304,7 +304,7 @@ application.create_id_site_url({
 });
 ```
 
-##### Using Subdomains 
+##### Using Subdomains
 
 In some cases, you may want to show the organization that the user is logging into as a subdomain instead of an form field. To configure this, you need to use a [wildcard certificate][wildcard-certificate] when setting up your [custom domain with ID Site][custom-domain-with-id-site]. Otherwise, the Stormpath infrastructure will cause browser SSL errors.
 
@@ -379,8 +379,8 @@ Again, with all these methods, You will want your application to link to an inte
 > A JWT will expire after 60 seconds of creation.
 
 #### Exchange ID Site token for a Stormpath Access Token
-After the user has been authenticated via ID Site, a developer may want to control their authorization with an OAuth 2.0 Token. 
-This is done by passing the JWT similar to the way we passed the user’s credentials as described in [Generating an OAuth 2.0 Access Token][generate-oauth-access-token]. 
+After the user has been authenticated via ID Site, a developer may want to control their authorization with an OAuth 2.0 Token.
+This is done by passing the JWT similar to the way we passed the user’s credentials as described in [Generating an OAuth 2.0 Access Token][generate-oauth-access-token].
 The difference is that instead of using the password grant type and passing credentials, we will use the id_site_token type and pass the JWT we got from the ID Site
 more info [here][exchange-id-site-token].
 
@@ -486,6 +486,204 @@ rescue Stormpath::Error => e
 end
 ```
 
+The `UsernamePasswordRequest` can take an optional link to the application’s accountStore (directory or group) or the Organization nameKey. Specifying this attribute can speed up logins if you know exactly which of the application’s assigned account stores contains the account: Stormpath will not have to iterate over the assigned account stores to find the account to authenticate it. This can speed up logins significantly if you have many account stores (> 15) assigned to the application.
+
+The `UsernamePasswordRequest` can receive the AccountStore in three ways.
+
+Passing the organization, directory or group instance:
+
+```ruby
+auth_request =
+  Stormpath::Authentication::UsernamePasswordRequest.new 'johnsmith', '4P@$$w0rd!', account_store: organization
+```
+
+Passing the organization, directory or group href:
+
+```ruby
+auth_request =
+  Stormpath::Authentication::UsernamePasswordRequest.new 'johnsmith', '4P@$$w0rd!', account_store: { href: organization.href }
+```
+
+Passing the organization name_key:
+
+```ruby
+auth_request =
+  Stormpath::Authentication::UsernamePasswordRequest.new 'johnsmith', '4P@$$w0rd!', account_store: { name_key: organization.name_key }
+```
+
+### Authentication Against a SAML Directory
+
+SAML is an XML-based standard for exchanging authentication and authorization data between security domains.
+Stormpath enables you to allow customers to log-in by authenticating with an external SAML Identity Provider.
+
+#### Stormpath as a Service Provider
+
+The specific use case that Stormpath supports is user-initiated single sign-on. In this scenario, a user requests
+a protected resource (e.g. your application). Your application, with the help of Stormpath, then confirms the users
+identity in order to determine whether they are able to access the resource. In SAML terminology, the user is the User
+Agent, your application (along with Stormpath) is the Service Provider, and the third-party SAML authentication site
+is the Identity Provider or IdP.
+
+The broad strokes of the process are as follows:
+
+* User Agent requests access from Service Provider
+* Service Provider responds with redirect to Identity Provider
+* Identity Provider authenticates the user
+* Identity provider redirects user back to Service Provider along with SAML assertions.
+* Service Provider receives SAML assertions and either creates or retrieves Account information
+
+#### Configuring Stormpath as a Service Provider
+
+Configuration is stored in the Directory's Provider resource. Here we will explain to you the steps that are required to configure Stormpath as a SAML Service
+Provider.
+
+#### Step 1: Gather IDP Data
+
+You will need the following information from your IdP:
+
+- **SSO Login URL** - The URL at the IdP to which SAML authentication requests should be sent. This is often called an "SSO URL", "Login URL" or "Sign-in URL".
+- **SSO Logout URL** - The URL at the IdP to which SAML logout requests should be sent. This is often called a "Logout URL", "Global Logout URL" or "Single Logout URL".
+- **Signing Cert** - The IdP will digitally sign auth assertions and Stormpath will need to validate the signature. This will usually be in .pem or .crt format, but Stormpath requires the text value.
+- **Signing Algorithm** - You will need the name of the signing algorithm that your IdP uses. It will be either "RSA-SHA256" or "RSA-SHA1".
+
+#### Step 2: Configure Your SAML Directory
+
+Input the data you gathered in Step 1 above into your Directory's Provider resource, and then pass that along as part of the Directory creation HTTP POST:
+
+```ruby
+provider = "saml"
+request = Stormpath::Provider::AccountRequest.new(provider, :access_token, access_token)
+application.get_provider_account(request)
+
+client.directories.create(
+  name: "infinum_directory",
+  description: "random description",
+  provider: {
+    provider_id: "saml"
+  }
+)
+```
+
+to get the data about the provider just type
+```ruby
+directory.provider
+```
+
+provider method returns instance of SamlProvider and you can access the following data
+
+```ruby
+dir_provider = directory.provider
+
+dir_provider.provider_id
+dir_provider.sso_login_url
+dir_provider.sso_logout_url
+dir_provider.encoded_x509_signing_cert
+dir_provider.request_signature_algorithm
+dir_provider.service_provider_metadata
+dir_provider.attribute_statement_mapping_rules
+dir_provider.creted_at
+dir_provider.modified_at
+```
+
+##### Retrieve Your Service Provider Metadata
+
+Next you will have to configure your Stormpath-powered application as a Service Provider in your Identity Provider. This means that you will need to retrieve the correct metadata from Stormpath.
+
+In order to retrieve the required values, start by sending a GET to the Directory's Provider:
+
+```ruby
+directory.provider_metadata
+```
+
+provider_metadata method returns instance of SamlProviderMetadata and you can access the following values
+
+```ruby
+dir_provider_metadata = directory.provider_metadata
+
+dir_provider_metadata.href
+dir_provider_metadata.entity_id
+dir_provider_metadata.x509_signing_cert
+dir_provider_metadata.assertion_consumer_service_post_endpoint
+dir_provider_metadata.created_at
+dir_provider_metadata.modified_at
+```
+
+From this metadata, you will need two values:
+
+- **Assertion Consumer Service URL**: This is the location the IdP will send its response to.
+- **X509 Signing Certificate**: The certificate that is used to sign the requests sent to the IdP. If you retrieve XML, the certificate will be embedded. If you retrieve JSON, you'll have to follow a further /x509certificates link to retrieve it.
+
+You will also need two other values, which will always be the same:
+
+- **SAML Request Binding**: Set to HTTP-Redirect.
+- **SAML Response Binding**: Set to HTTP-Post.
+
+#### Step 4: Configure Your Service Provider in Your Identity Provider
+
+Log-in to your Identity Provider (Salesforce, OneLogin, etc) and enter the information you retrieved in
+the previous step into the relevant application configuration fields. The specific steps to follow here
+will depend entirely on what Identity Provider you use, and for more information you should consult your
+Identity Provider's SAML documentation.
+
+#### Step 5: Configure Your Application
+
+The Stormpath `Application` Resource has two parts that are relevant to SAML:
+
+- an ``authorizedCallbackUri`` Array that defines the authorized URIs that the IdP can return your user to. These should be URIs that you host yourself.
+- an embedded ``samlPolicy`` object that contains information about the SAML flow configuration and endpoints.
+
+```ruby
+application.authorized_callback_uris = ["https://myapplication.com/whatever/callback", "https://myapplication.com/whatever/callback2"]
+application.save
+```
+
+#### Step 6: Add the SAML Directory as an Account Store
+
+The next step is to map the new Directory to your Application with an Account Store Mapping.
+
+##### Step 7: Configure SAML Assertion Mapping
+
+The Identity Provider's SAML response contains assertions about the user's identity, which Stormpath can use to create and populate a new Account resource.
+
+```xml
+  <saml:AttributeStatement>
+    <saml:Attribute Name="uid" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
+      <saml:AttributeValue xsi:type="xs:string">test</saml:AttributeValue>
+    </saml:Attribute>
+    <saml:Attribute Name="mail" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
+      <saml:AttributeValue xsi:type="xs:string">jane@example.com</saml:AttributeValue>
+    </saml:Attribute>
+      <saml:Attribute Name="location" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
+      <saml:AttributeValue xsi:type="xs:string">Tampa, FL</saml:AttributeValue>
+    </saml:Attribute>
+  </saml:AttributeStatement>
+
+```
+The Attribute Assertions (`<saml:AttributeStatement>`) are brought into Stormpath and become Account and customData attributes.
+
+SAML Assertion mapping is defined in an **attributeStatementMappingRules** object found inside the Directory's Provider object, or directly: `/v1/attributeStatementMappingRules/$RULES_ID`.
+
+##### Mapping Rules
+
+The rules have three different components:
+
+- **name**: The SAML Attribute name
+- **nameFormat**: The name format for this SAML Attribute, expressed as a Uniform Resource Name (URN).
+- **accountAttributes**: This is an array of Stormpath Account or customData (`customData.$KEY_NAME`) attributes that will map to this SAML Attribute.
+
+In order to create the mapping rules, we simply send the following:
+
+```ruby
+mappings = Stormpath::Provider::SamlMappingRules.new(items: [
+  {
+    name: "uid",
+    account_attributes: ["username"]
+  }
+])
+
+dir.create_attribute_mappings(mappings)
+```
+
 ### Password Reset
 
 A password reset workflow, if configured on the directory the account is
@@ -576,6 +774,39 @@ Group membership can be created by:
 
 You will need to reload the account or group resource after these
 operations to ensure they've picked up the changes.
+
+### Working with Organizations
+
+An `Organization` is a top-level container for Account Stores. You can think of an Organization as a tenant for your multi-tenant application. This is different than your Stormpath Tenant, which represents your tenant in the Stormpath system. Organizations are powerful because you can group together account stores that represent a tenant.
+
+* Locate an organization
+
+  ```ruby
+    client.organizations.search(name: 'Finance Organization')
+  ```
+
+* Create an organization
+
+  ```ruby
+    client.organizations.create(name: 'Finance Organization', name_key: 'finance-organization')
+  ```
+
+* Adding an account store to an organization
+
+  ```ruby
+    client.organization_account_store_mappings.create(
+      account_store: { href: directory_or_group.href },
+      organization:  { href: organization.href }
+    )
+  ```
+
+* Adding an Organization to an Application as an Account Store
+
+  ```ruby
+    client.account_store_mappings.create application: application, account_store: organization
+  ```
+
+
 ### Add Custom Data to Accounts or Groups
 
 Account and Group resources have predefined fields that are useful to many applications, but you are likely to have your own custom data that you need to associate with an account or group as well.

data/Rakefile

@@ -1,9 +1,11 @@
+require 'bundler/gem_tasks'
 require 'rubygems'
 require 'rubygems/package_task'
 require 'rspec/core/rake_task'
 require 'stormpath-sdk'
 require './support/api'
 
+
 spec = eval(File.read('stormpath-sdk.gemspec'))
 
 Gem::PackageTask.new(spec) do |p|
@@ -27,4 +29,4 @@ namespace :api do
       ENV['STORMPATH_SDK_TEST_DIRECTORY_WITH_VERIFICATION_URL']
     )
   end
-end
+end

data/lib/stormpath-sdk.rb

@@ -87,6 +87,10 @@ module Stormpath
     autoload :LinkedinProviderData, 'stormpath-sdk/provider/linkedin/linkedin_provider_data'
     autoload :GithubProvider, 'stormpath-sdk/provider/github/github_provider'
     autoload :GithubProviderData, 'stormpath-sdk/provider/github/github_provider_data'
+    autoload :SamlProvider, 'stormpath-sdk/provider/saml/saml_provider'
+    autoload :SamlProviderData, 'stormpath-sdk/provider/saml/saml_provider_data'
+    autoload :SamlProviderMetadata, 'stormpath-sdk/provider/saml/saml_provider_metadata'
+    autoload :SamlMappingRules, 'stormpath-sdk/provider/saml/saml_mapping_rules'
     autoload :StormpathProvider, 'stormpath-sdk/provider/stormpath/stormpath_provider'
     autoload :StormpathProviderData, 'stormpath-sdk/provider/stormpath/stormpath_provider_data'
   end

data/lib/stormpath-sdk/auth/basic_login_attempt.rb

@@ -28,6 +28,10 @@ module Stormpath
       def account_store=(account_store)
         if account_store.kind_of? Stormpath::Resource::Base
           set_property ACCOUNT_STORE, {HREF_PROP_NAME => account_store.href}
+        elsif account_store.kind_of? Hash
+          set_property ACCOUNT_STORE, sanitize(account_store)
+        else
+          fail ArgumentError, 'account_store should be a Stormpath::Resource::Instance or a Hash'
         end
       end
 

data/lib/stormpath-sdk/auth/username_password_request.rb

@@ -46,4 +46,3 @@ module Stormpath
     end
   end
 end
-

data/lib/stormpath-sdk/client.rb

@@ -53,7 +53,7 @@ module Stormpath
         data_store.save token, Stormpath::Resource::Account
       end
     end
-    has_many :organizations, href: '/organizations', can: [:get, :create]
+    has_many :organizations, href: '/organizations', can: [:get, :create], delegate: true
     has_many :groups, href: '/groups', can: :get
     has_many :group_memberships, href: '/groupMemberships', can: [:get, :create]
     has_many :account_store_mappings, href: '/accountStoreMappings', can: [:get, :create]

data/lib/stormpath-sdk/data_store.rb

@@ -119,7 +119,7 @@ class Stormpath::DataStore
 
       request = Request.new(http_method, href, query, Hash.new, body, @api_key)
 
-      if resource.try(:form_data?) 
+      if resource.try(:form_data?)
         apply_form_data_request_headers request
       else
         apply_default_request_headers request
@@ -141,7 +141,7 @@ class Stormpath::DataStore
 
       return if http_method == 'delete'
 
-      if result[HREF_PROP_NAME]
+      if result[HREF_PROP_NAME] and !resource_is_saml_mapping_rules? resource
         cache_walk result
       else
         result
@@ -213,7 +213,7 @@ class Stormpath::DataStore
         request.http_headers.store 'Content-Type', 'application/json'
       end
     end
-    
+
     def apply_form_data_request_headers(request)
       request.http_headers.store 'Content-Type', 'application/x-www-form-urlencoded'
       apply_default_user_agent(request)
@@ -277,7 +277,7 @@ class Stormpath::DataStore
       form_data = resource.try(:form_data?)
 
       if form_data
-        form_request_parse(resource) 
+        form_request_parse(resource)
       else
         MultiJson.dump(to_hash(resource))
       end
@@ -285,7 +285,7 @@ class Stormpath::DataStore
 
     def form_request_parse(resource)
       data = ""
-      
+
       property_names = resource.get_dirty_property_names
       property_names.each do |name|
         if name != "formData"
@@ -305,29 +305,37 @@ class Stormpath::DataStore
           property = resource.get_property name, ignore_camelcasing: ignore_camelcasing
 
           # Special use cases are with Custom Data, Provider and ProviderData, their hashes should not be simplified
-          if property.kind_of?(Hash) and !resource_nested_submittable(resource, name)
+          if property.kind_of?(Hash) and !resource_nested_submittable(resource, name) and name != "items"
             property = to_simple_reference name, property
           end
 
+          if name == "items" and resource_is_saml_mapping_rules? resource
+            property = property.map { |item| item.transform_keys { |key| key.to_s.camelize(:lower).to_sym }  }
+          end
+
           properties.store name, property
         end
       end
     end
 
     def to_simple_reference(property_name, hash)
-      assert_true hash.has_key?(HREF_PROP_NAME), "Nested resource '#{property_name}' must have an 'href' property."
+      assert_true hash.key?(HREF_PROP_NAME), "Nested resource '#{property_name}' must have an 'href' property."
 
       href = hash[HREF_PROP_NAME]
 
-      {HREF_PROP_NAME => href}
+      { HREF_PROP_NAME => href }
     end
 
     def resource_nested_submittable resource, name
-      ['provider', 'providerData'].include?(name) or resource_is_custom_data(resource, name)
+      ['provider', 'providerData', 'accountStore'].include?(name) or resource_is_custom_data(resource, name)
     end
 
     def resource_is_custom_data resource, name
       resource.is_a? Stormpath::Resource::CustomData or name == 'customData'
     end
 
+    def resource_is_saml_mapping_rules? resource
+      resource.is_a? Stormpath::Provider::SamlMappingRules
+    end
+
 end