(Check out the SAP Developer Challenge - APIs blog post for everything you need to know about the challenge to which this task relates!)
This task brings you one more step closer to being able to call the API endpoint to look at the details of the directory you created in your SAP BTP account in Task 7, in that you'll learn how to request an access token to use as the credentials in the API call.
Background
In the Background section to Task 8, while you were in "reading mode", you looked at the SAP Help Portal documentation Account Administration Using APIs of the SAP Cloud Management Service. The first child node in this documentation that you come across is essential to this task. It's Getting an Access Token for SAP Cloud Management Service APIs and describes how to go about requesting an access token.
OAuth access tokens are obtained through various means, depending, to an extent, on what's being protected, who owns the resource, and so on. There are different so-called "grant types" in OAuth. They're sometimes also referred to as "flows". There's an archived CodeJam content project over on GitHub, in the SAP-archive organization, that gives a brief overview of these grant types. It's Exercise 02 - Understand OAuth 2.0 at a high level.
Being in the SAP-archive organization indicates that the content is no longer being maintained. But this particular exercise content is still valid and worthwhile reading.
OK, back to the SAP Help Portal documentation. You'll see that "the APIs of the SAP Cloud Management service for SAP BTP are protected with the OAuth 2.0 Password grant type". In some cases the Client Credentials grant type is at play, but not here in our context (mostly as we created the service instance in Cloud Foundry, for reasons explained in the corresponding task). So far so good.
And just to remind you of where you are in this group of tasks, you've now done steps 1 and 2 of the steps introduced in Task 8. This time you're tackling step 3.
- create an instance of the SAP Cloud Management Service, with a plan that contains the appropriate scope(s) that you need ✅
- create a service key based on that instance ✅
- use the details in the service key to request an access token
- use the access token thus obtained to authenticate a call to the API endpoint
So you'll need to follow the SAP Help Portal instructions to request an access token. Requesting an access token involves making an HTTP call to an Authorization Server endpoint. In making such a request, information must be supplied to specify and credentialize that request. The information required here, being a request for access to a resource that's protected with the Resource Owner Password Credentials grant type (you can see why this is shortened to just "Password" grant type, right?) is:
- the type of grant type in play
- the resource owner's username and password (this is the "Resource Owner" part of the grant type)
- the client's identity (the identity of the client that will be making the API calls)
We know that:
- the grant type in play is "password"
- you are the owner of the resources that will be requested (the API facilities via the instance of the service you created, in your Cloud Foundry environment)
- there's an ad hoc identity (client ID) and corresponding secret (client secret) generated that is used to represent the client that will be making the requests
The client (in the case of this group of tasks) will just be the HTTP client you use to make the calls. It could just as well be a script, a program, or another system.
You know where the resources are that you'll be requesting (the API endpoints), you know who the resource owner is (you yourself) but where is this client ID and client secret? Yes! They're in the service key data that you obtained in the previous task!
OK. To finish off this section, it's worth repeating what the section in the Understand OAuth 2.0 at a high level content says for this Resource Owner Password Credentials grant type:
This is a flow designed for use in the situation where there is strong trust between the Client and the Resource Owner - more specifically, when the Resource Owner trusts the Client (application) so much that they are willing to give their username & password credentials to the Client, which can then use them to request an access token. One redeeming feature of this grant type is that the Client does not have to store the credentials, as the access token granted can be long-lived, and / or the lifetime of the token can be extended by use of a refresh token.
OAuth as a concept is wonderful, but it does take some thinking time to let things sink in. Embrace the wonder of OAuth and its many facets, and enjoy this task!
Your task
Your task, then, is to request an access token in this context of the Resource Owner Password Credentials grant type with which the API endpoint(s) of the Accounts Service API are protected.
When your request is successful, you'll obtain not only an access token, but other data with it, in a JSON object. Here's what it will look like:
{
"access_token": "eyJhbGciOiJSUzI1NiIs...",
"token_type": "bearer...",
"id_token": "eyJhbGciOiJSUzI1NiIs...",
"refresh_token": "e72b61a9a9304dde963e...",
"scope": "cis-central!b14.glob...",
"jti": "579fea14a1cf47d7ab9e..."
}
Actually, there will also be another property, which has been deliberately removed from this sample. It's one that tells you when the access token supplied will expire, and the value is a duration, in seconds.
Identify this property, take the duration, in seconds, and compute the number of hours, rounding up to the nearest whole hour. That integer result is what you should send to the hash function and reply with, as usual, and as described in Task 0.
Hints and tips
The task here is, from one perspective, quite straightforward. But from another perspective, if this is your first time requesting an access token in an OAuth flow like this, it's worth taking your time and making sure you get the right values passed in the right way to the call to the Authorization Server, i.e. to the call to the resource that ends with /oauth/token.
You may have come across this URL path before; while it's not a standard, it's in common use to represent the endpoint of an OAuth Authorization Server that can be used to request an access token. It's shown, by the way, in the Getting an Access Token for SAP Cloud Management Service APIs documentation section in the SAP Help Portal.
Use the sample curl invocations in Step 3 of the Procedure section in Getting an Access Token for SAP Cloud Management Service APIs as a guide.
You can of course use whatever HTTP client you wish to make the request for the access token. Whether you use curl or something else, be aware that the data that you send, as described in the documentation, should be sent with content type application/x-www-form-urlencoded. This means a series of name and value pairs.
And take this as a clue - in particular the urlencoded part. While the example in the documentation shows explicitly that the HTTP POST method should be employed (with -x POST, but see the note below), you are likely to have some values that you need to transmit, that have characters that need to be so encoded. And for those of you lovely folks who are using curl, you may find the --data-urlencode parameter very useful! 🙂
If you use curl and supply data with the -d parameter, then the HTTP POST method is used by default by curl, and you don't have to actually specify -X POST. Nor do you have to explicitly send a Content-Type header with the value application/x-www-form-urlencoded either, curl sends that by default.
For discussion
What approach did you take to request the access token? What form does the access token take? What other interesting information is returned in the JSON object?
