zhdk/madek

Authentication
==============

Every resource accessible through the API (except of the entry point) requires
proper authentication. Failing to perform authentication will result with a
`401 Unauthorized` response.


~~~ 
curl -I -H "Accept: application/hal+json" http://medienarchiv.zhdk.ch/api/media_resources

HTTP/1.1 401 Unauthorized
...
~~~

<div class="alert alert-info">
<h5> Authentication vs Authorization </h5>
We use the term authentication with respect off access to the Madek API. The
Http basic authentication uses the terms authentication and authorization in
this sense (see the response from the example above).

We use the term authorization with respect of retrieving certain resources 
within the Madek API.
</div>



Authentication requires knowledge of two properties: 

  1. an application **ID**, and
  2. a corresponding application **SECRET**.  




HTTP Basic Authentication
-------------------------
*[Http basic authentication][]* is based on using an *user name* and a
*password*. The ID serves as the *user name* and the SECRET as the
*password*. Many frameworks and application provide convenient methods
to pass on these parameters:

    curl -u demo-app:725553c2-67ce-4186-9087-a7f8e9762a41 -I -H "Accept: application/hal+json" http://localhost:3000/api/media_resources 

    HTTP/1.1 200 OK
    ...

However, [Http basic authentication][] does not more than encode the
parameters and send then via an http-header, see e.g. [Http basic
client\_side][]. This header can be send if the client does not support
the mentioned convenience:

    curl -I -H "Authorization: Basic ZGVtby1hcHA6NzI1NTUzYzItNjdjZS00MTg2LTkwODctYTdmOGU5NzYyYTQx" http://127.0.0.1:3000/api/media_resources

    HTTP/1.1 200 OK
    ...


Retrieving ID and SECRET
------------------------

Contact your MAdeK support, respectively administrator, to obtain the
required ID and SECRET. You can also obtain the ready encoded authorization
header.

Note, that the authentication header is not encrypted, not even
cryptographically hashed.

<div class="alert alert-danger">
Do neither share the secret nor the authorization header of your application!
</div>

[Http basic client\_side]: http://en.wikipedia.org/wiki/Basic_access_authentication#Client_side
[Http basic authentication]: http://en.wikipedia.org/wiki/Basic_access_authentication


Specification & Tests
---------------------

See [`madek /spec/requests/api/authentication_spec.rb`][].

  [`madek /spec/requests/api/authentication_spec.rb`]: https://github.com/zhdk/madek/blob/next/spec/requests/api/authentication_spec.rb