What is OAuth 2.0 and how to set it up in Adaptive?

Uh Oh... OAuth? Was ist das?


Adaptive can connect with other applications's via REST APIs using the OAuth 2.0 authentication. 

I will explain what OAUTH is so you will no longer ask: "What is this?" (Was ist das?) and feel like someone is talking a foreign language to you!


 

What is OAUTH 2 really? How does it work and what do you need to do in Adaptive?

Let me give you 2 sets of explanations: a real life illustration to demistify OAuth 2.0 and a more technical summary. And lastly high level steps on the setup in Adaptive.

If you have no idea what OAUTH is, continue reading, otherwise jump to the 2nd section. 

In this example: imagine you need to connect to Microsoft Sharepoint and you want to bring CSV files  into Adaptive.


1) Illustrational explanation for total newbs: OAuth Access vs Hotel Access!

OAuth 2.0 can sound overwhelming at first, but it's essentially a way for applications to securely talk to each other and access data. Let me break it down into simple terms and examples.

The Big Picture: 

Imagine you want to go to a hotel (= API like Microsoft SharePoint) and use their pool (a resource, like your CSV file). The hotel doesn't just let anyone use the pool. You need a key (a token) that proves you have permission to use it.

Now, instead of giving you a permanent key to the pool (which could be dangerous if stolen), they give you a temporary pass (a short-lived token) each time you ask. To get the pass, you need to show them:

  1. Your Client ID (who you are).

  2. Your Client Secret (your secret handshake to prove you're allowed to ask).

The Main Players:

  1. Client (You): Adaptive Planning, which wants access to SharePoint files.
  2. Resource Server (Hotel): SharePoint, where the CSV file is stored.
  3. Authorization Server (Hotel Front Desk): Microsoft, which gives permission (tokens).

  4. Resource (The Pool): Your CSV file.

When you setup an OAuth 2.0 credential in Adaptive, it will ask you for:

Terms Simplified:

  • Client ID (Consumer Key): Your app's username. This identifies your app to the authorization server.

  • Client Secret (Consumer Secret): Your app's password. Used with the Client ID to prove your app is legitimate.

  • Token: A temporary keycard that lets your app access the data it needs.

    • Access Token: Lets you into the resource (e.g., download the file).

    • Refresh Token: Lets you get a new access token when the old one expires.

  • Scope: What parts of the resource you want access to (e.g., pool access, not the gym).

  • Redirect URI: Where the front desk sends you after approval, often back to your app.


Step-by-Step Flow: A Real-Life Example

Let’s say Adaptive wants to get a CSV file from SharePoint. Here’s what happens:

Step 1: Registration (Who are you?)

  • Adaptive registers with Microsoft to use OAuth 2.0.

  • Microsoft gives Adaptive:

    • Client ID: Think of this as your app's name tag.

    • Client Secret: Think of this as your app's password. Keep it safe!

Step 2: Asking for Permission (Knocking on the Door)

  • Adaptive asks you (the user) for permission to access your SharePoint files.

  • A new browser window opens, showing the Microsoft login page.

  • You log in and see a consent screen saying:
     “Adaptive wants to:

    • Read your files

    • Access your SharePoint data”

  • You click Allow.

Step 3: Authorization Code (Temporary Approval Note)

  • After you click Allow, Microsoft sends Adaptive a code to the Redirect URI.
     Example: https://adaptive.com/callback?code=1234abcd.

Step 4: Exchange Code for Token (Getting the Keycard)

  • Adaptive takes the authorization code and says to Microsoft:

    • "Here’s my Client ID and Client Secret.
       I also have this code the user just approved."

  • Microsoft checks everything and replies:

    • "Here’s your Access Token (keycard for the resource)
       and Refresh Token (to get a new keycard later)."

Step 5: Use the Token (Enjoy the Pool!)

  • Adaptive uses the Access Token to connect to SharePoint and download your CSV file.

  • The token is like saying:

    • "I’m Adaptive. I have permission to access this specific file."

Step 6: Renew the Token (Keycard Expired)

  • If the Access Token expires, Adaptive uses the Refresh Token to ask Microsoft:

    • "Can I have a new keycard?"

  • Microsoft replies with a new Access Token.


Why This Is Secure:

  • Tokens are temporary. Even if stolen, they only work for a short time.

  • Secrets stay secret. The Client Secret is only known by your app and the authorization server.

  • Permissions are limited. Scopes ensure your app only gets access to what it needs.


A Quick Analogy Recap:

  • Client ID = Your app's name tag.

  • Client Secret = Your app's password (secret handshake).

  • Access Token = A temporary pool keycard.

  • Refresh Token = A voucher to get a new keycard.

  • Scope = Permission to access the pool, not the whole hotel.

  • Redirect URI = Where you go after checking in.


2) Technical Summary: 

OAuth 2.0 is an authorization framework that allows users to grant websites or applications access to their data without sharing their passwords. It's a common standard used to authorize third-party applications to access user data on a service provider's platform.


How does OAuth 2 work?

  1. User Authorization:
    • The user logs into the service provider (e.g., Google, Microsoft, etc.).
    • The user grants permission to the third-party application to access specific data.
  2. Token Request:
    • The third-party application requests an access token from the service provider's authorization server.
    • This request includes information about the application and the scope of the requested access.
  3. Token Issuance:
    • The authorization server verifies the request and, if approved, issues an access token to the application.
  4. API Access:
    • The third-party application uses the access token to make API calls to the service provider's resources on behalf of the user.

OAuth 2 Credentials in Adaptive

To use OAuth 2 in Adaptive, you typically need the following:

  1. Client ID and Client Secret: These are unique identifiers for your application, provided by the service provider.
  2. Authorization URL: This is the URL where users can grant permission to your application.
  3. Token URL: This is the URL where your application can request access tokens.
  4. Scope: This defines the specific permissions your application needs.

