Kyma for Dymmies [3]: calling secured service with REST client

In the previous blog post, we’ve created a service and secured an endpoint with OAuth
In this blog post we’ll learn how to call the service with REST client and how to view little more info

Quicklinks:
Quick Guide

This blog is intended for Wyndows users who prefer using a REST client tool, instead of running the HTTP requests on Linux bash.
Why not Linux?
No need to disclose the reason
In my case, it is Linux being too complicated for my little brain

Overview

• The protected endpoint
• The boring way (don’t skip)
  • Fetch access token
  • Call endpoint
• The easy way
• View the token

The protected endpoint

We start with a URL

https://safeapp.c-1234.kyma.shoot.live.k8s-hana.ondemand.com/prot

We know it is protected with OAuth
As such, we need to fetch an access token
BTW, there’s a blog post for OAuth dymmies…

The long and boring way (don’t skip)

As we know, prior to calling an OAuth-protected endpoint, we have to obtain an access token

Fetch access token

So let’s see how to compose the REST request for token fetch

1. Compose URL

To compose the URL, we remove the application name prefix from the endpoint URL and the suffix

So we get the domain name

In my example:
The app URL:

https://safeapp.c-1234.kyma.shoot.live.k8s-hana.ondemand.com/prot

Removing prefix and suffix:

https://safeapp.c-1234.kyma.shoot.live.k8s-hana.ondemand.com/prot

The resulting domain:

c-1234.kyma.shoot.live.k8s-hana.ondemand.com

Now we compose the token-fetch-URL:
We add the prefix oauth2 to the beginning of the URL:

https://oauth2.c-1234.kyma.shoot.live.k8s-hana.ondemand.com

And we  add the path for the token endpoint to the end

https://oauth2.c-4e9d1b2.kyma.shoot.live.k8s-hana.ondemand.com/oauth2/token

Note:
Make sure to replace the domain URI with your value

That’s the URL from which we get the access token
Now we can copy&paste it into our REST client

2. Authorization

To call that URL and get a token, we need to authorize.
This is done with clientid and clientsecret
Remember? In previous blog post we created an OAuth client for our secured endpoint
So now we have to view it again

In the Kyma dashboard, we navigate to Configuration->OAuth Clients then step into the details screen of our OAuth client which we created in the previous blog post
We called it oauthclient-for-nodesafeapp
On the bottom of the details screen we can see the corresponding “Secret” which carries the information about clientid and clientsecret

That’s what we need
However, the values are encoded
Fortunately, there’s a button “Decode”, which we happily press

Now we can copy&paste the required values for the authorization of the token request into our REST client

3. Parameters

To request an access token from an OAuth authorization server, we need to send 2 more pieces of information

grant type
The grant type is client_credentials, because we’re communicating from external app (in this case replaced by REST client) to the protected service

scope
In addition, we have to pass the required scope. We can also copy&paste it from the oauth client in the Kyma dashboard (see screenshot above)
In our example: nodesafeaccessscope

4. The request

See here the details of the request

And see here how it looks in postman

We can press Send
As a result we get the access token in the response body, along with some more data
Look:

We copy the value of the access_token property, without quotation marks, into our clipboard.
And keep it there.
Safe.

Call endpoint

Now we can use the access token for calling our protected endpoint
So we go ahead and copy the URL of our endpoint into our clipboard
…. upps… sorry…. now we’ve lost the access token which was already in clipboard…
My fault…

OK, you know you have to be patient with me, so keep smiling and go ahead…
Here are the details for calling our protected endpoint:

Note:
Alternatively, authorization can be configured as header.
In this case, the header name is Authorization and the value is composed as follows
“Bearer” followed by one space followed by the access token
E.g.
Authorization : Bearer abc123…

See my postman:

Result:
As a result we get the response text of our node server REST endpoint
Means that the access token has been valid

Host: We can see that the information about the host:
In my example:
service-nodesafeapp.default.svc.cluster.local:3333/prot’

Service: Fortunately, we can recognize the silly name of the service which we created in Kyma: service-nodesafeapp

