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

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
User authentication architecture in IFS Applications
Picture courtesy: IFS 10 Technical Documentation

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.

PKCE Authorization Code Flow in IFS
PKCE Authorization Code Flow in IFS

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 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

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

Obtaining OpenID Provider Configuration
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.

Response Headers in 401 unauthorized request
Response Headers in 401 unauthorized request

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.

Identity Provider details
Client ID and Secret

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

Postman Authorization
Postman Authorization

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
OAuth 2.0 Configurations

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

OAuth 2.0 Token

Below diagram explains what happened underneath until we get the token

OAuth 2.0 Authorization code flow with PKCE
OAuth 2.0 Authorization code flow with PKCE

If you need to see how the HTTP requests of each step looks like, you can check the Postman console for details

OAuth 2.0 flow – Postman console

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.

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

IFS Session cookies

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.

I’m working my free time on creating a .Net library to work the IFS IDP OAuth flow with PKCE and this blog is a result of it. If anyone needs assistance, I’d like to help as I could. Please reach me via damithsj@gmail.com

3 Comments

  1. Great document!
    I am happy to that now we can use Postman to get the data from IFS, This would really help technical and functional while developing integration from/to IFS. Very Good Article!!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s