Implementation of Principal Propagation using "saml2-bearer" grant type

[maxi1555]

Hello hello experts,

Today I want to share one of our common scenarios for principal propagation using Microsoft Azure AD as IDP:

Details:

1.User Authentication:

• Request:
  
  
  
  • The application performs a SAML request to Azure AD to authenticate the user
  
  
  
  


• Response:
  
  
  
  • Azure AD sends a SAML response( it contains the UPN )
  
  
  
  

2.Application Authorization:

• Request:
  
  
  
  • The application performs a OAuth Token request to SAP API Management including:
  
  
  • SAML response from Azure AD encoded in base64
  
  
  • SAP APIM application key
  
  
  • SAP APIM application secret
  
  
  • Grant type
  
  
  
  


• Response:
  
  
  
  • SAP API Management sends a access_token to be used in API calls
  
  
  
  

3.API calls:

• Request:
  
  
  
  • The application performs API calls using the access_token
  
  
  
  


• Response:
  
  
  
  • SAP API Management performs:
  
  
  • Access token validation
  
  
  • Call backend system using the UPN from the token
  
  
  • Send the backend API response to the application
  
  
  
  

IMPLEMENTATION

As you may know the "OAuth v2.0 Policies" support only the following grant_types out of the box:

• client_credentials


• authorization_code


• implicit

So you need to implement it manually in your policies using condition flows based on the grant_type "urn:ietf:params:oauth:grant-type:saml2-bearer"( link ), let's see in details how to do it:

API to get OAuth Token:

1-setSAMLFlag: Check if the "grant_type" requested is "saml2-bearer"

2-replaceClientType: As mentioned before this grant type is not supported so we need to change it

3-getToken: Get OAuth Token( in another words checking if the client_id & client_secret are correct )

4-Validate SAML response: Just validating the SAML response attached in the "assertion" field, for more details of the policies check this 

5-Get Principal Configuration Name: At this point we know that the client_id ( the application registered in API Business Hub Enterprise ) is valid so we read the "Custom Attributes" of the application to retrieve the "Principal Propagation Configuration Name"

getPPConfiguration: it gets the application details ( more info )

extractIDPSKeys: it extracts the PP configuration name using a xpath condition

6-Get PP Configuration details: here is where using the PP configuration name we retrieve the IDP issuer & audience allowed for this application via KVMs, and finally we check if the SAML atributes matches with the allowed ones:

7-setUPN: And finally if we reached this point we attach the UPN from the SAML assertion to the generated token

API to consume backend service:

Two simple steps need to added to all those APIs where you need "principal propagation" :

 

1-Verify Token: Policy OOB to verify the bearer token provided by the apps and if it is successful then the policy put the "attributes" of the token as variables in runtime

2-UPN_MISSING: In those APIs where you need the "principal propagation" you must check if the UPN is there

TEST

Get OAuth Token:

POSTMAN

APIM TRACE

API to consume backend service:

POSTMAN

APIM TRACE

As you can see below the UPN is in runtime after the "Verify Token" policy is successfully executed

The rest of the principal propagation flow is defined here

CONCLUSION

Principal Propagation is a must for all those APIs where user context is necessary, and it is very important to have a concept in place to be able to standardize the consumption of them, as you can see it's a pretty easy task using SAP API Management 😉

Notes:It can be extended for:

• jwt2-bearer


• X5092-bearer

Max.