Customizing Broadleaf Auth Service for User-Specific Claims

Authentication
1

The following question came in through our support channel:

I have a question regarding Authentication Services integrating with microservices during token creation.

I’d like to confirm whether it is possible and/or supported to enhance the authentication tokens generated by the Authentication Service with additional custom claims beyond the standard identity and role information.

In particular, can the Authentication Service call out to another service of the microservices platform during token creation to include user-specific details? Or is this not a recommended pattern within the Broadleaf ecosystem?

I’d appreciate any guidance or best practices you can share regarding the applicability of this approach.

2

While it is supported to add custom claims, making an external call to do so can have a significant performance impact since this will occur whenever any user requests an OAuth Access Token not just at login. Instead a pattern that we use is to sync some selected information to the Auth User from either the Customer Service or Admin User Service (depending on the type of user) on updates to the Customer or Admin User entities.

We do have a built in way to automatically map properties from the Customer entity to the User’s attributes, needing only Spring configuration properties. For example, to map the Customer’s phone number to a User attribute you can do the following:

broadleaf:
  auth:
    user:
      mapping:
        customer-mappings:
          - attribute-name: phone_number
            value-path: phone.phoneNumber
            include-as-token-claim: true

For include-token-as-claim, attributeName will be converted to snake case (phoneNumber → phone_number) if it is not already when added as a claim, and this will only work if the value is a String—other objects cannot be used as claims. This mapping takes place in CustomerPersistenceHandler#mapAdditionalAttributes, and adding it to the claims in UserAccessTokenEnhancer#getAdditionalAttributeClaims. More documentation on TokenEnhancers can be found here: Auth Services - Auth Services - Broadleaf Dev Central

Also note that care needs to be taken in how much information is added to the token for the sake of size constraints. Since the token has to be included in the Authorization header, default server size limits need to be taken into account, usually defaulting to 8kB. Ways to limit the token size also include limiting the number of authorities that are associated with a security scope since each authority is added to the token as well since this is what the resource APIs use to gate themselves. E.g., if the frontend user is a Customer trying to read Quotes, you could use the catch-all scope of CUSTOMER_USER, but that will map to a large number of authorities not necessarily relevant to a given need. Instead, when requesting an Access Token to read or operate against Quotes, you can supply the QUOTE scope that only maps to the relevant permissions. Beyond that, you can limit the number of additional claims added to the token.