README.md in omniauth-multi-provider-0.1.0 vs README.md in omniauth-multi-provider-0.2.0

@@ -1,14 +1,12 @@
-# OmniAuth::MultiProvider
+# OmniAuth MultiProvider
 
-Welcome to your new gem! In this directory, you'll find the files you need to be
-able to package up your Ruby library into a gem. Put your Ruby code in the file
-`lib/omniauth-multi-provider`. To experiment with that code, run 
-`bin/console` for an interactive prompt.
+This is a simple extension to [omniauth](https://github.com/omniauth/omniauth) for supporting 
+multiple identity provider instances of a given type e.g. multiple SAML or OAuth2
+identity providers. It is a generalization of the 
+[omniauth-multi-provider-saml](https://github.com/salsify/omniauth-multi-provider-saml).
 
-TODO: Delete this and the text above, and describe your gem
-
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -21,12 +19,74 @@
 
 Or install it yourself as:
 
     $ gem install omniauth-multi-provider
 
-## Usage
+## Setup
 
-TODO: Write usage instructions here
+**Getting your setup to work with a single identity provider before attempting to use this gem is highly recommended.** 
+
+The setup process consists of the following steps:
+
+1. Create an OmniAuth callback controller for your identity provider like you normally would with OmniAuth.
+1. Configure your routes to handle routes for multiple identity provider instances.
+1. Configure omniauth-multi-provider to choose the appropriate identity provider instance.
+
+### Configure Routes
+
+Add something like the following to your routes assuming you're using Rails and a SAML identity provider 
+(your actual URL structure may vary):
+
+```ruby
+MyApplication::Application.routes.draw do
+  match '/auth/saml/:identity_provider_id/callback',
+        via: [:get, :post],
+        to: 'omniauth_callbacks#saml',
+        as: 'user_omniauth_callback'
+
+  match '/auth/saml/:identity_provider_id',
+        via: [:get, :post],
+        to: 'omniauth_callbacks#passthru',
+        as: 'user_omniauth_authorize'
+end
+```
+
+### Configure OmniAuth
+
+The basic configuration of OmniAuth looks something like this:
+
+```ruby
+# config/omniauth.rb
+Rails.application.config.middleware.use OmniAuth::Builder do
+  OmniAuth::MultiProvider.register(self,
+                                   provider_name: :saml,
+                                   identity_provider_id_regex: /\d+/,
+                                   path_prefix: '/auth/saml',
+                                   callback_suffix: 'callback',
+                                   # Specify any additional provider specific options
+                                   name_identifier_format: 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress',
+                                   issuer: 'salsify.com',
+                                   allowed_clock_drift: 5.seconds) do |identity_provider_id, rack_env|
+    identity_provider = SAML::IdentityProvider.find(identity_provider_id)
+    # Optionally store a reference to the identity provider in the Rack environment
+    # so you can reference it in your OmniAuth callbacks controller
+    rack_env['salsify.saml_identity_provider'] = identity_provider
+    # Any dynamic options returned by this block will be merged in with any statically
+    # configured options for the identity provider type e.g. issuer in this example.
+    identity_provider.options
+  end
+  
+  # This also works with multiple provider types
+  OmniAuth::MultiProvider.register(self,
+                                   provider_name: :oauth2,
+                                   identity_provider_id_regex: /\d+/,
+                                   path_prefix: '/auth/oauth2') do |identity_provider_id, rack_env|
+    identity_provider = OAuth2::IdentityProvider.find(identity_provider_id)
+    rack_env['salsify.oauth2_identity_provider'] = identity_provider
+    identity_provider.options
+  end
+end
+```
 
 ## Development
 
 After 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