Wednesday, July 8, 2015

OpenShift v3 REST API usage

Time for a quick v3 api trial. The REST api is completely changed. First notable thing is authentication. Basic auth is no longer supported. Now the only supported auth types are oauth token and client SSL certificate.

Lets see how we can get an oauth token. First method is to go with a browser to https://your.openshift.master.server.example.com:8443/oauth/token/request

That will present you with a nice page explaining you how to use your newly acquired token. But we want to perform this in a more machine friendly manner so let's do with openshift-challenging-client via curl:
curl -u joe -kv -H "X-CSRF-Token: xxx" 'https://master.cluster.local:8443/oauth/authorize?client_id=openshift-challenging-client&response_type=token'
Keys here are:
  • use client_id=openshift-challenging-client, otherwise 400 Bad Request is returned
  • use response_type=token
  • set X-CSRF-Token header to some non-empty value, otherwise error is returned
  • actual token is returned in the Location header of the 302 response per the OAuth spec as access_token=VO4dAgNGLnX5MGYu_wXau8au2Rw0QAqnwq8AtrLkMfU
See partial curl output:

< HTTP/1.1 302 Found
< Cache-Control: no-cache, no-store, max-age=0, must-revalidate
< Expires: Fri, 01 Jan 1990 00:00:00 GMT
< Location: https://master.cluster.local:8443/oauth/token/display#access_token=VO4dAgNGLnX5MGYu_wXau8au2Rw0QAqnwq8AtrLkMfU&expires_in=86400&token_type=bearer
< Pragma: no-cache
< Set-Cookie: ssn=MTQzNjM3NzI4NXxDSkxSTl8yb0ZjUmZaSDZwNG51UjNDZEx1M29xRldQNGtGZTMwbnhfYlNRV2FuVmYxVHlKSWhWazVKWjR2RDc3X056ZVpqZXl6VWN4T0Nqc1dyX01raDhiUlNSdXFpdkhDalAwWDQzNWdyWExlTmNTUURjN3pQeW9HT1RpVmRtQ1JBPT18qi62Db0PolIHaMmAjtdKPejhCGRY-EUEruT6W_Du2bg=; Path=/; Expires=Wed, 08 Jul 2015 18:41:25 UTC; Max-Age=3600; HttpOnly; Secure
< Date: Wed, 08 Jul 2015 17:41:25 GMT
< Content-Length: 0
< Content-Type: text/plain; charset=utf-8
Now lets perform a real API call to remove the token we just obtained:
curl -vk -H "Authorization: Bearer VO4dAgNGLnX5MGYu_wXau8au2Rw0QAqnwq8AtrLkMfU" https://master.cluster.local:8443/oapi/v1/oauthaccesstokens/VO4dAgNGLnX5MGYu_wXau8au2Rw0QAqnwq8AtrLkMfU -X DELETE
Well done!

Notice how we pass the token - using header: 
"Authorization: Bearer VO4dAgNGLnX5MGYu_wXau8au2Rw0QAqnwq8AtrLkMfU"

You might have noticed API endpoint is /oapi/v1/something, where "v1" is the version of the API. How do we get server supported API versions? 2 ways so far:
$ curl -k https://master.cluster.local:8443/
{
  "paths": [
    "/api",
    "/api/v1beta3",
    "/api/v1",
    "/controllers",
    "/healthz",
    "/healthz/ping",
    "/logs/",
    "/metrics",
    "/ready",
    "/osapi",
    "/osapi/v1beta3",
    "/oapi",
    "/oapi/v1",
    "/swaggerapi/"
  ]
Looking specifically at kubernetes API endpoint:
$ curl -vk https://master.cluster.local:8443/api
{
  "versions": [
    "v1beta3",
    "v1"
  ]
Well forgot to mention. OpenShift v3 does give you access to the plain kubernetes REST API as well to the OpenShift REST API, because OpenShift is built atop of kubernetes. Not sure if versions of those two will be in sync forever but for the time being supported kubernetes and OpenShift API versions do match.

I'm planning to go through most interesting API calls in another post. So far you can try looking at existing documentation:
Update (June 2016): You can run `oc ... --loglevel=8` to see exact calls made by the oc utility. It's priceless to understand how an API call works. Keep in mind the output exposes your token.
    Thanks a lot to @liggit, without whom I wouldn't be able to write the above!

    3 comments:

    1. If I wanna use the X.509 certificates as an Authentication, how do I do that, and what are the places where I can find those certificates?

      ReplyDelete
      Replies
      1. @ssd, I think you only need to use proper client ssl certificate when performing the calls. I'm yet to try it out though. See "authentication documentation" link in the post.

        To manage your certificates you can use any approach you like. AFAIK Red Hat recommends freeIPA.

        If you don't have experience with certificates though, it might be better to generate tokens with proper expire times or use service accounts where token does not expire. It shouldn't be less secure but easier to understand and do right IMO.

        Delete
      2. You can check this discussion as well about that subject: http://lists.openshift.redhat.com/openshift-archives/users/2016-February/msg00312.html

        Delete