Broadleaf Microservices
  • v1.0.0-latest-prod

Auth Service Configuration

Overview

The following properties can be configured to control various aspects of the Broadleaf Auth Service

Service Properties

Property Description

broadleaf.auth.jpa.*

JPA Configuration Properties. See com.broadleafcommerce.common.jpa.data.JpaProperties for full list of options.

broadleaf.auth.datasource.*

Datasource Configuration Properties. See org.springframework.boot.autoconfigure.jdbc.DataSourceProperties for full list of options.

broadleaf.auth.liquibase.*

Liquibase Configuration Properties. See org.springframework.boot.autoconfigure.liquibase.LiquibaseProperties for full list of options.

broadleaf.auth.delegating.*

Delegating Schema Configuration Properties for running in a composed mode along side other Broadleaf microservices. See com.broadleafcommerce.common.jpa.data.SchemaDelegatingProperties for full list of options.

Cache Properties

Property Description

broadleaf.auth.cache.by-server-id

TTL property that influences cache settings for the auth service in Minutes

(Defaults to 5 minutes)

broadleaf.auth.cache.by-scope-names

TTL property that influences cache settings for the auth service in Minutes

(Defaults to 5 minutes)

broadleaf.auth.cache.by-scope-names-permissions

TTL property that influences cache settings for the auth service in Minutes

(Defaults to 5 minutes)

broadleaf.auth.cache.application-url-by-application-id

TTL property that influences cache settings for the auth service in Minutes

(Defaults to 5 minutes)

broadleaf.auth.cache.application-by-application-id

TTL property that influences cache settings for the auth service in Minutes

(Defaults to 5 minutes)

broadleaf.auth.cache.admin-url-by-tenant-id

TTL property that influences cache settings for the auth service in Minutes

(Defaults to 5 minutes)

broadleaf.auth.cache.by-auth-client

TTL property that influences cache settings for the auth service in Minutes

(Defaults to 5 minutes)

broadleaf.auth.cache.ancestor-account-cache-by-account-id

TTL property that influences cache settings for the auth service in Minutes

(Defaults to 5 minutes)

broadleaf.auth.cache.descendant-account-cache-by-account-id

TTL property that influences cache settings for the auth service in Minutes

(Defaults to 5 minutes)

broadleaf.auth.cache.account-inheritance-line-cache-by-account-id

TTL property that influences cache settings for the auth service in Minutes

(Defaults to 5 minutes)

broadleaf.auth.cache.client-identity-provider-cache-size (Since 2.0.3, 2.1.2)

Size of the LRUMap cache to use to store AuthenticationController#oauth2AuthenticationProviders

(Defaults to 100)

Authorization Server Properties

Property Description Default

broadleaf.auth.security.use-redirect-uri-host

Use the same host from the provided successful login redirect uri. This facilitates a common domain for authorize, login, and application, if desired. Redirect Uris are always validated against a white list.

false

broadleaf.auth.security.prefixed-domain-whitelist

If a tenant enabled installation is in place (i.e. broadleaf.auth.data.tenant.sync.active = true), this list serves to declare the possible domain names that can be used in conjunction with subdomains registered for applications via the Application#getIdentifierType() of ResolutionIdentifierType#DOMAIN_PREFIX.

broadleaf.auth.security.login-path-or-url

