Since AuthenticationServices 2.0.1-GA
Broadleaf AuthenticationServices allows admin users to be managed by third-party authentication providers, such as Okta, Google, or MS Entra. For admins, AuthenticationServices also supports role management from the third-party provider. This allows companies to assign Broadleaf access roles from their centralized security system.
|
Note
|
For both admins and customers, Broadleaf supports simple login with third party OAuth2 providers out of box with minimal additional configuration. For comprehensive documentation on the configuration of OAuth2 Clients, see the third party IDP documentation. |
Admin User roles and access can be managed in either the admin interface or a third-party provider. The property broadleaf.auth.user.access-level.manage-tenant-app-access-externally controls which is used. Set to true to enable third-party management of roles and access. It defaults to false, which requires user roles to be set manually in the Broadleaf admin.
This refers to using the Broadleaf Admin, at section Security / Users (/users), to manage the Admin Users, including roles, tenant access, and application access. This is the default behavior, and indicates that the third-party authentication provider will only serve as an identity provider. There needs to be a Broadleaf Admin User record with appropriate roles and access already configured before the user can log in with the third-party provider. This means that there needs to be a default Admin User that can create new Admin Users before they can log in with the third-party provider. Set the Admin User’s Username and Email Address to the email address used to log in with the provider.
This refers to using a third-party authentication provider, such as Okta, Google, or MS Entra, to manage which users have access to the Broadleaf admin and what roles those users are assigned. In this case, Broadleaf AuthenticationServices can be configured to create new admin users and assign appropriate roles based on specific claims in the ID tokens from the provider.
|
Note
|
This option still uses Broadleaf’s AuthenticationServices to issue tokens for use with the other microservices. The third party system is only used for login. |
There are a few things to be aware of if choosing this option:
Role mappings. Roles defined in the external system must be mapped to Broadleaf roles.
Tenant access. Tenant level access needs to be considered. Depending on the user’s assigned permissions, they may be able to make changes at the tenant level that affect multiple applications (these are the actual customer facing stores). Depending on your business, you may need to restrict tenant access for users.
Application access. In a multi application scenario, you may want to restrict your admins to only viewing certain applications. This requires keeping track of the user’s assigned applications in your system.
To enable tenant/application management via third party, set the following properties:
broadleaf.auth.user.access-level.manage-tenant-app-access-externally=true
broadleaf.adminuser.access-level.manage-tenant-app-access-externally=true
When manage-tenant-app-access-externally is true, the system will look for additional claims on the third party token to determine access at the tenant/application level. The following table describes the claims.
| Claim | Description | Type |
|---|---|---|
|
Does the user have tenant level access? |
Boolean |
|
Does the user have application level access? |
Boolean |
|
The IDs of the applications the user has access to. An empty value indicates all applications |
String array, or comma separated string. |
|
The roles assigned to the user. Values are mapped with |
String array, or comma separated string |
|
Tip
|
The blc_roles claim corresponds to the Roles field on the admin edit user page. The claims blc_tenant_access, blc_app_access, blc_app_ids correspond to the fields in the Tenant and Application Access section of the admin edit user page.
|
Whether managing internally or externally, a User MUST have a role assigned to be able to access the Broadleaf Admin. During login, it is treated as a failed login attempt if a User does not have any roles assigned.
Roles assigned via third party are considered read-only and may not be modified via Broadleaf.
Roles assigned via third party are not updated in real time. They are updated each time a user logs in.
For this example, we’ll use Okta as our provider. The steps described here will vary slightly with other OAuth providers, but the fundamental concepts will be the same. This example will target local development.
In the Okta control panel:
Create an application in the Okta control panel with the sign-in method of OIDC.
Select Web Application as the application type
In the newly created application, configure the sign-in redirect URL. This has the pattern of {adminUrl}/auth/login/oauth2/code/{client-provider-name}. We’ll use okta as the client provider name, so for local development, the redirect URI will be https://localhost:8446/auth/login/oauth2/code/okta
Configure relevant user assignments and save.
Navigate to Okta API Scopes and grant the application the okta.users.read.self scope. This allows us to read the user’s profile information (name, email, etc.)
We need to configure Broadleaf Authentication to use our new Okta application. From the application view in the Okta control panel, the following information is needed:
The issuer URI
The client ID
The client secret
The redirect URI
The following scopes: openid, email profile
We’ll then configure the following properties:
spring:
security:
oauth2:
client:
provider:
okta:
issuer-uri: https://dev-xxxx.okta.com/oauth/default
registration:
okta:
client-id: my-apps-client-id
client-secret: my-apps-client-secret
redirect-uri: https://localhost:8446/auth/login/oauth2/code/okta
scope:
- 'openid'
- 'email'
- 'profile'Of note here, with the property spring.security.oauth2.client.provider.okta, we’ve set our provider’s name to okta. This matches the client provider name in our redirect URI we configured in the previous step: https://localhost:8446/auth/login/oauth2/code/okta. This is how the system knows to use these provider properties when redirecting back to the Broadleaf admin.
|
Note
|
This can also be configured in the OAuth Client Registrations section of the admin. See Third Party IDP - Admin UI for more details. |
Now, we need to configure this provider as usable from the Broadleaf admin with the following properties:
broadleaf:
auth:
user:
access-level:
manage-tenant-app-access-externally: true
web:
authorization:
strategy-delegates:
authentication-strategy-delegate:
# Note - this is only if your Admin 3PIDP authentication will be handled by DefaultOIDCAuthenticationStrategyDelegate.
# Different implementations such as 'google' or 'github' would be under their respective property prefixes.
default-oidc:
handle-external-admin-users: true
identity-provider:
admin:
hide-first-party-form: true
providers:
okta:
icon: okta-image.png
auto-register: trueIf exclusively using the third party provider to login, hide-first-party-form is recommended to be set to true. Setting this to true will automatically redirect the user to the third party login system when attempting to access the Broadleaf admin. If the first party form is hidden, the icon property is not needed.
For admins, it is generally recommended that auto-register is set to true. This will allow users configured in the third party system to automatically be created without first creating them in the Broadleaf admin and solves the "first user" problem described in the next step.
If auto-register is enabled, Broadleaf also needs to enable configuration of an ExternalAdminUserHandler by setting the property broadleaf.auth.user.web.authorization.strategy-delegates.authentication-strategy-delegate.{delegate-property-key}.handle-external-admin-users to true. Out of the box, Broadleaf has support for admin user handling for a delegate-property-key of types default-oidc, google and github. If none of these out of the box implementations work, the section over Custom OAuth Implementations has some information on the classes requiring extensions.
The manage-tenant-app-access-externally property allows the admin roles to be set from the third-party ID token.
At this point, our configuration is complete, but we still don’t have any users with the relevant permissions to access the Broadleaf admin. To address this, AuthenticationServices has the ability to set access permissions based on claims in the third-party ID token.
For admin user roles, AuthenticationServices maps the value in the blc_roles claim to a Broadleaf Admin Role with an ExternalRoleMapping. Out of the box, Broadleaf includes a mapping from the claim BLC_SUPER_ADMIN to the Full Access admin role.
To set up the first user as a super admin, add these custom claims to the ID token with values:
| Token Claim | Value |
|---|---|
|
|
|
|
|
|
For Okta, there are a few steps to make sure this is set up correctly which need to be done in the Okta Control Panel. This assumes the previous steps for setting up Okta have already been completed.
Navigate to the Profile Editor under the Directory tab of the Control Panel > Select the profile of the created application, this will have a name of "Application Name" User.
In the Attributes table, add a custom attribute with a display name and variable name of blc_roles. No other fields need changes and by default the data type should be string for this attribute. Repeat this for the other two claims listed above.
Navigate to People under the Directory tab of the Control Panel > Select the user that will be used to login to Okta on the Broadleaf Admin.
In the Assigned Applications table, assign the application modified in the Profile Editor from step 1 to the user. Once assigned, there should be an entry on the Assigned Applications table with a pencil symbol to Edit Application Assignment. Navigate to the edit form.
Scroll down to the bottom of the Edit Application Assignment
form and the three claims set up in step 2, blc_roles, blc_tenant_access and blc_app_access, should be visible. Add the corresponding values to these claims for the user. e.g. Set the value of the blc_roles field to BLC_SUPER_ADMIN.
Navigate to API under the Security tab of the Control Panel > Select the authorization server that is used for the implementation, this is most likely the default authorization server > Select the Claims tab
In the Claims table, add a claim with a Name of blc_roles, set Include in token type to ID Token, and set value to appuser.blc_roles. Repeat this for the other two claims replacing, blc_roles with the correct claim. This sets up the authorization server to send the claims information created in the previous steps with the auth request. For value, appuser is an Okta specific expression keyword which utilizes info setup on the Okta user.
|
Tip
|
For more information on this setup process, see Official Okta documentation. |
Now when this user logs in, their Broadleaf User record will automatically be created with appropriate access roles.
The ExternalRoleMapping map to the JPA Entity JpaExternalRoleMapping with the table auth.blc_ext_role_map. Custom mappings for roles can be added directly to the table. All mappings are global. There is not currently an admin interface for this table.
Mappings can be added for any Broadleaf defined role, whether out-of-the-box or custom configured. Further, there MUST be a mapping present to assign the role. Simply adding a Broadleaf role name to the blc_roles token claim will not assign the role.
If the out of box implementation does not suit your needs, there are two key classes to extend that handle user authentication and registration. Custom implementations can be written and registered as Spring beans to handle user login.
AbstractOAuthClientAuthenticationStrategyDelegate - Determines user profile information (name, email, username) and delegates to an additional handler responsible for creating/updating users.
AbstractExternalAdminUserHandler - Responsible for managing user state, including creating/updating admin users, determining tenant/application level access, and updating third party assigned roles. This must be set using AbstractOAuthClientAuthenticationStrategyDelegate#setExternalAdminUserHandler(ExternalAdminUserHandler)