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.
Setup¶
- go to http://foreman.url/settings?utf8=%E2%9C%93&search=+category++%3D++Auth
- enable OAuth authetication
oauth_active
, set totrue
- set
oauth_consumer_key
andoauth_consumer_secret
- optionally set
oauth_map_users
totrue
to enable user mapping
Troubleshooting¶
- if you have trouble enabling OAuth authentication watch Foreman log WARN messages.
- or debug OAuth authentication logic, see: source:lib/api/authorization.rb
Security¶
OAuth does not signs whole request (body and FOREMAN-USER
are not signed), Api should be exposed over HTTPS.
Examples¶
To list architectures using curl
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'
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
base = [method, normalized_uri, normalized_parameters]
base = base.map { |v| escape(v) }.join("&")
Base64.encode64(base).chomp.gsub(/\n/,'')
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.
Updated by Marek Hulán almost 8 years ago · 3 revisions