SAP SuccessFactors OData OAuth with SAP IAS-generated SAML assertion

SAP SuccessFactors OData OAuth with SAP IAS-generated SAML assertion

Discover how to successfully integrate SAP SuccessFactors using SAP Identity Authentication Service (IAS) to enable secure OAuth SAML2.0 Assertion authentication. This guide offers a detailed walkthrough, from setup prerequisites to obtaining an access token, ensuring a seamless and secure integration for API applications.

1. Background / Design

SAP recommends using OAuth2.0 authentication for the authentication of API applications, since HTTP Basic Authentication is deprecated.

SAP OData OAuth 2.0 authentication is using the OAuth SAML2.0 Assertion flow for authentication, requiring an external IDP service to generate a signed SAML assertion, to be used in the request towards the SAP SuccessFactors API server.

Description of the from SAP documentation

Figure 1 – Description of the SAP documentation.

In this document, the setup will be described with SAP IAS for dynamically generating the SAML assertion, instead of using other 3rd-party IDPs.

The following screenshots show the setup using Okta Workflows as the API client application to handle the API calls between SAP SuccessFactors and IAS.

2. Setup

2.1 Prerequisites

  • SAP SuccessFactors is configured with IAS Federation.
  • A SuccessFactors API user is created with the same username in SuccessFactors and IAS.
  • A copy of the SAP IAS signing certificate (see below).

2.1.1 Retrieve the SAP IAS signing certificate

In IAS, the Signature Certificate can be retrieved from the tenant settings. From the Admin Dashboard, go to "Applications & Resources" and there to “Tenant Settings”. In the tenant settings, the signing certificate can be retrieved in “Single Sign-On” “SAML 2.0 Configuration”   Signing Certificates.

Certificate Information of SAP IAS Signing Certificate. 
Figure 2 – Certificate Information of SAP IAS Signing Certificate. 

Clicking on the “Lens Icon” ( ) opens the certificate information. Copy the text from the “Certificate Information” section:

Detailed certificate information of SAP IAS signing certificate.

Figure 3 – Detailed Certificate Information of SAP IAS Signing Certificate.

Note: If there are multiple signing certificates, choose the one that will be used in the SAML2.0 application, created in the following steps.

2.2 SuccessFactors

Create an OAuth2 Client application in the API center.

OAuth2 client application settings Figure 4 – OAuth2 Client Application Settings

Name Value
Company <SAP SF company>
Application Name Custom application name
Description Custom description
Application URL

Application URL for the OAuth flow. 

Okta workflows1



Bind to users Optional
x.509 certificate Let SuccessFactors generate it. Will be changed later.
API key Copy after creation of the application. Will be required later.

1Okta Workflows OAuth Reference

2.3. IAS Application

The next step involves creating an application in IAS. This application serves as the endpoint for retrieving the SAML assertion, which will be used to obtain the SuccessFactors Access Token. The IAS application will handle both SAML and OAuth requests.

2.3.1 Create an IAS SAML Application.

IAS Admin Applications & Resources Applications Create.


Name Value
Display name <custom>
Home URL <empty>
Type <optional> ("custom" types might be charged)
Parent application None
Protocol Type SAML 2.0


Create an IAS SAML application

2.3.2 SAML 2.0 Configuration

The SAML application needs to be configured with the token URL from SuccessFactors. This step is essential to enable the application to generate a SAML assertion with the URL in the "Recipient".

<select previously created application>    Trust    Single Sign-On    SAML 2.0 Configuration. 

Name Value
Name <custom>
URL for Principal Propagation

SFAPI token URL (<SF endpoint>/oauth/token)

For preview (example):

For production (example):


SAML 2.0 configuration Figure 5 – SAML 2.0 Configuration

2.3.3 Subject Name Identifier and Default Name ID Format

Select the attribute that matches the username of the API account in SuccessFactors.

Subject name Identifier – example configuration.Figure 6 – Subject Name Identifier – Example Configuration. 

Default Name ID format is “unspecified / urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified” (Default value).

2.3.4 Attributes

All default attributes can removed here. One additional attribute is added ("api_key") so the SAML assertion will be created with this attribute included. 

Name Source Value
"api_key" (case-sensitive) Expression <API key copied from SF OAuth2 Application created earlier>


Attributes values

Figure 7 – Attributes values

2.4 Allow Token Exchange Flow

After creating the application, the app needs to allow the Token Exchange OAuth2 grant. To do this, temporarily change the app to “OpenID Connect”.

Allow Token Exchange Flow Figure 8 - Change the app settings by clicking on "Edit" in the app overview.

Change the app from "Protocol Type" "SAML 2.0" to "OpenID Connect".Figure 9 – Change the app from "Protocol Type" "SAML 2.0" to "OpenID Connect".

After the app has been changed to OpenID Connect, go to “OpenID Connect Configuration” on the app and change the “Grant Types” to allow only “Password” and “Token Exchange (RFC 8693)” flows.

