Background on OAuth2 Client Credentials
Stuck in my Ways
- Fetch token service URL, Client ID and Client Secret from a custom table.
- Call the OAuth token service to get token using APEX_WEB_SERVICE.
- Optionally store the token for use again (within its expiration window).
- Call the main web service using APEX_WEB_SERVICE, passing the token.
- Repeat as many times as the user calls the web service.
Don’t get me wrong, this is still much more convenient than using UTL_HTTP. As a developer, however, I am still having to manage the following:
- Storing the token end point and the client credentials (most likely not very securely).
- Deciding when the token expires and fetching another token (more likely not bothering to do this and just getting a new token every time I call the main web service).
Storing the Credentials
I have to build an APEX page to store the token URL and credentials and also some APIs to set and get these values. I then have to build APIs to manage token expiration and decide when to get a new token. Finally, I have to maintain this code and nurse it through upgrades etc. All this was fun the first time but I would much rather have APEX handle this for me so I can focus on delivering business logic.
Securing the Credentials
This approach also introduces the obvious security concern which is that I may not be encrypting the credentials when I store them.
Unless you build code to store the expiration time for the token, you are most likely going to call the token service every time you call the main web service. While token services are usually pretty light weight, you are incurring an extra round trip from your database to the endpoint every time you call the main web service. This can add up to a second to every web service call which is noticeable to your end users.
There is a Better Way
Since APEX 18.1 we can make calls to APEX_WEB_SERVICE without having to deal with first calling the associated token service or having to manage token expiration. This is made possible with the addition of 2 parameters p_credential_static_id and p_token_url. These parameters allow you to pass a reference to a set of ‘Web Credentials’ and the token URL to APEX_WEB_SERVICE and it will handle the REST (pun intended).
APEX_EXEC For all use cases that fit, I strongly encourage you to look into APEX_EXEC, instead of APEX_WEB_SERVICE. APEX_EXEC takes even more of the load off the developer and has a number of other advantages which I don’t have time to get into in this post. Carsten Czarski wrote a great overview in this post.
In addition to creating and editing Web Credentials in the APEX UI, you can also set them programmatically using the APEX_CREDENTIAL API (available since APEX 18.2). This API has a number of uses, one of which is to help when migrating new credentials to TEST and PROD instances.
- In order to use APEX_WEB_SERVICE (with web credentials) you need to have an APEX session.
- Here I am setting variables for the URL of the web service I want to call as well as the URL of the token web service. Ideally these would be stored in a table. For bonus points, you could store the base URL in a ‘Remote Server’ definition (also stored at the workspace level). You can then use the APEX view apex_workspace_remote_servers to fetch the base URL for the web service and tag on the path for the token service and the main web service.
- Call the web service. The final two parameters are of particular importance and are essentially what this blog is all about.
- p_credential_static_id is pointing to the Web Credential ‘SMS_DEV’ that I have setup in my workspace (see screen shot above).
- p_token_url is pointing to the URL of the token service for the web service referenced by l_rest_url.
- Check the return status of the call and parse the JSON response.
How did this Help Me?
- Call the main web service using APEX_WEB_SERVICE, passing Web Credentials Static ID and Token Web Service URL.
- Repeat as many times as the user calls the web service (APEX handles fetching new tokens etc.).
Storing the Credentials
The OAuth2 Client Credentials can now be stored natively in APEX using ‘Web Credentials’. APEX provides a UI to manage these credentials and APIs to set these credentials programmatically.
Securing the Credentials
Using Web Credentials, even the Workspace Administrator is not able to view the client secret for a given client. In addition, although there are APIs to set the credentials there are none to get credentials. The only way to use them is via APEX APIs.
When you pass values for p_credential_static_id and p_token_url you are essentially handing over management of the OAuth2 token to APEX. It will store the expiration for the token, and it will only get a new token when it needs to.
All this leaves you as a developer to focus on calling the main web service and parsing the results.
Enhancement Request: It would be great if instead of having to pass p_token_url, we could pass the static id of the remote server plus a suffix for the token service end point. This would prevent us from having to store the URL of the token service in a custom table. Remote Servers are defined under ‘Remote Servers’ in the Workspace Utilities area (right above Web Credentials).
Jon Dixon, Co-Founder JMJ Cloud