Additional Considerations

  • Token Expiration: Access tokens typically have a limited lifespan. Your application should handle token expiration and refresh tokens as needed.
  • Security Best Practices:
    • Store your client secret securely.
    • Implement robust error handling and security measures to protect user data.
    • Consider using HTTPS to encrypt communication between your application and the service provider's APIs.

By following these steps and understanding the fundamentals of OAuth 2, you can effectively leverage this powerful authorization framework to integrate various services into your Adaptive workflows.


Setting up OAuth 2 in Adaptive

Before I explain anything, you can always refer for some info on Workday Adaptive's official documentation: 

What are the steps to configure OAuth 2 in Adaptive? 



  1. Create a New Credential:
    • Menu > Integration > Integration Management > Credentials > Create New Credential
    • Select OAuth 2.0 and give it a name (eg. OAUTH 2 - Sharepoint)
  2. Configure Authentication:
    • Have the customer provide the required credentials: 
      • Client Key (= Client ID), 
      • Client Secret (top secret, do not write on a postit!)
      • Scope: if any... indicates the type of permission, level of access

      • Authorization Header Required: please indicate Yes or No --> this will be in your Custom cloud DataSource or loader's Javascript API call.

      • Access Token Renewable: indicate Yes or No --> if the initial authorization process fetches the original access and refresh tokens for renewal, and if the access token on MS Sharepoints renews automatically.

      • Authorize redirect URL: URL to obtain the temporary credentials for delegation request identification.

      • Access Token Service HTTP method: GET or POST? (are you retrieving or posting data?)

      • Access Token Service Endpoint URL

        • Ex: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize

      • Token Expiry Default (in seconds): Default expiration in seconds for access tokens without an expiry time.

  3. Request Authorisation and Test the Connection:
    • You will need to create a new Custom Cloud Data Source (CCDS, to fetch data) or a new Custom Cloud Loader (to push data).
    • You will have to select your freshly created OAuth 2.0 credential and click on "Request Authorization" the first time. It will open a browser page where you will have to put credentials (that the customer will provide you with) to login to the third party application and confirm the authorization! You only need to do it once, or when the token expires (eg. every year).
    • Lastly... write the script to fetch / parse the data received or to be pushed (if you do an outbound integration)!--> Another post will come on that scripting topic!

Optimizing the CSV File Format for Adaptive Integration

To minimize the need for scripting and reduce maintenance on Adaptive's end, it's essential to ensure that the data in the CSV file adheres to a clean and consistent format. Here are some key guidelines:

  1. Avoid Special Characters:

    • Ensure that the file does not include special characters, such as pipes (|), in any data fields.

      1. This will cause Adaptive’s data parsing to fail, unless we specifically do the cleanup in the Javascript.

  2. Comma-Delimited Format and encapsulation:

    • If the file uses commas as delimiters, ensure that no data elements contain commas unless they are properly encapsulated within double quotes.

    • Encapsulate every data item within double quotes to maintain formatting integrity.


Example of the ideal CSV format:


“Account_Num”, ”Entity”, “Cost_Center”, “Currency”, “Memo”, “Posting_Date”, “Amount” 

"6100", "1", "300_HR", "USD", "Meal reimbursement, Juana Doe", "6/16/2024", "89.52"

In this example:

  • Each data element is enclosed in double quotes.

  • The comma within the Memo field ("Meal reimbursement, Juana Doe") does not disrupt the file's structure because of proper encapsulation.

By following these formatting practices, the data will be reliably parsed, and integration issues will be avoided.

Lastly, it is easier if the file has always the same name, or some consistent format that can be easily written in the Javascript (for example FileName_202412.csv --> filename_yyyymm.csv).


WAS IST DAS?

Are you still lost? If you do... Sorry... I know that feeling... Try to read it again a couple of times, it will come at some point! 








Comments

Post a Comment

Popular posts from this blog

Adaptive REST API Calls for Platform Customers with User Sync Enabled

How to Make Adaptive REST API Calls for Platform Customers with User Sync Enabled If you’re a platform customer (HCM + FINS + Adaptive) or using Workday HCM or Financials alongside Adaptive and want to create custom scripts leveraging Adaptive’s REST API (XML), you’ve likely encountered a key requirement: providing Adaptive user credentials (username and password). For standalone customers or those not using user sync, this typically involves creating an integration user in Adaptive. Easy peasy.  But what if you’re using user sync? How do you supply credentials for API calls in the XML input? In this article, I’ll guide you through the steps to generate the necessary credentials when user sync is enabled. I’ll also share helpful links to official documentation to ensure a smooth integration process. 1. Overview The process allows Workday-synchronized users to make API calls to Adaptive Planning using Workday credentials . The key steps involve: Generating an OAuth token using Work...
Read more

Introduction to Adaptive's API

To integrate data in Workday Adaptive Planning, customers typically use the integration module to connect with ERPs, SFTPs, AWS S3, Snowflake, SalesForce, Excel, and Google Sheets, etc.  You can also use third party platforms such as Tray.ai , Boomi , Matilion etc. which leverage Adaptive's APIs in a user friendly setup.  And lastly, you can write your very own scripts (C#, Python, Powershell...) to make these API calls.  Most  common Adaptive's API use cases Import Data from ERPs Actual summaries Actual transactions Assets, amortization, depreciation Transactional details by Supplier Payroll details and taxes Import Sales data from CRMs or datalakes Pipeline, churn, opportunities and customer list Billings and bookings ARR and MRR Import Headcount data from an HRIS Current headcount Terminated Hired, not started Wages and compensation plans Benefits Other Demographics Import Other data: Exchange Rates Weather Import Meta data: currencies, attributes, dimensions such...
Read more