Either the path portion only to the login page (e.g. /login), or the absolute url to the login page (e.g. https://security.server.com/login. If use-redirect-uri-host is true, then this should be the login path only (since the system will be dynamically building the login form url). Otherwise, this value can be a full URL or relative path as needed.

/login

broadleaf.auth.security.global-domain-whitelist

If a tenant enabled installation is in place (i.e. broadleaf.auth.data.tenant.sync.active = true), this list serves to declare the possible domain names (e.g., all of global.mycompany.com) that can be used to validate a requested redirect uri that represents a global admin login.

broadleaf.auth.security.global-prefix-whitelist

If a tenant enabled installation is in place (i.e. broadleaf.auth.data.tenant.sync.active = true), this list serves to declare the possible domain name prefixes (e.g., global in global.mycompany.com) that can be used to validate a requested redirect uri that represents a global admin login.

["global"]

broadleaf.auth.security.frame-options

Determines the value and presence of the X-Frame-Options header.

DENY

broadleaf.auth.security.pkce-enabled

(Deprecated, not used in 2.0) Whether the Proof-Key-for-Code-Exchange enhancement for the Authorization Code Flow should be enabled.

false

broadleaf.auth.security.logout-redirect-parameter

The name of the parameter that indicates the URI to where the user should be forwarded after successful logout. The parameter should be included in logout requests from clients utilizing refresh tokens, eg cross-site websites or embedded apps.

returnTo

broadleaf.auth.security.oauth2.encoded-private-key

Base64-encoded version of the private key used to generate tokens. Used for encrypting both the JWT authorization tokens as well as stateless session cookies.

broadleaf.auth.security.oauth2.encoded-public-key

Base64-encoded version of the public key used to generate tokens. Used for encrypting both the JWT authorization tokens as well as stateless session cookies.

broadleaf.auth.security.oauth2.issuer

Used in validation of JWT to ensure that the system that issued the token (this one) is the same as the one passed in the token. Corresponds to the iss JWT claim

broadleaf-authentication

broadleaf.auth.security.oauth2.additional-audiences

Corresponds to the aud JWT claim. Usually contains the iss claim

["broadleaf-authentication", "oauth2-resource"]

broadleaf.auth.security.oauth2.impersonated-session-duration

The max session duration for an impersonated session. This controls how long a CSR will have a session authenticated as the impersonated user.

15 Minutes

broadleaf.auth.security.oauth2.whitelisted-impersonation-authorities

The whitelist of GrantedAuthority that will be inherited when a user is impersonated by a CSR user. This set of authorities serves as a whitelist of the authorities that are inherited by the impersonated user session. This set only restricts the authorities permitted, but it will not result in authorities being inherited that the CSR does not originally have.

["CSR", "ALL_CSR", "PUBLISH_QUOTE"]

Content Security Policy (CSP) Properties (since 1.6.0)

Tip
 For more information about this, see Mozilla’s documentation.
Property Description Default

broadleaf.auth.security.content-security-policy.*

Properties configuring Content Security Policy behavior. See com.broadleafcommerce.auth.user.autoconfigure.AuthorizationServerProperties.ContentSecurityPolicyProperties for full list of options.

broadleaf.auth.security.content-security-policy.enabled

Whether to enable content security policy behavior.

true

broadleaf.auth.security.content-security-policy.default-src.enabled

Configures whether to include the 'default-src' content security policy directive.

true

broadleaf.auth.security.content-security-policy.default-src.value

If enabled, this is the value to use for the 'default-src' content security policy directive.

'self'

broadleaf.auth.security.content-security-policy.base-uri.enabled

Configures whether to include the 'base-uri' content security policy directive.

true

broadleaf.auth.security.content-security-policy.base-uri.value

If enabled, this is the value to use for the 'base-uri' content security policy directive.

'self'

broadleaf.auth.security.content-security-policy.frame-ancestors.enabled

Configures whether to include the 'frame-ancestors' content security policy directive.

true

broadleaf.auth.security.content-security-policy.frame-ancestors.value

If enabled, this is the value to use for the 'frame-ancestors' content security policy directive.

'self'

broadleaf.auth.security.content-security-policy.form-action.enabled

Configures whether to include the 'form-action' content security policy directive.

true

broadleaf.auth.security.content-security-policy.form-action.value

If enabled, this is the value to use for the 'form-action' content security policy directive.

'self'

broadleaf.auth.security.content-security-policy.additional-directives

A list of additional directives that should be added to the content security policy header. Each must include both the directive name and the value. This will automatically be combined in the final result with a semicolon separator.

[] (empty list)

Dispatcher Type Authorization Properties (since 2.0.0)

Property Description Default

broadleaf.auth.security.dispatcher-type-authorization.should-configure

Whether dispatcher type authorization should be configured. Modifying this may also cause you to adjust 'spring.security.filter.dispatcher-types'.

true

broadleaf.auth.security.dispatcher-type-authorization.dispatcher-type-matchers-permitted-without-authorization

The dispatcher type matchers to permit without authorization. FORWARD is necessary to allow MVC forwarding to views.

FORWARD

Registration Properties

Property Description Default

broadleaf.auth.registration.email-as-username

Indicates that the registered user’s username should always be set from their email.

true

broadleaf.auth.registration.require-password-confirmation-field

Whether the registration form requires that there be a password confirmation field where the user has to re-enter their password. This must match the password field. This decreases the changes the user mistypes their password when registering.

false
Note
 In order to use the broadleaf.auth.registration.email-as-username property, an additional property in CustomerService i.e. broadleaf.customer.behavior.email-as-username needs to be set to the same value as the property above. Both of these properties must be set to the same value for enabling/disabling the behavior of using an email as username. The first property is specifically for the Authentication Service (and is also applicable to the users for admin and commerce sites) while the latter is for the Customer Service (specifically for the users on the commerce site).

Password Properties

Property Description Default

broadleaf.auth.password.validation.short-pattern

The minimum number of characters for a password.

^.{8,}$ (min is 8)

broadleaf.auth.password.validation.long-pattern

The maximum number of characters for a password

^.{0,255}$ (max is 255)

broadleaf.auth.password.validation.upper-pattern

How many uppercase characters the password must have.

^.*\p{Lu}.*$ (min is 1)

broadleaf.auth.password.validation.lower-pattern

How many lowercase characters the password must have.

^.*\p{Ll}.*$ (min is 1)

broadleaf.auth.password.validation.digit-pattern

How many digits the password must have.

^.*[0-9].*$ (min is 1)

broadleaf.auth.password.validation.special-pattern

How many special characters the password must have and what characters count as special.

^.*[●!"#$%&'()*+,\-./:;<⇒?@\[\\\]^_`{|}~].*$ (min is 1)

broadleaf.auth.password.validation.whitepsace-pattern

Controls whether whitespace characters are allowed. If this is true, then validation fails.

^.*[\s].*$ (max is 0)

broadleaf.auth.password.validation.repeated-pattern

How many repeated characters the password can have.

^.*(.)\1\1.*$ (cannot have more than 2 repeated characters)

broadleaf.auth.password.validation.custom-pattern

Additional patterns that must be matched.

broadleaf.auth.password.token.previous-passwords-to-remember

Determines the number of previous passwords to the system should remember. This is used to prevent a user from reusing a recently used password. Zero indicates no passwords are remembered.

0

broadleaf.auth.password.token.ttl

How long a password reset token is valid for. A negative or 0 value indicates that once a password token is generated it is valid forever (no expiration).

30 minutes

broadleaf.auth.password.token.chars

The character set to use when generating password tokens.

ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*()_+|\]}[{'";:/?.>,<`~

broadleaf.auth.password.token.length

The length of a generated password token

32

broadleaf.auth.user.password.password-max-life-days

The number of days a password is valid, after which it must be reset. Zero indicate no limit.

0

broadleaf.auth.user.password.force-password-reset-if-last-updated-date-is-null

Whether to force users to reset their passwords if User#passwordLastUpdated is null. This can happen for users created before that field was introduced.

false

Embedded Login Properties

Property Description Default

broadleaf.auth.login.embedded.enabled

Whether to enable features supporting embedded login. By default, only Universal Login is enabled. Setting this property to true will allow both.

false

broadleaf.auth.login.embedded.paths.login

The path to use for embedded login.

/embedded/login

broadleaf.auth.login.embedded.paths.request-password-reset

The path to use for embedded login request password reset.

/embedded/request-password-reset

broadleaf.auth.login.embedded.paths.reset-password

The path to use for embedded login password reset.

/embedded/reset-password

broadleaf.auth.login.embedded.paths.change-password

The path to use for embedded login change password.

/embedded/change-password

Data Initialization Properties

Property Description

broadleaf.auth.data.load.*

Seed Data Initialization Properties. See com.broadleafcommerce.auth.data.autoconfigure.AuthorizationDataInitializationProperties for full list of options.

Refresh Token Rotation Properties (since 1.4.0)

Property Description

broadleaf.auth.token.*

Refresh Token Rotation configuration Properties. See com.broadleafcommerce.auth.token.TokenProperties for full list of options.

Stateless Session Properties (since 1.6.0)

Property Description

broadleaf.auth.stateless.saved-request-cookie-same-site-value

The value to use for the SameSite attribute on the "saved request" (BLSR) cookie responsible for redirecting users following an authentication request. See com.broadleafcommerce.auth.user.session.environment.StatelessUtilProperties for the full list of options.

(Defaults to Lax)

Authorized Client Repository Properties (since 1.6.0)

Important
 This has been removed since AuthenticationServices 1.8.15 and 2.0.1.
Property Description

broadleaf.auth.auth-client-repository.authorized-client-cookie-same-site-value

The value to use for the SameSite attribute on the cookies responsible for saving authorized clients (BL-ACS-*). See com.broadleafcommerce.auth.client.autoconfigure.OAuth2AuthorizedClientRepositoryProperties for the full list of options.

(Defaults to Lax)

Authorization Request Repository Properties (since 1.6.0)

Property Description

broadleaf.auth.auth-request-repository.saved-auth-request-cookie-same-site-value

The value to use for the SameSite attribute on the cookies responsible for saving authorization requests (BLSAR). See com.broadleafcommerce.auth.client.autoconfigure.AuthorizationRequestRepositoryProperties for the full list of options.

(Defaults to Lax)

Authorized Client Validator Properties

Property Description Default

broadleaf.auth.client.validator.excluded-grant-types

Authorization Grant Types that cannot be saved to an AuthorizedClient

["password", "urn:ietf:params:oauth:grant-type:jwt-bearer", "urn:ietf:params:oauth:grant-type:device_code"]

Authorized Client Validator Properties

Property Description Default

broadleaf.auth.client.validator.excluded-grant-types

Authorization Grant Types that cannot be saved to an AuthorizedClient

["password", "urn:ietf:params:oauth:grant-type:jwt-bearer", "urn:ietf:params:oauth:grant-type:device_code"]

Automatic Authorization Server and Authorized Client Creation on Application Creation Event properties

When a new Application is created, Authentication Service will also create a matching AuthorizationServer and AuthorizedClient. Broadleaf provides configuration properties to determine the default values for various fields on each, some of which can be derived from values on the created Application. These properties can be configured independently for each tenant (based on tenant ID, case-sensitive.), or even disabled for a single tenant. To configure the properties for a tenant with the ID my-tenant, simply specify the tenant’s id as the map key.

Example Tenant Configuration
broadleaf:
  auth:
    server-creation-defaults:
      my-tenant: # tenant id
        user-role-ids:
          - '-100'
        sso-enabled: true
        domain-default-redirect-uris:
          - 'https://{domain}/callback'
          - 'https://{domain}/silent-callback.html'
          - 'https://{domain}'
          - 'https://www.{domain}/callback'
          - 'https://www.{domain}/silent-callback.html'
          - 'https://www.{domain}'
          - 'https://localhost'
          - 'https://localhost/callback'
          - 'https://localhost/silent-callback.html'
        domain-default-client-redirect-uri: https://{domain}
        domain-prefix-default-redirect-uris:
          - 'https://{domain}.localhost/callback'
          - 'https://{domain}.localhost/silent-callback.html'
          - 'https://{domain}.localhost'
        domain-prefix-default-client-redirect-uri: https://{domain}.localhost
        parameter-default-client-redirect-uri: 'https://localhost/?application={identifier}'
        parameter-default-redirect-uris:
          - 'https://localhost?application={identifier}'
          - 'https://localhost/?application={identifier}'
          - 'https://localhost/callback?application={identifier}'
          - 'https://localhost/silent-callback.html?application={identifier}'
        # the following are since 1.8.6
        context-path-default-client-redirect-uri: 'https://localhost/{identifier}'
        context-path-default-redirect-uris:
          - 'https://localhost/{identifier}'
          - 'https://localhost/{identifier}/'
          - 'https://localhost/{identifier}/callback'
          - 'https://localhost/{identifier}/silent-callback.html'
Note
 These properties must follow kebab-case format and must be lower-cased. For example, the tenant IDs MYTENANT, myTenant and mytenant cannot be differentiated via properties, and in all these cases the tenant ID property should be mytenant.

To configure default properties that apply to all tenants, use default in place of a tenant ID. Properties for defining the default redirect URIs support special template variables that will be used to dynamically generate the redirect-uris based on an Application’s identifier type and value. For DOMAIN and DOMAIN_PREFIX identifier types, Broadleaf supports a template variable called domain. This value will be substituted with the application’s domain. Thus, for domain discriminated apps you could do: https://{domain}/callback'. And for domain prefix: https://{domain}.localhost/callback'.

For PARAMETER and CONTEXT_PATH apps, the variable is identifier. Thus, for parameter discriminated apps you could do: https://localhost/callback?application={identifier}. And for context-path: https://localhost/{identifier}/callback

Property Description

broadleaf.auth.server-creation-defaults.{tenantid}

See com.broadleafcommerce.auth.tenant.domain.DefaultAuthServerProperties.AuthServerProperties for full list of options.

broadleaf.auth.server-creation-defaults.{tenantid}.disabled

Optional. If set to true, no Authorization servers or Clients will be automatically created for applications for this tenant.

Post Auth URIs Defaults (since 2.0.1)

Similarly to the OAuth redirect URIs mentioned above for non-OAuth flows like CSR impersonation that use redirects, there are now properties to configure post-auth redirect URIs:

broadleaf:
  auth:
    server-creation-defaults:
      my-tenant: # tenant id
        domain-default-post-auth-success-redirect-uris:
          - 'https://{domain}:${commercegatewayPort}'
          - 'https://{domain}:${commercegatewayPort}/'
          - 'https://www.{domain}:${commercegatewayPort}'
          - 'https://www.{domain}:${commercegatewayPort}/'
          - 'https://localhost:${commercegatewayPort}'
          - 'https://localhost:${commercegatewayPort}/'
        domain-prefix-default-post-auth-success-redirect-uris:
          - 'https://{domain}.localhost:${commercegatewayPort}'
          - 'https://{domain}.localhost:${commercegatewayPort}/'
        parameter-default-post-auth-success-redirect-uris:
          - 'https://localhost:${commercegatewayPort}?application={identifier}'
          - 'https://localhost:${commercegatewayPort}/?application={identifier}'
        context-path-default-post-auth-success-redirect-uris:
          - 'https://localhost:${commercegatewayPort}/{identifier}'
          - 'https://localhost:${commercegatewayPort}/{identifier}/'

User Mapping Properties (since 1.8.6)

  • customer-mappings: Defines additional attributes that should be mapped from a Customer to a User’s attributes. This is used when handling customer persistence events.

    • attribute-name: The attribute name where this field’s value should be stored in the User’s attributes.

    • value-path: The JSON path of the field on Customer from which to retrieve the value.

    • include-as-token-claim: Whether to also include the attribute as a claim on the auth token. The attribute name will be converted to snake case and used as the name of the claim: If the attribute name was phoneNumber then the claim would be phone_number.

      • Important: This property is only used if the attribute value is a string as other objects are not supported as claims.

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

Entity Resource Lock Properties (since 1.8.15, 2.0.1)

Property Description Default

broadleaf.auth.resource.lock.user-lock-ttl

Determines the amount of time that a user resource lock is held, before it expires. See com.broadleafcommerce.auth.user.service.autoconfigure.AuthenticationResourceLockProperties

5 seconds

OAuth2AuthorizedClient Cleanup Properties (since 1.8.15, 2.0.1)

Property Description

broadleaf.auth.user.web.authorization.authorized-client-entity-cleanup.*

Properties configuring the cleanup of OAuth2AuthorizedClientEntity from the datastore. See com.broadleafcommerce.auth.client.autoconfigure.OAuth2AuthorizedClientCleanupProperties for full list of options.

Authentication Strategy Delegate Properties Properties (since 2.0.1)

Property Description Default

broadleaf.auth.user.web.authorization.strategy-delegates.authentication-strategy-delegate.{delegate-property-key}.handle-external-admin-users

Determines if an AuthenticationStrategyDelegate should configure an ExternalAdminUserHandler bean to be injected. Out of the box delegate-property-key can be default-oidc, google, or github. See com.broadleafcommerce.auth.user.web.autoconfigure.AuthenticationStrategyDelegateProperties.

false