h1. API OAuth

There is two legged OAuth protocol added in API allowing request authentication.

Signed request with OAuth (using @oauth_consumer_key@ and @oauth_consumer_secret@) are trusted by Foreman. If request verification is successful a Foreman user is authenticated. Depending on @oauth_map_users@ option the incoming request is executed as admin or as mapped user. If @oauth_map_users@ is enabled users are mapped by @User#login@ passed in @X-FOREMAN-USER@ header.

h2. Setup

# go to http://foreman.url/settings?utf8=%E2%9C%93&search=+category++%3D++Auth

# enable OAuth authetication @oauth_active@, set to @true@

# set @oauth_consumer_key@ and @oauth_consumer_secret@

# optionally set @oauth_map_users@ to @true@ to enable user mapping

h2. Troubleshooting

* if you have trouble enabling OAuth authentication watch Foreman log WARN messages.

* or debug OAuth authentication logic, see: source:lib/api/authorization.rb

h2. Security

OAuth does not signs whole request (body and @FOREMAN-USER@ are not signed), Api should be exposed over HTTPS.

h2. Examples

To list architectures using curl

<pre>

curl -X GET 'https://foreman.example.tst/api/v2/architectures' -H 'Content-Type: application/json' -H 'ForemanApiVersion: 2' \

-H 'Authorization: OAuth oauth_version="1.0",oauth_consumer_key="a",oauth_signature_method="hmac-sha1",oauth_signature="PlLTrHk5+aMgJACtww61dqakAWg=' -H 'FOREMAN-USER: ares'

</pre>

@oauth_consumer_key@ is set to a, @oauth_map_users@ is enabled so we set FOREMAN-USER header. The signature is normally computed by oauth client library, in this case I got it from server, it uses following algorithm

<pre><code class="ruby">

base = [method, normalized_uri, normalized_parameters]

base = base.map { |v| escape(v) }.join("&")

Base64.encode64(base).chomp.gsub(/\n/,'')

</code></pre>

as you can see, only method, URI and parameters are signed and verified on server side. Note that in real world usage, you should also include oauth_timestamp and oauth_nonce headers to prevent replay attacks.