In my previous article I wrote about Capturing IFS Aurena requests using Postman which is a shortcut method for calling IFS main cluster resources which requires OAuth2 and OpenID Connect authentication. I thought of getting little deep dive this time and try out how we can create a successful request to IFS with OAuth authentication.
What this post is about…
- What is OAuth and how it’s used in IFS
- Understand the OAuth 2.0 Authorization code flow
- How to create OAuth 2.0 token for IFS Identity Provider in Postman
- Using the OAuth 2.0 token to access IFS Main cluster resources
- My sample app
What is OAuth?
To begin at a high level, OAuth an open standard for authorization. Today when people talks about OAuth it typically means OAuth 2.0 specification. Everything about the OAuth 2.0 standard can be found on RFC 6749 but I bet no one would ever read that. But if you are so into develop your own OAuth flow, this is the best document you can have and there are plenty of information web about this so I won’t go into details.
OAuth in IFS
With the release of Aurena client in IFS Applications 10, IFS Authentication divided into two parts.
- OAuth2 OpenID Connect authentication for Clients
- HTTP Basic authentication for Integrations
When consuming IFS webservices or projections in integration cluster, we have to add the credentials in the HTTP Authorization header field of the request. There is no difference from previous versions of IFS. When consuming projections in main cluster (clients), the story is different and we need to use the OAuth2 authentication flow.
There are several variants of authorization code flow and todays’ best practice is to use PKCE (Proof Key for Code Exchange) whenever possible. What differs PKCE from regular flow is that it replaces the client secret used in the standard Authorization Code flow with a one-time code challenge. Therefore the client app doesn’t have to store a client secret.
Below diagram shows the basic steps involved with authorization code flow with PKCE.
If you need to build a new client for IFS with OAuth, above steps need to be followed to get it work. Implementing this flow could be tricky and depends on the technologies used to build the application. Using Postman, we can simulate the OAuth flow and call IFS main projections. It is also useful to check the HTTP request format requires when calling IDP endpoints so you can save a lot of time.
PKCE flow in Postman
Postman says that it supports PKCE flow and the option is available under OAuth 2.0 grant types. But I noticed that client secret is still required when getting the access token and it was discussed in this blog article as well. I’m not sure whether this is a bug on Postman or I mis-interpreted the concept.
Update 2021/01/12: This seems to be a bug in Postman and I created a issue in Postman github repo.
https://github.com/postmanlabs/postman-app-support/issues/9409
Update 2022/01/10, It’s now fixed: OAuth2.0 PKCE flow to no longer send a client_secret when it is left empty.
https://github.com/postmanlabs/postman-app-support/issues/9409#issuecomment-1008574015
We will now look at how to generate an OAuth token from Postman and call IFS main projection using it. Before that it’s interesting to check the steps for getting the IDP endpoint information (Steps 1-4 in above diagram)
Obtaining OpenID Provider Configuration
Open Postman and call a Main projection without authentication. You’ll get the HTTP 401 Unauthorized Request as the response. What interesting is the headers included in this response.
We can extract the IDP provider information from the WWW-Authenticate header and X-IFS-OAuth2-Resource header tells us the client ID.
According to OpenID specification, IDP provider configurations can be retrieved by calling the OpenID Connect Discovery URL. Typically, it’s in the format of
{{OPENID_CONNECT_URL}}/.well-known/openid-configuration
From here we can get the Authorization and Token endpoints and other related details. More information can be found in OpenID Connect Discovery swagger documentation.
IDP provider configurations is a simple JSON document. Below snippet is an example discovery document received from IFS inbuilt IDP.
{
"response_types_supported": [
"code",
"id_token",
"code id_token",
"id_token token",
"code token",
"code id_token token"
],
"claims_supported": [
"iss",
...
...
"at_hash",
"nonce"
],
...
...
"scopes_supported": [
"openid"
],
"issuer": "https://IFS_URL/openid-connect-provider",
"authorization_endpoint": "https://IFS_URL/openid-connect-provider/idp/authorization",
"token_endpoint": "https://IFS_URL/openid-connect-provider/idp/token"
}Now we’ll see how to obtain OAuth2 token in Postman for IFS
OAuth token in Postman
In order to get an OAuth token, you need following information
- Authorization endpoint
- Token endpoint
- Client ID
- Client Secret
- Scope
One way to fetch above information except the client secret is to follow the steps in Obtaining OpenID Provider Configuration but all these information can be found in IFS Admin console as well.
Go to Postman and Create a new GET request. Here I use the PartHandling projection to get PartCatalogSet information.
{{IFS_URL}}/main/ifsapplications/projection/v1/PartHandling.svc/PartCatalogSet(PartNo='TEST1')
In the Authorization tab, select OAuth 2.0 as Type
Fill the details in the OAuth 2.0 details form as follows
Add auth data to: Request Headers
Header Prefix: Bearer
Grant Type: Authorization Code (With PKCE)
Callback URL: {{IFS_URL}}/main/ifsapplications/projection/oauth2/callback
Auth URL, Access Token URL, Client ID, Client Secret: See OAuth Token step
Code Challenge Method: SHA-256
Scope: openid
Client Authentication: Send client credentials in body
Press Get New Access Token
It will pop up IFS login dialog to enter the credentials. Enter the credentials and Login. If everything works fine, you should get the Access token
Below diagram explains what happened underneath until we get the token
If you need to see how the HTTP requests of each step looks like, you can check the Postman console for details
Now we face a trap where most of my friends got in trouble including me 😉
IFS requires ID token, not the access token. It’s arguable whether it’s correct approach according to the OAuth 2.0 protocol but we have to deal with it anyway. If you press Use token, Postman will use the Access token. What you need to do is, copy the ID token and paste in the Access Token field.
ID token is recognizable from Access token by it's length.Update 2022-05-10
Tobias made a great input in one of the comments regarding how the access token can be used.
If you pass a parameter in the body of the token request called “resource” with the client id as the value, the access token is usable and the id token no longer needs to be used.
Now you are ready to call the main projection
below diagram explains the steps
Next step…
IFS will send cookies which can be used in the subsequent requests instead of the token. If you are building an app, you can keep that in mind and design the auth flow to use the cookies if they are present
When the cookies are present, you don’t need any type of authentication. To try this, we can select Authorization to No Auth and send the request. IFS will still accept the request and send the response.
Hope you find this post useful and will add some value for IFS Aurena debugging and developments. Please comment with your thoughts on any suggestions and improvements needed.
Sample app to demo OAuth2 flow with PKCE in IFS 10
Given below is a sample .NET app I created to demonstrate the OAuth2 PKCE flow in IFS10 with IFS Identity Provider
Sample console app to demo OAuth2 flow with PKCE in IFS 10
Leave a Reply to Harsha Yapa Cancel reply