Deep Diver – Azure AD Groups/Roles claims for developers and IT pro’s with code examples

Background

Many enterprise applications rely on group /role information to be passed on assertions for authorization, and further role decisions. Last three to five years these applications have been moving to the cloud, or at least seeing parts of their authorization middle-wares upgraded to support SAML, or OAuth2, or both. Judging by how rich the group claim options are in Azure AD I’d say Microsoft is investing heavily into making configuration options cover all imaginable scenarios

Short version of this blog is:

Prefer SAML when:

• Application relies on getting user and groups information including transformed claims from the IDP in the initial token response.
• Application doesn’t need further information from other Azure AD API’s to be acquired by background flows using token delegation
• You want to transform claims both for user and group information in the GUI
• You want do as much as possible configuration and maintanence in the GUI

Prefer OAuth2 when

• Application has multiple Azure AD API’s called using token delegation, or redirect based flows after initial authentication
• Application needs combine information from Azure AD API’s beyond of that which is held in user attributes and groups
• While Claims Transformations arent supported in the token itself, you can basically do whatever you need to combine information once you have the initial token.
• Application needs multiple and complex group claim rules and you can do these in the back-end (Azure AD allows only adding single ‘add group claims’ rule in SAML app) – Note that even in OAuth2 this applies, but in OAuth2 you do this after receiving the initial token

Mix it together

• In complex scenarios you might need to decide on combining a mix of these approaches, or decide to lean heavily towards OAuth2. As I am mostly working from dev perspective I tend to prefer OAuth2 with or without OIDC, but in this blog I highlight benefits for both approaches
  • “For applications that do interactive browser-based sign-in to get a SAML assertion and then want to add access to an OAuth protected API (such as Microsoft Graph), you can make an OAuth request to get an access token for the API. When the browser is redirected to Azure AD to authenticate the user, the browser will pick up the session from the SAML sign-in and the user doesn’t need to enter their credentials.” /https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-saml-bearer-assertion

Useful information before proceeding

Claims transformations for Jwt tokens seem to be supported if you use the custom policy, even though this article recommends post token transformations in place of transformations for Jwt tokens. Transformations based on documentation seem to be limited on two methods atm

I’ve written few articles about Application Proxy If your applications remain on-premises but you need to modernize their access approach to Zero Trust

• Azure AD Application Proxy – SSO and Authorization notes from the field
• Concept: Publish on-prem API using AAD App Proxy and API Management with Azure AD JWT Bearer Grant
• Experimental testing: Azure AD Application Proxy With Azure Application Gateway WAF

Eating the elephant

Since the scenarios where groups and roles are so many, I’ve tried to distill it into an table to help with possible evaluations, and provided some examples and considerations to back these scenarios.

Note that in Azure AD Group is not explicitly same as Role. But these two can be mixed in various rules together.

Decision criteria table

Excerpt of configuration options presented in the table

send only groups that are assigned to the application (Via token configuration in App Registrations)

• App Registrations Token Configuration includes three type of token configurations for the group claims option
• Note the limitation only single group claims rule is available

send only groups that are assigned to the application (Via SSO settings in enterprise applications)

• For SAML apps this approach is preferable when you also need to change the name of the claim
• Note the limitation only single group claims rule is available

Query Graph API when send as claims is not possible

Querying Graph API is useful approach when you want/need information which is not available in the token response

• For SAML and JWT tokens which exceed group size limit you get Graph API link instead of the groups
• Azure Active Directory limits the number of groups it will emit in a token to 150 for SAML assertions, and 200 for JWT. If a user is a member of a larger number of groups, the groups are omitted and a link to the Graph endpoint to obtain group information is included instead.
• In this approach you need to add additional permissions for the application if you want to get the group names besides group id’s.
  • If you emit groups in the claims of the token you get with the built-in scope to graph the needed information

https://docs.microsoft.com/en-us/azure/active-directory/hybrid/how-to-connect-fed-group-claims#options-for-applications-to-consume-group-information

SAML / OAuth2 group information examples

In attempt to keep this blog even remotely readable I’ve included examples of the two main approaches, as all other examples are more or less derivatives/mixes of those two

SAML

• deliver most if not all information in the token response

OAuth2

• fetch information after receiving the initial token via separate http request to MS Graph API

Emit Groups in the token (works for both SAML and OAuth2)

Configuration for the examples below

• Note, here is alot to play with for different group configurations

Response example JWT token (Access Token):

Response example SAML token

Response example for exceeded group amount

Get groups of the user after token response – OAuth2 (And SAML APPS that support OAuth2)

• This scenario could be needed if filtering is required that is not available in claims customization, or the group size exceed token limits

Using OAuth2 JWT Bearer Flow

• I’ve written about JWT bearer grant earlier here Concept: Publish on-prem API using AAD App Proxy and API Management with Azure AD JWT Bearer Grant
• Note that this can be also achieved with:
  • Getting new access token with interactive user redirect flow
  • using refresh token flow (if initial scope allows storing refresh tokens)
  • SAML Bearer flow (This works with only SAML 1.1 tokens, so I am not recommending it, unless its token gotten from WSfederation protocol)