Location of the Grant Types for the OpenID Connect Configuration Flows.Figure 10 – Location of the Grant Types for the OpenID Connect Configuration Flows.

Save and change the app back to “SAML2.0”. Otherwise the Token Exchange flow will not work with this app: 

App setting back to "SAML2.0"Figure 11 – App setting back to "SAML2.0". 

2.5 Applications APIs – Client Authentication

Lastly, we need to create a form of authentication to create the initial IAS Access Token. In our example we will be using a simple secret.

<select previously created application> Application APIs Client Authentication.

Create Secret (settings according to company policies).

Applications APIs – Client Authentication

After the creation, copy ClientID and ClientSecret.

3. Flow

Now, let's put this knowledge into action. Our goal is to obtain an Access Token from SuccessFactors, and we can achieve this by making three separate API calls, with each call utilizing the information obtained from the previous result.

Step/Call Type Endpoint Result
1. Request IAS Access Token OAuth2 password flow <IAS>/oauth2/token IAS Access Token
2. Convert IAS token to SAML2 Assertion OAuth2 token-exchange <IAS>/oauth2/token IAS SAML2 Assertion
3. Request SuccessFactors Access Token OAuth2 assertion flow <SF>/oauth2/token SuccessFactors Access Token


→ To simplify the process, you can download our Postman collection with the preconfigured calls to IAS and Successfactors to retrieve an Successfactors Access Token!

3.1 Request IAS Access Token

To begin, we'll initiate a request for an access token from IAS. This access token will be generated within the context of the SuccessFactors user we intend to utilize for the SuccessFactors OData API. It's important that we adhere to the same username format used in SuccessFactors.

POST 'https://<IAS>/oauth2/token'
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Basic <token>' \
-d '{
  "password": "<IASPassword",
  "username": "<IASusername>",
  "grant_type": "password"

Request Attributes: 

Parameter Type Value
Content-Type Header «application/x-www-form-urlencoded»
Authorization Header «Basic <IASClientID:IASClientSecret>*»
Example, if ClientID=»Client1» and ClientSecret=”Secret2”:
“Client1:Secret2” -> Encode64 -> 
grant_type Body "password"
username Body IAS username (must be identical with SF username)
password Body IAS user password


Response body: 

  "access_token": "<access token>",
  "refresh_token": "20cd71d0007c04c3a091f15f926f3c35",
  "id_token": "<id token>",
  "token_type": "Bearer",
  "expires_in": 3600

The access token will be required in the next call. 

3.2 Convert IAS Access Token to SAML Assertion

Now, in this step, we need to convert the previously generated IAS Access Token into a SAML assertion. This is necessary in order to request an Access Token from SuccessFactors.

POST https://<IAS>/oauth2/token?grant_type
= urn:ietf:params:oauth:grant-type:token-exchange&
subject_token=<access token>
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Basic <token>'

Request Attributes:

Parameter Type Value
Content-Type Header «application/x-www-form-urlencoded»
Authorization Header «Basic <IASClientID:IASClientSecret>*»
*see previous call
grant_type Query “urn:ietf:params:oauth:grant-type:token-exchange”
requested_token_type Query “urn:ietf:params:oauth:token-type:saml2”
subject_token_type Query “urn:ietf:params:oauth:token-type:access_token”
subject_token Query <Access Token from previous call>
client_id Query <IAS Client ID>



  "access_token": "<Base64encodedSAMLAssertion>",
  "issued_token_type": "urn:ietf:params:oauth:token-type:saml2",
  "token_type": "Bearer",
  "expires_in": 600

The access token (SAML Assertion) will be required in the next step. 

3.3 Request SuccessFactors Access Token

Now that we have all the necessary information, we can proceed to request an Access Token from SuccessFactors. We will utilize the SAML Assertion obtained from IAS and use it on the SuccessFactors Token Endpoint.

POST https://<SFEndpoint>/oauth/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d '{
  "grant_type": "urn:ietf:params:oauth:grant-type:saml2-bearer",
  "company_id": "<SF company ID>",
  "client_id": "<SF api key>",
  "assertion": "<SAML Assertion from previous call> (Base64encoded)"

Request Attributes:

Parameter Type Value
Content-Type Header «application/x-www-form-urlencoded»
grant_type Body "urn:ietf:params:oauth:grant-type:saml2-bearer"
company_id Body Company ID of the Successfactors company (take from SF OAuth2 application)
client_id Body API key from the SF OAuth2 application
assertion Body Base64-encoded SAML2 assertion from the previous call.



  "access_token": "<the access token to the Successfactors OData API 🥳>",
  "token_type": "Bearer",
  "expires_in": 86268

That concludes the process! With this access token we can now use the SuccessFactors OData API. The full documentation for the API can be found here.

Ny call-to-action