Utilising Third-Party OAuth Tokens in SAP API Management

[SumaCV]

Introduction

OAuth, a widely accepted standard for secure access delegation, allows applications to access resources securely without needing to expose user credentials.

SAP API Management integrates smoothly with third-party OAuth providers, enhancing flexibility and simplifying authentication processes.

This blog explores the process of importing externally generated access tokens, refresh tokens, or authorization codes into the SAP API Management token store.

Background

SAP API Management generates an access token by creating a random string of letters and numbers. This token is then associated with other data such as the issuance time, expiration time, the list of API products the token is valid for, and the scope. When the OAuthV2 policy is configured with Operation = GenerateAccessToken, SAP API Management automatically includes this information in the response:

{
  "issued_at": "1469735625687",
  "application_name": "06947s70-288e-4ca3-ac72-036723t15789",
  "scope": "urn:httpsbin.org/read",
  "status": "approved",
  "api_product_list": "[OauthProd]",
  "api_product_list_json": ["OauthProd"],
  "expires_in": "1799", //--in seconds
  "developer.email": "aa@sap.com",
  "token_type": "BearerToken",
  "client_id": "U9AC66e9YFyI1yqaXgUF8H6b9wUN1TLk",
  "access_token": "zBC90HhCGmGlaMBWeZAai2s5tfIog",
  "organization_name": "SAP",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

The value of the access_token attribute is effectively the lookup key for the response data. For example, if an application sends a request to an API proxy hosted on SAP API Management with the bearer token zBC90HhCGmGlaMBWeZAai2s5tfIog, the OAuthV2 policy configured with Operation = VerifyAccessToken will look up the token, retrieve all information, and validate whether the token is authorized for the requested API proxy. This process is known as token validation. Essentially, the access token is a reference to the underlying information that comprises the token.

Alternatively, you can configure SAP API Management to use tokens generated by an external system. For instance, if an external service generates tokens in the format TOKEN-<16 random numbers>, SAP API Management can store and associate the same Information(e.g., issuance time, expiration time, API product list) with these tokens. For example, the Information for a token TOKEN-1092837373654221 might be stored in SAP API Management, allowing it to validate the token using the OAuthV2 policy with Operation = VerifyAccessToken.

This approach also applies to importing other types of tokens, such as authorization codes or refresh tokens, into SAP API Management for validation and management.

 

Policy Flow for third-party OAuth on SAP API Management

In SAP API Management, client credentials are essential for authenticating and authorizing API consumers within an OAuth framework.When integrating with third-party OAuth systems for token generation, the process should follow one of the  following pattern :

• External validation of client credentials
• Internal validation of client credentials.

Policy configuration for External Validation of Client Credentials

• ServiceCallout to Verify the inbound client credentials, and acquire an external token.

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<ServiceCallout async="false" continueOnError="false" enabled="true" xmlns="http://www.sap.com/apimgmt">
	    <Request>
	        <Set>
	            <Headers>
	                <Header name="Authorization">{Variable holding Autorization value}</Header>
	                <Header name="Content-Type">application/x-www-form-urlencoded</Header>
	            </Headers>
	            <Verb>POST</Verb>
	        </Set>
	    </Request>
	    <Response>TokenResponse</Response>
	    <Timeout>30000</Timeout>
	    <HTTPTargetConnection>
	    <URL>URI that will generate oauth token (e. g https://<Hostname>/oauth/token?grant_type=client_credentials)</URL>
	    </HTTPTargetConnection>
</ServiceCallout>

• ExtractVariables  to extract the externally-generated token from the response.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ExtractVariables async="true" continueOnError="false" enabled="true" xmlns="http://www.sap.com/apimgmt">
    <JSONPayload>
        <Variable name="external_access_token" type="string">
            <JSONPath>$.access_token</JSONPath>
        </Variable>
    </JSONPayload>
    <Source>TokenResponse</Source>
</ExtractVariables>

• AssignMessage to set the variable called oauth_external_authorization_status. The value must be true to indicate the client credentials are valid. In this policy, ClientID is also set .

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssignMessage async="false" continueOnError="false" enabled="true" xmlns="http://www.sap.com/apimgmt">
    <Set>
        <FormParams>
            <FormParam name="client_id">XXXXXXXXXXX</FormParam>
            <FormParam name="grant_type">client_credentials</FormParam>
        </FormParams>
    </Set>
    <AssignVariable>
        <Name>oauth_external_authorization_status</Name>
        <Value>true</Value>
    </AssignVariable>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"></AssignTo>
</AssignMessage>

• OAuthV2/GenerateAccessToken with the <ExternalAuthorization> element set to true, and at least one of <ExternalAccessToken>, <ExternalRefreshToken>, or <ExternalAuthorizationCode>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 async="false" continueOnError="false" enabled="true" xmlns="http://www.sap.com/apimgmt">
    <ExternalAccessToken>external_access_token</ExternalAccessToken>
    <ExternalAuthorization>true</ExternalAuthorization>
    <Operation>GenerateAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <StoreToken>true</StoreToken>
    <SupportedGrantTypes>
        <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
</OAuthV2>

Policy Configuration for Internal Validation of Client Credentials

• ServiceCallout to acquire an external token.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ServiceCallout async="false" continueOnError="false" enabled="true" xmlns="http://www.sap.com/apimgmt">
    <Request>
        <Set>
            <Headers>
                <Header name="Authorization">{Variable holding Autorization value}</Header>
                <Header name="Content-Type">application/x-www-form-urlencoded</Header>
            </Headers>
            <Verb>POST</Verb>
        </Set>
    </Request>
    <Response>TokenResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
    <URL>URI that will generate oauth token (e. g https://<Hostname>/oauth/token?grant_type=client_credentials)</URL>
    </HTTPTargetConnection>
</ServiceCallout>

• ExtractVariables  to extract the externally-generated token from the response.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ExtractVariables async="true" continueOnError="false" enabled="true" xmlns="http://www.sap.com/apimgmt">
    <JSONPayload>
        <Variable name="external_access_token" type="string">
            <JSONPath>$.access_token</JSONPath>
        </Variable>
    </JSONPayload>
    <Source>TokenResponse</Source>
</ExtractVariables>

• AssignMessage to set the Client-id and Client secret.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssignMessage async="false" continueOnError="false" enabled="true" xmlns="http://www.sap.com/apimgmt">
    <Set>
        <FormParams>
            <FormParam name="client_id">XXXXXXXXXXX</FormParam>
            <FormParam name="client_secret">XXXXXXX</FormParam>
            <FormParam name="grant_type">client_credentials</FormParam>
        </FormParams>
    </Set>
     <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"></AssignTo>
</AssignMessage>

• OAuthV2/GenerateAccessToken with the <ExternalAuthorization> element set to false, and at least one of <ExternalAccessToken>, <ExternalRefreshToken>, or <ExternalAuthorizationCode>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 async="false" continueOnError="false" enabled="true" xmlns="http://www.sap.com/apimgmt">
    <ExternalAccessToken>external_access_token</ExternalAccessToken>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>GenerateAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <StoreToken>true</StoreToken>
    <SupportedGrantTypes>
        <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
</OAuthV2>

 

SAP Help Document Links : 

https://help.sap.com/docs/sap-api-management/sap-api-management/third-party-oauth-token-usage?versio...

https://help.sap.com/docs/sap-api-management/sap-api-management/oauth-v2-0?version=Cloud

[Angshuman]

In which API we should apply these Policies, the main API preflow, which the client will call or We need to create a separate API proxy with these policies to generate the token? I am trying to use Azure entra ID application oAuth token to authenticate into APIM with grant type client credentail

[captwild06]

Angshuman, did you happen to figure this out? I am attempting to do the same thing, by leveraging an app registration in Entra in order to authenticate/authorize/grant tokens for an API I am developing and am getting the following;

{"fault":{"faultstring":"Execution of ServiceCallout ServiceCallout failed. Reason: ResponseCode 400 is treated as error","detail":{"errorcode":"steps.servicecallout.ExecutionFailed"}}}

I am having a hard time understanding the logical flow of this all.

[SumaCV]

@Angshuman  : You can apply the policies in the policy where you are generating the token. You can create a flow as /Token and apply the policies and generate the token and then use the token for further processing .

[SumaCV]

@captwild06 : In service callout policy , service which generates oauth token is invoked. Check if all the required properties are in correct format . 

[captwild06]

Hi @SumaCV ,

I think we are looking for a more holistic example with a step-by-step process. The information above is super helpful in explaining each component and its purpose, but in trying to build the full solution I think we need some guidance.