{"_id":"576c33ed74a8640e004cee01","category":{"_id":"56be3389be55991700c3ca11","__v":2,"pages":["56be338abe55991700c3ca13","56be34fa37d84017009de5f7"],"project":"56be3387be55991700c3ca0d","version":"56be3388be55991700c3ca10","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-02-12T19:33:29.389Z","from_sync":false,"order":2,"slug":"documentation","title":"Documentation"},"user":"5633ec9b35355017003ca3f2","version":{"_id":"56be3388be55991700c3ca10","project":"56be3387be55991700c3ca0d","__v":8,"createdAt":"2016-02-12T19:33:28.313Z","releaseDate":"2016-02-12T19:33:28.313Z","categories":["56be3389be55991700c3ca11","57646709b0a8be1900fcd0d8","5764671c89da831700590782","57646d30c176520e00ea8fe5","5764715d4f867c0e002bc8e3","57698fa2e93bfd190028815c","576c2af16c24681700c902da","5787da96b008c91900aae865"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"parentDoc":null,"__v":2,"project":"56be3387be55991700c3ca0d","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-06-23T19:09:33.206Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"Websolr features per-request authorization for requests made to your Solr\nindex.  This feature is perfect for anyone who needs to guarantee complete\ncyptographically secure access to their index -- or for anyone who wishes to\nexpose their Solr URL for public read-only access while still protecting\nupdates.\n\nWebsolr advanced authorization is an opt-in feature. Upon enabling this feature\nfor your index you will be issued a secret token (herein called SECRET). This\ntoken is used with the HMAC-SHA1 algorithm as described below.\n\n## Authorization scheme\n\nThe authorization scheme works by including three additional HTTP headers with\neach request to Solr:\n\n### X-Websolr-Time\n\nThe current Unix time -- seconds since epoch. This value helps to guarantee\nuniquness over time, and must be within one minute of our server time to prevent\nreplay attacks.  (Regex: `/[0-9]+/`)\n\n### X-Websolr-Nonce\n\nAny random non-whitespace string. This value further guarantees the uniqueness\nof each generated authorization token. (Regex: `/\\S+/`)\n\n### X-Websolr-Auth\n\nThe hexadecimal HMAC-SHA1 digest of your shared secret and the concatenation of\nthe above **time** and **nonce**.\n\nFor example, in Ruby:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"OpenSSL::HMAC.hexdigest('sha1', SECRET, \\\"#{time}#{nonce}\\\")\",\n      \"language\": \"ruby\"\n    }\n  ]\n}\n[/block]\n\n## Setting your URL\n\nWe recommend setting your URL as an environment variable rather than hardcoding it into the app for security reasons. Heroku users will already have a `WEBSOLR_URL` environment variable set up, and users of other platforms/frameworks should set one up as well. If you're not on Heroku, then something like this should work:\n\n```\n$ export WEBSOLR_URL=\"<the URL for your index>\"\n```\n\nWebsolr uses standard ports for communicating with an index, so we don't explicitly set those in the URL by default. Most clients can infer the correct port based on the protocol. However, some clients will default to port 80 unless instructed otherwise. This can lead to connectivity problems if the app tries to contact the index over port 80 using TLS/SSL. If you have trouble with this, feel free to set the port manually. We're using:\n\n* 443 for HTTPS (TLS/SSL) protocol. This provides end-to-end encryption during data transmission.\n* 80 for HTTP protocol. This is for plaintext data transmission (not recommending if you're following this guide)\n\nSome examples of valid URLs:\n\n```\n# Plaintext:\n$ export WEBSOLR_URL=\"http://index.websolr.com/solr/a1b2c3d4e5f\"\n$ export WEBSOLR_URL=\"http://index.websolr.com:80/solr/a1b2c3d4e5f\"\n\n# Encrypted\n$ export WEBSOLR_URL=\"https://index.websolr.com/solr/a1b2c3d4e5f\"\n$ export WEBSOLR_URL=\"https://index.websolr.com:443/solr/a1b2c3d4e5f\"\n```\n\nSome **invalid** URLs:\n\n```\n$ export WEBSOLR_URL=\"http://index.websolr.com:443/solr/a1b2c3d4e5f\"\n$ export WEBSOLR_URL=\"https://index.websolr.com:80/solr/a1b2c3d4e5f\"\n```\n\n\n## Example with RSolr\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"require 'rsolr'\\nrsolr = RSolr.connect :url => ENV['WEBSOLR_URL']\\n\\ndef auth_headers(secret=ENV['WEBSOLR_AUTH'])\\n  time  = Time.now.to_i\\n  nonce = Time.now.to_i.to_s.split(//).sort_by{rand}.join\\n  auth  = OpenSSL::HMAC.hexdigest('sha1', secret, \\\"#{time}#{nonce}\\\")\\n  {\\n    'X-Websolr-Time'  => time.to_s,\\n    'X-Websolr-Nonce' => nonce,\\n    'X-Websolr-Auth'  => auth\\n  }\\nend\\n\\n# Add a document\\nrsolr.add { :id => 1, :title => \\\"Hello world\\\" }, { :headers => auth_headers }\\n\\n# Commit\\nrsolr.commit :headers => auth_headers\\n\\n# Search\\nrsolr.get 'select', :params => { :q => \\\"hello\\\" }, :headers => auth_headers\",\n      \"language\": \"ruby\"\n    }\n  ]\n}\n[/block]","excerpt":"Learn about how we do advanced authentication at Websolr.","slug":"advanced-auth","type":"basic","title":"Advanced Auth"}

Advanced Auth

Learn about how we do advanced authentication at Websolr.

Websolr features per-request authorization for requests made to your Solr index. This feature is perfect for anyone who needs to guarantee complete cyptographically secure access to their index -- or for anyone who wishes to expose their Solr URL for public read-only access while still protecting updates. Websolr advanced authorization is an opt-in feature. Upon enabling this feature for your index you will be issued a secret token (herein called SECRET). This token is used with the HMAC-SHA1 algorithm as described below. ## Authorization scheme The authorization scheme works by including three additional HTTP headers with each request to Solr: ### X-Websolr-Time The current Unix time -- seconds since epoch. This value helps to guarantee uniquness over time, and must be within one minute of our server time to prevent replay attacks. (Regex: `/[0-9]+/`) ### X-Websolr-Nonce Any random non-whitespace string. This value further guarantees the uniqueness of each generated authorization token. (Regex: `/\S+/`) ### X-Websolr-Auth The hexadecimal HMAC-SHA1 digest of your shared secret and the concatenation of the above **time** and **nonce**. For example, in Ruby: [block:code] { "codes": [ { "code": "OpenSSL::HMAC.hexdigest('sha1', SECRET, \"#{time}#{nonce}\")", "language": "ruby" } ] } [/block] ## Setting your URL We recommend setting your URL as an environment variable rather than hardcoding it into the app for security reasons. Heroku users will already have a `WEBSOLR_URL` environment variable set up, and users of other platforms/frameworks should set one up as well. If you're not on Heroku, then something like this should work: ``` $ export WEBSOLR_URL="<the URL for your index>" ``` Websolr uses standard ports for communicating with an index, so we don't explicitly set those in the URL by default. Most clients can infer the correct port based on the protocol. However, some clients will default to port 80 unless instructed otherwise. This can lead to connectivity problems if the app tries to contact the index over port 80 using TLS/SSL. If you have trouble with this, feel free to set the port manually. We're using: * 443 for HTTPS (TLS/SSL) protocol. This provides end-to-end encryption during data transmission. * 80 for HTTP protocol. This is for plaintext data transmission (not recommending if you're following this guide) Some examples of valid URLs: ``` # Plaintext: $ export WEBSOLR_URL="http://index.websolr.com/solr/a1b2c3d4e5f" $ export WEBSOLR_URL="http://index.websolr.com:80/solr/a1b2c3d4e5f" # Encrypted $ export WEBSOLR_URL="https://index.websolr.com/solr/a1b2c3d4e5f" $ export WEBSOLR_URL="https://index.websolr.com:443/solr/a1b2c3d4e5f" ``` Some **invalid** URLs: ``` $ export WEBSOLR_URL="http://index.websolr.com:443/solr/a1b2c3d4e5f" $ export WEBSOLR_URL="https://index.websolr.com:80/solr/a1b2c3d4e5f" ``` ## Example with RSolr [block:code] { "codes": [ { "code": "require 'rsolr'\nrsolr = RSolr.connect :url => ENV['WEBSOLR_URL']\n\ndef auth_headers(secret=ENV['WEBSOLR_AUTH'])\n time = Time.now.to_i\n nonce = Time.now.to_i.to_s.split(//).sort_by{rand}.join\n auth = OpenSSL::HMAC.hexdigest('sha1', secret, \"#{time}#{nonce}\")\n {\n 'X-Websolr-Time' => time.to_s,\n 'X-Websolr-Nonce' => nonce,\n 'X-Websolr-Auth' => auth\n }\nend\n\n# Add a document\nrsolr.add { :id => 1, :title => \"Hello world\" }, { :headers => auth_headers }\n\n# Commit\nrsolr.commit :headers => auth_headers\n\n# Search\nrsolr.get 'select', :params => { :q => \"hello\" }, :headers => auth_headers", "language": "ruby" } ] } [/block]