AuthSig
A toolkit for decentralized identification and authorization.
High level explantation
You get an AuthSig verified url and want to see if it is valid.
Visit that link. It says it's valid, so it is valid!
But how did we get that url?
Send a user to http://authsig.herokuapp.com/verify/request?login=user_1. If they are logged in as user_1, they will receive a version of the above, signed url available to them.
The signature part of the url can only be generated by parties that know a special secret code that helped create it. If only AuthSig knows that code, only AuthSig can generate that url. So, when you get a valid AuthSig verified url, you can have some confidence that AuthSig verified that user's identity to its satisfaction.
In practice
Send a user to /verify/request to start verifying their identity. Add components to the query string to adjust how the AuthSig server reacts. For example ...
Quick note ...
Anything you put in the query string will contribute to the signature. You can put anything you want in the request query string and it will be verified by the signature in the verified query string.
The following attributes have special meaning:
login
/verify/request?login=user_1
Which user you want to identify. Required in some form.
service
/verify/request?service=twitter&login=samsm
Which service the login name belongs to. In the above example, it would attempt to login the Twitter user samsm. The default service is "password" (local authentication).
(note, AuthSig doesn't actually support Twitter, Facebook or any other external service right now)
redirect_url
/verify/request?login=user_1&redirect_url=http://example.com
Upon successful identification of user_1, redirects to (in this case) http://example.com.
Normal query string escaping required.
notify_url
/verify/request?login=user_1¬ify_url=http://example.com
Upon successful identification of user_1, POSTs signed verification url to (in this case) http://example.com.
Normal query string escaping required.
hide
/verify/request?login=user_1¬ify_url=http://example.com&hide=true
With any value in hide, the verification url will not be shown to the end user.
In this example, upon successful identification a verification will be sent to http://example.com but not shown to the user_1.
time
/verify/request?login=user_1&time=2013-06-11T19:48:20-04:00
AuthSig will only create a verified url if the time is within the time_fudge. Default fudge is a 5 minute radius (total 10 minute window).
time_fudge
/verify/request?login=user_1&time=2013-06-11T19:48:20-04:00&time_fudge=10
Changes the default tolerance for how far off the requested time is from the AuthSig server time.
secret
/verify/request?login=user_1&secret=foo
Overrides the AuthSig secret. Making this visible in a url is a bad idea. It can be surreptitiously inserted using defaults.
provides
/verify/request?provides=login
AuthSig will attempt to populate attributes listed here. The above request might produce the following verified url:
http://example.com/verify/verified?login=user_1&signature=REDACTED
You can get multiple attributes populated:
/verify/request?provides[]=login&provides[]=time
login, service and time can be populated.
default
Defaults quietly insert previously supplied data into the signature calculation without actually putting that data into the query string.
For example, if there was a default with the slug my-secret and value {secret: "custom-secret"} ...
/verify/request?login=user_1&default[my-secret] would use the secret "custom-secret". It would be equivalent to:
/verify/request?login=user_1&default[my-secret]&secret=my-secret
Rationale
Ease
OAuth and OpenID impose a lot of rules in order to fit the needs of a diverse set of authentication scenarios.
AuthSig does not impose rules, it just provides options that allow for the implementation of a variety of rules. It is easier, because it doesn't demand anything. If you want to only redirect to a particular domain, don't accept AuthSig urls that have redirect_urls with different domains. If you want the signature secretly sent to an address, put that in the request. AuthSig will work with or without these options.
An AuthSig client can be very simple, verifying a url is as easy as visiting that url.
Portability
Verified AuthSig urls represent a person being identified. They are easy enough to make that an end user could initiate the process on their own and cut/paste the url to demonstrate their identity.
http://authsig.herokuapp.com/verify/verified?login=user_1&hi=wearing-a-blue-t-shirt&signature=%242a%2410%24PzwOLCTN.HIT7ubaAyi%2FvuKkIfrOcM23r2Maz%2FyAQfDjEBcNkwMtu
These urls can be emailed, sent through chat, be single purpose. The key is that only the identified user can trigger the generation of new verified urls.
When your app collects an AuthSig verified url, it doesn't have to check it right away. Imagine an AuthSig url sent alongside a blog post or comment. You can check the validity of that url at the time of publishing rather than at the time of storing. This flexibility was the incentive for creating this system.
Installation
It's a Padrino (rack) app.
padrino start should work.
So should foreman start.
rake dm:migrate first, maybe?
And rake db:seed too, perhaps.
Set an AUTHSIG_HOUSE_SECRET environment variable.
Adding AUTHSIG_HOUSE_SECRET=abcdefg-some-secret-here to .env is a good way to accomplish this in development mode.
The site root provides a lot of info about how stuff works.
Here's a hosted version: http://authsig.herokuapp.com/