Dear SAP Folks
During the implementation of OAuth 2.0 JWT Grant flow in SAP PI REST, I learnt lot of ins and outs about it and I hope through this blog you will have better insights into what to expect when configuring JWT Authentication for APIs which require it.
There is another blog about DocuSign JWT Authentication for Cloud Integration, so if you need configuration details about same in context of Cloud Integration you can refer this excellent blog:
Authenticate DocuSign APIs By JWT OAuth Grant Mechanism In Cloud Integration
When I got the requirement, the above blog was not there so I have made sure to include detailed steps and observations and the reasons behind those in this blog post.
Objective:
To understand and implement a complete scenario end to end for SAP PI REST adapter configuration where we will use OAuth2 configuration to use JWT grant authentication. I am sure this blog post will be able to shed light on JWT based Auth which has very limited documentation available.
What you should know already before this blog post:
(i) Understanding of how APIs work. (HTTP Methods, Headers, Params etc.)
(ii) Understanding of REST adapter.
(iii) Testing APIs with Postman.
For the theoretical explanation and more detailed insights about JWT you can check out jwt.io homepage, or below DocuSign page:
https://developers.docusign.com/platform/auth/jwt/
I will try to focus more on implementation here. Lets get started.
During the implementation of OAuth 2.0 JWT Grant flow in SAP PI REST, I learnt lot of ins and outs about it and I hope through this blog you will have better insights into what to expect when configuring JWT Authentication for APIs which require it.
There is another blog about DocuSign JWT Authentication for Cloud Integration, so if you need configuration details about same in context of Cloud Integration you can refer this excellent blog:
Authenticate DocuSign APIs By JWT OAuth Grant Mechanism In Cloud Integration
When I got the requirement, the above blog was not there so I have made sure to include detailed steps and observations and the reasons behind those in this blog post.
Objective:
To understand and implement a complete scenario end to end for SAP PI REST adapter configuration where we will use OAuth2 configuration to use JWT grant authentication. I am sure this blog post will be able to shed light on JWT based Auth which has very limited documentation available.
What you should know already before this blog post:
(i) Understanding of how APIs work. (HTTP Methods, Headers, Params etc.)
(ii) Understanding of REST adapter.
(iii) Testing APIs with Postman.
For the theoretical explanation and more detailed insights about JWT you can check out jwt.io homepage, or below DocuSign page:
https://developers.docusign.com/platform/auth/jwt/
I will try to focus more on implementation here. Lets get started.
- JWT Grant What is it for?
It is an OAuth 2.0 mechanism which is used for granting an access token to service integrations, which want to leverage an API integration. - Consuming an API
Consuming an API requires below steps in all types of integration.
(a) Log into the DocuSign Developers portal.
(b) Create and application which generates unique key values.
(c) Use generated API keys or other parameters which identify this app in unique way.
(d) Log in to client and configure these API key values for authentication.
(e) Deploy the configuration to use the API in real-time. In context of DocuSign, we will navigate through each of these steps. - Breakdown of JWT Flow
(a) Granting consent to make calls on behalf of logged in user (from step 2.i). This step generates an authorization code.
(b) The application (from step 2.b) requests access token.
(c) If step 3.a is not completed yet, it will rout the call back to step 3.a, else it will validate the passed in parameters. If the parameters are valid, it will return access code. Else, it will return relevant errors. - Using Access Token
The access token obtained in step 3 will be used to authenticate the APIs and complete the calls successfully. In SAP PI REST configuration the selection is available as to how do you want to use the “OAuth 2.0 access token as:”, you can select “HTTP header” there, as it will be shown in later steps. - Set up in DocuSign(a) Create Developers Account on DocuSign or it will be provided to you by your Org Admin.(b) Go to "My App and Keys" as shown below:
(c) This will take you to a landing page where your account details along with application you have created, are listed. Click the pointed out button for create a new application for our integration service.
(d) Create the App
(f) Scroll down to Service Integration section, where you can upload your own RSA key pair or generate a new one. We will generate a new one here.
(g) You will see a new key pair generated, copy the values by clicking the highlighted buttons as shown below and copy them to a notepad (or store them securely for later usage.)
Click “Save” button at the bottom, and you are done.
(i) As we are using individual grant, in this case we need to grant consent for this application to authenticate on our(logged in user’s) behalf.
To do this, we need to call below URL, and provide consent. You be asked to log in in case of “no log in” or “stale session”.
The URL is:
https://account-d.docusign.com/oauth/auth?response_type=code&scope=signature%20spring_read%20spring_...impersonation&client_id={IntegrationKey}&redirect_uri={redirect_uri}
Observation#1: the scope query parameter should include “impersonation” as shown above, else you will get “consent required” error later (refer step 3.b) despite a successful execution of next step.
Click on "ALLOW ACCESS" and you will be redirected to below page.
As long as the code is generated in the URL as seen below, this is expected. It confirms the consent is now granted successfully on behalf of the logged in user. Now your integration in SAP PI can use this application’s identifiers to fetch “access_token” with JWT grant flow for final authentication. - SAP PI Configuration (REST Channel)
(a) We will use REST adapter here to consume the APIs as it has all the configuration to satisfy our needs in context of OAuth 2.0 and JWT Grant.
(b) Create a REST Communication Channel and select field as shown below:
(c) Below highlighted fields are the ones we need for JWT Auth configuration here.
Now below are all the values for each field:
Issuer (iss)
Integration key for DocuSign application
Subject (sub)
user id of the logged user in DocuSign Developer portal
Audience (aud)
in official DocuSign documentation it is account-d.docusign.com
Expiration (exp)
it doesn’t have any bearing on the authorization process as the expiry of token is set by DocuSign application, and not by client. We will set as 3600 here.
JWT Signing Algorithm
you can use various types of Signing algorithm, but as per DocuSign documentation we will use RSA256
Scope
This basically the authorization/permission at entity level granted to the user to perform certain operations, these will be provided by Functional user and implemented by org admin for your user.
Observation#2: For JWT Signing Algorithm we will use the RSA key pair generated in step 5.f and these keys will be installed into NWA KeyStore for usage in REST channel configuration
(d) Now we will fill all the information for step (c) from step 5.
Observation#3: You may have noticed that scope field is blank here. The reason for this is the fact that for some reason the “scope” was a claim which was not treated as such when the values were configured here and the configuration was not able to use the scope values to generate the token.
To configure the scope, we will use “OAuth 2.0 Additional Parameters” configuration as shown below:
Observation#4: All values of scope configured here must be used in “grant consent” step in step 5, else the generated access token though valid, will not be able to fetch, update relevant entities in DocuSign.
REST URL Setting
As you have already selected "HTTP header" as option to use OAuth 2.0 token usage in the configuration as shown in step 6.d, you don't need to configure anything specific to "Authorization" parameter in "HTTP Headers tab of the REST channel.
HTTP Header Config
Finish rest of the configuration and you are done.
(f) You can run end to end test or ping the channel to validate configuration. A successful ping sample is below:
(g) For the end to end testing I have created a plain REST (SAP PI) to REST (DocuSign API) scenario. I will not get into the iFlow configuration here.
Below is the postman grab for testing of same interface.
Just to clarify the "created" field in the response as seen above is the timestamp of when my account was created in DocuSign last year. This DocuSign API just fetches user account information.
And here are the logs for a successful call to DocuSign API.
- A few notes:
(a) All the thing marked against "Observation" are the issues I encountered so I wanted to make sure you do not miss those configurations.
(b) If there is any issue with OAuth configuration, you will get “could not retrieve oauth token” somewhere in the ping or message processing in step 6.viii. Please revisit the configuration if you notice this issue.
(c) Make sure that you have imported HTTPS certificate in the NWA Trusted Certificate key store as well. The OAuth will not work without it. The trusted certificate should be of "Authorization Server URL" from step 6.d
Conclusion:
In this blog I have tried to convey a visualized way of understanding OAuth 2.0 configuration for JWT Grant flow. WE have gone over:
- Understanding JWT Grant Flow.
- Setting things up in DocuSign (similar steps will be there for other 3rd party API partners)
- REST Adapter Configuration to consume these APIs.
Along with this, I have tried to point out the issues and observation and relevant change you need to be wary of, to make the configuration work correctly. I hope this blog helps you with your implementations through more informed insights.
Action to the reader:
You can make this configuration work for other 3rd party APIs as well with similar configuration. Make sure to test the APIs in postman first for this configuration so that you have lesser issues to fix when move the settings over to REST Adapter.
Questions and feedbacks are very much welcome. Please do share, like and follow me for more such posts if you enjoyed this one.
Thank for you reading.
Please follow SAP Process Orchestration Community for more content:
https://community.sap.com/topics/process-orchestration
Also check out below link to read more other blog posts on SAP PO.
https://blogs.sap.com/tags/477916618626075516391832082074785/
- SAP Managed Tags:
9 Comments