• The JWT token is stored either in back-end token store, or in user cookies (In the example is in the req.cookies.token)

Response example

Note! you can clean up the contents of graph response, if needed. This is just example 🙂

//Bearer Grant (depedencies request etc)
var getJwtBearerAssertion = ({client_id,redirect_uri,resource,assertion,client_secret},callback) => {
  //console.log(secret)
    var options = {
      json:true,
      headers:[{
      "content-type":"application/x-www-form-urlencoded" 
      }
      ],
      form: {
          grant_type:"urn:ietf:params:oauth:grant-type:jwt-bearer",
          client_id,
          redirect_uri,
          resource,   
          assertion,
          "requested_token_use":"on_behalf_of",
          client_secret
          }
      }
  
    rq.post("https://login.microsoftonline.com/common/oauth2/token",options, (error,response) => {
     //console.log('reqiest',options)
  
        if (!response.body.access_token) { return callback(undefined,response.body)}
  
       fs.writeFileSync('token.JSON',JSON.stringify(response.body))
        callback(response.body.access_token, undefined)
     }
    )
  
  }
// New code from here /Different JS file
var options = {
                client_id:ClientId,
                redirect_uri:RedirectUri,
                resource:"https://graph.microsoft.com",
                assertion:req.cookies.token,
                "client_secret":secret
             }
 
   getJwtBearerAssertion(options, (result,error) =>  {
                if (error) {return res.send(error)}
                apiCall(result,"https://graph.microsoft.com/v1.0/me/memberOf", (result) => {
 
                      var data =   result.value.filter((group) => {
                          console.log('group iterated')
//Iterate groups into Cookies
                         if (group.displayName) {res.cookie(`groupID:${group.id}`,group.displayName,CookieOpts)}
                        return group.id != undefined
                      })
                      
                      res.send(data)
                            }
                    )
                 

var xmlparser = require('fast-xml-parser');
const util = require('util')
function samlParser () {
    return function (req,res,next) {
       
        if (req.body.SAMLResponse) {
            console.log('SAML response')
            let bbuffer = Buffer.from(req.body.SAMLResponse, 'base64')
            var xmlstring = bbuffer.toString('utf-8')
            if (xmlparser.validate(xmlstring)) {
                
                var options = {
                ignoreAttributes:false
                }
            var xmlpayload = xmlparser.parse(xmlstring,options)
            var detailed = util.inspect(xmlpayload,true,7,true)
            console.log(detailed)
            req.body={'token':req.body.SAMLResponse}
            return next()
                
            }
            
        }
        next()
    }
}
console.log('using SAML parser')
module.exports={samlParser}

Security aspects

Using app permissions in place of delegated permissions?

This is generally not recommended practice (at least in my opinion) because

Using app permissions for substituting flows that are originally suited to use user delegation is not good idea, because it decouples user authorization and further requests to other API’s from the user context.

With delegated permissions 

• With delegation existing access rights of the user is used to get further information. The process delegating the token cannot exceed permissions of the user with the token
• More coherent log trail is produced as user context is shown which the app accessed API’s on behalf of the user

When instead app permissions are used

• Log trail is problematic. The action which was destined towards user API’s doesn’t show user context rather only the application acting towards the API
• Elevation of privilege risks enter the picture, as the app permissions might exceed by far margin the permissions of the user
• incomplete or no user consent even when the app does actions on behalf of user without delegation. 

Attacker figuring out a client side input parameters intended for back-end queries

• In “SAML approach” all of the delivered attributes are verified by signature verification, this applies to OAuth2 tokens too, but in OAuth2 approach you need to query often information after receiving the token for further information
  • Since the token JWT token might not have needed information, hypothetically you could have bad application code running “curl –insecure-” against what it expects to be Graph API” – but is instead being tricked to read an attacker controlled version of the endpoint. Attacker could use an limited Remote Code Injection approach, or figure out that some client side information is used in the back end with no integrity check, or has serious issues in with its input validation
    • example function running in the back-end expects that the array from client side function always produces single item array. The validation function assumes that the content is thus always stored in the index[0]. But the function processes all items in the array if the first index item is validated

• The obvious counter argument here is that if application is running insecure curl requests and such bad coding practices 🙂 how can you be sure, that its not being tricked to use the wrong token sign-in key? or have more serious security issues. In especially older apps, the public verification key is stored in the application itself With Azure AD this is not recommended, querying the JWKS uri needs to happen always from the metadata because those public keys can rollover (Read “Signing key rollover in Azure Active Directory”)
  • There is no plausible production scenario where you wouldn’t be verifying signatures of the either token types (SAML / JWT)

Where from here?

The current blog highlights technical decision criteria’s and examples of code sample and response outputs. For solving a particular group based scenarios don’t hesitate to ask me in twitter or LI for further additions into this blog

Microsoft references

https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-optional-claims

https://docs.microsoft.com/en-us/azure/active-directory/hybrid/how-to-connect-fed-group-claims