OAuth2 Authentication/Token Acquisition

Explains how client applications obtain and use OAuth2 access tokens to access SAP Fieldglass REST APIs. Covers client credentials, SAML, and certificate-based authentication methods, including required parameters, URLs, access token usage, API key requirements, and X.509 certificate configuration.

Before a client application can access private data via the SAP Fieldglass REST API, it must request an access token from the SAP Fieldglass OAuth2 Authorization Server. A single access token can grant varying degrees of access to multiple APIs.

After an application obtains an access token, it sends the token to an SAP Fieldglass REST API in an HTTP authorization header or as part of the request body.

The x-ApplicationKey header is optional for Connector, Identity (SCIM), and Reporting APIs. If you receive an error for not including an API Key, you can obtain the API Key in your SAP Fieldglass Configuration Manager account.

There are multiple authentication options available for the OAuth2 service, including client credentials with basic authentication, client credentials with certificate-based authentication, client credentials with SAML response authentication, and SAML assertion grant.

Client Credentials with Basic Authentication

Client credentials authentication provides a relatively simple mechanism for authentication, using a client ID and client secret. The client ID is a valid SAP Fieldglass username and the client secret can be either that user's application password, or, to avoid issues with password rotation, a <license key>, as generated within the SAP Fieldglass system. Refer to the Create API Application Key or Web Service to create the license key.

The URL to use for client credentials requests is:

https://<SAP Fieldglass Environment URL>/api/oauth2/v2.0/token?grant_type=client_credentials&response_type=token

The following sample code illustrates how to obtain the access token with user/password credentials.

Sample Code

sample request for token with user/password credential

POST /api/oauth2/v2.0/token?grant_type=client_credentials&response_type=token
				Authorization: Basic {Base64Encoded(user:credential)}
				Content-Type: application/x-www-form-urlencoded
				X-ApplicationKey: {server provided key}

Sample Code

sample response

{"access_token" : "WDXlKj3TTOn3rpg9GHnZpbKmvj1=",
				"token_type" : "Bearer","expires_in" : 7200}

Client Credentials with Certificate Authentication

Certificate-based authentication provides a secure mechanism for authentication, eliminating the need for explicit credentials to be used (note that this authentication still uses the client credentials grant type as a framework). To leverage certificate authentication, do the following:

Use a required X509 certificate issued by a trusted Certificate Authority (for example, DigiCert) or the SAP Cloud Root Certificate Authority. Contact your SAP Fieldglass representative for more information.

Use the correct URL.

For a test environment, the URL is in the following format: https://<XXXX>-auth.<region>.fieldglass[test]/api/oauth2/v2.0/token?grant_type=client_credentials&response_type=token.

Where:

Variable	Value
`<XXXX>`	Company code or tenant
`<region>`	The region the client is in.

The environment base URL includes the protocol. The company name that is part of it should be followed with "-auth".

To set up the X509 certificate for use in OAuth2 authentication, complete the steps outlined in the Configure X.509 Certificate Authentication section within the SAP Fieldglass application. This adds the public certificate to the application and links it to a user (ensure it's a valid, active user), thus not requiring the credentials to be supplied as part of the OAuth2 request itself.

Client Credentials with SAML Response Authentication

A SAML Response message can be generated for a valid user and passed via a 'SAML Response' parameter (note that this authentication still uses the client credentials grant type as a framework).

The URL to use for SAML authentication request is:

https://<SAP Fieldglass Environment URL>/api/oauth2/v2.0/token?grant_type=client_credentials&response_type=token&scope=company%3D<XXXX>&SAMLResponse={Base64Encoded SAML Assertion}

The following sample code illustrates how to use client credentials with SAML response authentication to obtain the access token with SAML.

Sample Code

sample request for token with SAML

POST   /api/oauth2/v2.0/token?grant_type=client_credentials&amp;response_type=token&SAMLResponse={Base64Encoded SAML Assertion}
				Authorization: Basic {Base64Encoded(user:credential)}
				Content-Type: application/x-www-form-urlencoded
				X-ApplicationKey: {server provided key}

Sample Code

sample response

{"access_token" : "WDXlKj3TTOn3rpg9GHnZpbKmvj1=",
				"token_type" : "Bearer","expires_in" : 7200}

SAML Assertion Grant

A SAML assertion can be generated for a valid user and passed via an 'Assertion' parameter, alongside valid Client ID (client_id) and Client Secret (client_secret) parameters. The 'grant_type' parameter should be set to "urn:ietf:params:oauth:grant-type:saml2-bearer" in this case, per the RFC7522 Information published on non-SAP site .

The URL to use for SAML authentication request is:

https://<SAP Fieldglass environment URL>/api/oauth2/v2.0/token?grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer&response_type=token&scope=company%3D<XXXX>&client_id=[ClientID]&client_secret=[ClientSecret]&Assertion={Base64Encoded SAML Assertion}

The following sample code illustrates how to use client credentials with SAML response authentication to obtain the access token with SAML.

Sample Code

sample request for token with SAML

POST   /api/oauth2/v2.0/token?grant_type=client_credentials&amp;response_type=token&SAMLResponse={Base64Encoded SAML Assertion}
				Authorization: Basic {Base64Encoded(user:credential)}
				Content-Type: application/x-www-form-urlencoded
				X-ApplicationKey: {server provided key}

Sample Code

sample response

{"access_token" : "WDXlKj3TTOn3rpg9GHnZpbKmvj1=",
				"token_type" : "Bearer","expires_in" : 7200}