Port: We can see the port 3333, which we defined in the descriptor of the service, is used

Small recap

1. We’ve called the token endpoint to fetch an access token
2. We’ve called our protected endpoint using the fetched access token

Call protected endpoint with Postman – easier

Postman (and other REST client tools) provides nice support for OAuth 2 authorization
We can call the protected endpoint with one request – and Postman handles the OAuth flow
(under the hood there will be of course 2 single requests)

See here how to configure Postman

We open a new tab in Postman and enter the following values

URL:
As URL, we enter the final URL of our protected endpoint
https://safeapp.c-1234.kyma.shoot.live.k8s-hana.ondemand.com/prot

Method:
Here we enter the HTTP method which is supported by our endpoint.
In our example it is a simple GET request

Authorization
Now we don’t have a token. We leave it up to Postman to fetch it
As such we can choose as Authorization type:  OAuth 2.0
Then we need to configure the token-fetch:
We pres22s “Get New Access Token”
In the dialog, we enter the following values:
Grant Type: Client Credentials
Access Token URL:
We compose and enter the same as described above:
https://oauth2.c-1234.kyma.shoot.live.k8s-hana.ondemand.com/oauth2/token
Client ID: Same as above, copy from OAuth Client in Kyma dashboard
Client Secret: Same as above, copy from OAuth Client in Kyma dashboard
Scope: Same as above, copy from OAuth Client in Kyma dashboard, nodesafeaccessscope
Client Authentication: Basic Auth
Finally, we press “Request Token”

As a result, we can see the access token in the dialog
Now we can scroll down and press “Use Token”
The token is inserted into the main request in postman
Finally we can press “Send”
As a result we get our success response

Small recap

To call an OAuth protected endpoint is made easy with the OAuth 2 support of REST client
The required information, like clientid, clientsecret and scope, has to be obtained from the Kyma dashboard, Configuration -> OAuth Clients
The token URL has to be composed according to Kyma domain URI and adding prefix and path

Note
While doing this exercise, we’ve seen the access token – and we might have wondered why it is shorter than the usual JWT tokens which we’ve seen before
The reason is: it isn’t a JWT token

View the Token

After we’ve fetched quite a few access tokens for our protected endpoint, we’d like to know what is inside the token
Why?
Just curiosity
Boring…
Come on, last short chapter, I promise…
Can’t we view anything nice?
OK

And now…
one more cat?
…let’s try to have a look at the token
To serve our curiosity, there’s an endpoint for token introspect
.We can call it…
…send the token to it…
……and in the response we get the boring information

Here are the details

Look

Result:
We can see the data contained in the access token, like
sub (subject),
exp (expiration ),
iss (issuer),
iat (issued at)

If the token is not valid, e.g. because it is expired, we get a success response, but it contains:
active = false

scope

In the request body, we can add the scope to the params:

token=123abc-123…abc&scope=nodesafeaccessscope

Result:
The scope parameter in the body is optional.
Result is same if the scope param is omitted.
However, result is false if scope is wrong (i.e. not the one contained in the token)
As such, this param can be used as kind of validation

More info:
https://www.ory.sh/hydra/docs/reference/api#introspect-oauth2-tokens

Summary

In this blog post we’ve learned how to call an OAuth protected REST service endpoint in Kyma

We’ve learned how to compose the token request, required to fetch an access token
To call the protected endpoint, we use the obtained token

In addition, we’ve learned how to read the content of an access token:
Kyma (more concrete: the Hydra component of the Ory component of Kyma) provides a service for token introspect

Quick Guide

Token fetch:

POST https://oauth2.c-1234.kyma.shoot.live.k8s-hana.ondemand.com/oauth2/token
Basic auth,  clientid, clientsecret from kyma dashboard
application/x-www-form-urlencoded
Body: grant_type=client_credentials&scope=nodesafeaccessscope

Token introspect:

POST https://oauth2.c-1234.kyma.shoot.live.k8s-hana.ondemand.com/oauth2/introspect
Content-Type:application/x-www-form-urlencoded
Accept:application/json
Request body: token=123abc…