Azure AD SSO SAML Setup

This article explains how to set up an SSO connection from Azure AD to Brandworkz.

Note that there are a number of different editions of Azure AD, so the screens you see may vary from the ones below, and your organization may have implemented custom policies and working practices that will require you to adapt the steps below. Also, note that while we support regular Azure AD, e.g. the one which comes included with Office 365, you ideally need one of the premium versions or have it connected with an AD so you can enforce reauthentication at least once per week.

When setting up a connection, the Azure AD setup needs info from the Brandworkz SSO setup and vice versa.

You should set up the Azure AD connection first with some of the required fields left empty, then set up the Brandworkz SSO configuration, and finally going back to Azure AD to import the remaining values from the Brandworkz configuration which is done simply by uploading a metadata XML file.

Azure AD set up - part 1

As a prerequisite you should:

1. Install the Microsoft My Apps Secure Sign-In Extension browser plug-in which is available for Edge, Chrome and Firefox. This will make it easier to test/troubleshoot the connection once set up, and the below assumes that you have this installed.
2. Ensure that the Microsoft account you use is either a Global Admin or Application Admin+Conditional Access Admin, otherwise you will not see the "Enterprise applications" menu entry which you need and you won't be able to access Conditional Access which you also need. If you don't see this menu entry in the below steps or if you don't have any admin access to Azure AD at all, then you need get the appropriate person in your organisation to do the below. 

Set up Brandworkz as a non-gallery enterprise application in Azure AD:

1. Go to Azure AD: https://aad.portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Overview
2. Go to Enterprise applications → New Application → Create your own application
3. Give your app a name, e.g. Brandworkz - <nameOfSite>
4. Keep this radio button selected "Integrate any other application you don't find in the gallery"
5. Click Create

Before you start the SSO part, you need to assign yourself as a user of this new app:

1. Go to Users & Groups → Add user 
2. Click on None Selected to get the user listing
3. Find yourself in the listing, and hit Select
4. Then hit Assign to assign yourself to the application

Once the connection is finalised you will need to come back to this section and assign the appropriate users/groups who should have access to Brandworkz.

Please note: Brandworkz will auto-provision all users who it is sent a valid SAML assertions for, including setting up users taking your beyond the user licence you have purchased. This is in order to provide the end-users with the best experience and not potentially rejecting them with a "out of licences" message.
Therefore, you should limit the number of people who have access to SSO to Brandworkz to match the user licence you have purchased. Any overate will be resolved at quarterly client meetings.

Next choose Single sign on and then choose SAML

You should now see this screen:

There are five numbered sections on the main SAML config screen above:

1. Basic SAML Configuration section
   Leave this section as-is for now, you will populate it later via importing a metadata XML file later.
2. User Attributes & Claims section
   This is the section where you decide which user attributes you are going to send through in the SAML assertions.
   
   If you are using "default" Azure AD - i.e. not customised and not connected to an on-premise AD you should be able to simply skip this step for now and go to step 3 to get the connection going and you can then come back and do further configuration of this later.

In the Brandworkz SSO config you can map any Claim name to the corresponding Brandworkz user attribute including custom Brandworkz user attributes. However, the below describes a typical base configuration sending through mandatory claims:

• Click Edit
• Required claim
  Unique User Identifier (Name ID): This is the claim we will use for the main login name when setting up a user. You may well have a corporate standard for how to send this through already and you should then use that. Note that a typical config is a format of Email Address (aka EMAIL) and a source attribute of user.userprincipalname.
• Some companies may have their main unique user ID as e.g. a number for each person. We do not recommend using this as the name identifier as there are various places in the UI where this shows up so it will be better if the value sent through is something that is unique but also identifies the person by name, e.g. their email address.
• Optional claims
  By default a new connection will give you these: emailaddress, givenname, surname and name/userprincipalname - in the namespace of http://schemas.xmlsoap.org/ws/2005/05/identity/claims
  Brandworkz must be supplied with emailaddress, givenname and surname so leave those in place, although of course if you store your users' email, first name and surname in different claims/name spaces then add those instead and you can then map those during the Brandworkz SSO config.

Also see the Optional Claims / User Attributes section further down for for various other optional claims you can send through.

    3. SAML Signing Certificate section

This may already be showing a certificate if you have set one up for another SAML connection in the past. If yes then leave this as-is. If this box says "No certificate exists...." then click Add a Certificate, leave all defaults as-is (unless you have special corporate requirements around certificates), Click New Certificate, then click Save, and close the pop-up.

Once a certificate is configured, you need to download both of these:

• Certificate (Base64)
• Federation Metadata XML

Note that if you don't have any "Download" links showing up then refresh your browser and go back into the SAML section for the app.

    4.  Set up... section
You will need the values shown here in the next section so leave your Azure AD browser window up and go to the next section.

    5. Test section
Don't test the connection yet, it won't work until you have completed the below setup, just leave this screen open for completion later.

Brandworkz SSO set up

In a separate browser tab log in as a sysadmin to your Brandworkz application and go to Settings → Single Sign on (/bms/admin/saml)

    1. Click on Add new connection

    2. Click on Azure AD

• Core Service Settings section
  • Connection Name: typically just call this Prod or QA depending on whether this is your production/live Brandworkz instance or your test/QA instance. However, if you have multiple Azure AD accounts that needs to be connected to your Brandworkz instance then you need to name them uniquely.
  • Service Provider Endpoint: Leave as Brandworkz Web-App - Note that this option will be retired soon and may not show up for you
  • Service Provider ID: auto-generated.

• Identity Provider Settings section 
  • Identity Provider ID: Temporarily switch to your other browser tab with the Azure AD SAML connection detail and copy the "Azure AD Identifier" value - it typically starts with "https://sts.windows.net..." - and paste it into this field
  • Identity Provider Metadata Endpoint: This doesn't work well in combination with Azure AD so leave this empty and instead use the two fields below
  • Identity Provider Metadata XML: Temporarily switch to your Azure browser tab and hit the Download button next to Federation Metadata XML. Open this XML file in a text editor and copy-paste all of it into this textarea.
  • Identity Provider Certificate: Again, switch to your Azure browser tab and download the certificate from the Certificate (Base64) download link, open it in a text editor and copy-paste it into this field.

Note that if you change anything in the Azure AD config or if you refresh your certificate then you will have to re-download it and paste the XML and/or certificate into the Brandworkz config again.

• Login and Logout section 
  • For now just leave these settings as-is. When the connection is established you can come back and tweak these settings.
• SAML Attributes section 
  • For now you can leave most of these settings as-is to get the connection established.
  • However note the following: 
    • Login Name/NameID and type - called "Unique User Identifier" in Azure AD: If your company already uses Azure AD for other cloud apps then you will typically have set a company policy for which attribute you use as the unique identifier for a user. Many companies go for EMAIL. This should match whatever you chose under Claims for this field in the Azure AD setup.
    • User Details Update: Brandworkz will auto-provision new users previously unseen to the system and of course use the attributes to set up this new user. If you would like Brandworkz to check for any changes to the attributes every time an end-user logs in and update the user profile with any changes then check this button. This could for instance be if somebody changes their last name after getting married, or their group membership changes. Note that if you enable this and you don't have auto-group assignment then you will highly likely want to tick Do not overwrite groups on subsequent logins further down under groups as the Brandworkz admin may well have added various SSO users to additional groups manually.
    • Group: You need to set a Default Group, typically a read-only group giving only the minimum permissions which you are OK with all SSO users having. The Default Group works in two different ways depending on whether you are passing through a Group claim: 
      • If you aren't passing through a group claim then ALL new users will be assigned to the selected Default Group. Once an SSO user has been auto-created in Brandworkz you can then optionally go to the properties of that user and assign them to further permission groups, although note that if you are planning to do this then you must enable "Do not overwrite groups on subsequent logins" as otherwise their permissions will be reset on their next login.
      • If you are passing through a group claim (default name is "groups" but you can change it here) then users whose SAML assertion contain a group value(s) which match the name of a Brandworkz permission group(s) will get assigned to this group(s). If there are no matches, then the user will get assigned to the Default group. For instance, imagine that you have set up three Brandworkz permission groups "Default User", "Sales" and "Marketing". This is what will happen in terms of group assignment in a variety of scenarios depending on what a user has as their Group value in the "groups" claim:

• Tip: If you would like ALL users to always be part of a default group, even if there is a match for them on a specific group as well then see instructions in how to achieve this through your Azure group config below under Optional Claims/attributes → Group. 

• Security section 
  • Only tick Force re-authentication... if you would like users to re-authenticate on every login even if they are already logged in to your IdP system. This should typically not be ticked as it gets annoying for end-users and we recommend only ticking it if you have highly sensitive material stored in Brandworkz.
    However, note that you must at your IdP end force re-authentication at least every 24 hours - rising to 7 days in Brandworkz v8.6.1 - as otherwise the SAML assertions will be rejected. See more on this in Azure AD set up part 
• Click Save
  • Note that if you see an error on Save then go back to /bms/admin/saml/ and the new connection should be set up successfully regardless of the error.
  • You should now see the new connection on the SAML overview page. Go back into this connection by clicking on it's name and download the Brandworkz metadata XML by clicking on the "Download Brandworkz Service Provider metadata XML" link.

Please note: It may take a minute or two for our SSO system to generate the XML after the connection is set up, so if the download doesn't work then you go back into the config screen, then wait a couple of minutes and try again.

Azure AD set up - part 2

1. Switch back to your Azure AD browser tab where you should still be on the SAML config page for your Brandworkz app.
   
   
2. Click on Upload metadata file and upload the XML file you just downloaded in the previous step. It will be named "saml-provider-metadata....xml"

After upload this will open the Basic SAML Configuration section and the relevant fields should now be auto-filled with the correct information.

    3. Hit Save and close the pop-up

The main configuration is now complete but there are a couple of further items to complete on Azure AD which are:

1. Download the Brandworkz app icon from here: https://www.brandworkz.com/wp-content/uploads/2020/11/1-Brandworkz_Mark_RGB_Neg_DarkBackground.png and go to your Azure application's Properties and upload it for that final branded touch! (note that it can take up to 24 hours for this icon to show up on https://myapplications.microsoft.com/ )
2. Ensure that end-users are forced to re-authenticate at least once every 7 days. If you are using regular Azure AD you can't do this after Jan 2021 as Microsoft is pulling that feature (read more about that in this MS article), so you will need to have the Premium editions where you can configure this via Conditional Access, or have it linked with AD Connect. If you are not already forcing users to authenticate at least once per week for all apps, here is how you can set that up for the Brandworkz application. 
   • Still in the context of the Brandworkz Enterprise Application go to Security → Conditional Access
   • click New Policy
   • On the New setup screen:
   • Name: e.g. Brandworkz force re-authentication every week
   • Assignments: 
   • Users and groups: select All users
   • Cloud apps or actions: Leave as just the Brandworkz app
   • Conditions: Leave empty
   • Access controls: 
   • Grant: Leave empty
   • Session: Tick Sign-in frequency and select 7 and Days
   • Click Select
   • Enable policy: Switch it to On
   • Click Create

Now it's time to test the connection so go back to the "Single sign-on" section and hit the Test button and select Sign in as current user 

...or indeed as someone else, but remember that if you do that they need to be added as a user to the app first.

Hopefully the connection is successful, if yes then GREAT - if not then Azure is pretty good at telling you what might be wrong.

You may also want to go back and revisit the Brandworkz SAML settings for the connection to see if there are any other settings to be tweaked, typically in conjunction with your organisation's Brandworkz sysadmin.

Finally, once everything is working AND if your Brandworkz Admin has finalised configuring and populating the system, you also need to go and assign the appropriate users/groups to the Brandworkz app so they can access it, either through Users & Groups, or if you have purchased an enterprise-wide licence of Brandworkz for all employees then you can alternatively go to the main Properties for the app and disable User assignment required to let all employees have access

Optional claims / user attributes

Apart from the mandatory claims mentioned above in the setup, Brandworkz can also optionally populate these user properties if they are passed through as claims, as long as you have these populated for the majority of your users in your directory. The claim name for each of the below can be whatever you like as you can map these in the Brandworkz SSO setup:

BWKZ user property	Notes
telephone	Any string
language	This is used to control the default UI language on multi-language sites. The language values must match languages set up in Brandworkz.
country	If you are a multi-country or global company then this may be useful to store against the Brandworkz user record so the Brandworkz admin can see which country a particular user is in. The names passed must match the list of built-in country names in Brandworkz - see the "country" field dropdown on the Brandworkz SSO setup screen. Note that if you are exclusively using Azure AD for your user directory, i.e. not connected to an on-premise AD, then the user.country field will not send through country names but country codes like GB for Great Britain, ES for Spain and so forth. Therefore, if you are using user.country to store the location of your users, you need to apply a transformation for each of the countries where you have users for this to match the Brandworkz country list. See screenshot below:
group	Used to automatically assign a user to a specific Brandworkz group when setting this user up through auto-provisioning. Note that the names of the Brandworkz groups MUST exactly match the group names you are sending through in this claim, and if you are sending through multiple group names, they must be semi-colon separated. Also note that you can not do this if you only use Azure AD as this will only send through it's own group GUIDs. However, if you have your own AD connected to Azure AD using AAD Connect Sync 1.2.70 or above, then you have further options for achieving this, but don't do this on initial setup as it will complicate any troubleshooting. Note however that if you want to base each user's Brandworkz group membership on an AD field with only one value, e.g. user.department, then you can do this with Plain Vanilla Azure AD. Also, if you would like to assign all users to a default group AND another group/field - e.g. user.department - then you can achieve this by setting up a claim transformation like so: Prep in Brandworkz: Also set up permission groups with names which exactly matches each of the department names in the user.department field and assign additional permissions to these groups. Go to Azure AD → Enterprise Applications → The Enterprise app you have set up for Brandworkz → SAML-based Sign-on → User Attributes and Claims: Click Add new claim   Call it "groups" and click on "Transformation" under Source: Enter the four values as per the screenshot below:  Save the new claim:  This "groups" claim will now contain a list of the fixed "general users" and the current user's department, e.g. "general users","sales" so the user will now get assigned to both the fixed/default group and the group matching their department's name.
custom Brandworkz user field	If you have custom fields not in the above list which you would like to populate to custom Brandworkz user fields then you first need to set these up in Brandworkz, get the systemrefs for these and send them through with the same claim name as the Brandworkz systemrefs. There is more info on this on the Brandworkz SSO setup screen but don't do this on initial setup as it will complicate any troubleshooting

For reference, your Azure SAML screen should look something like this when it's fully set up:

Troubleshooting

If you see this error when trying to log in to Brandworkz via SAML: 

"Sorry, but we're having trouble with signing you in". AADSTSS0105: The signed in user 'xxxxx@xxxx.xxx' is not assigned to a role for the application 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx' (Enterprise app name)

You have most likely not given yourself permission to the Enterprise App for Brandworkz so Microsoft will not send the SAML assertion to us.

Scroll up to the "Azure AD set up - part 1" section above and see the "Before you start..." section for instructions.

After following the above steps, the SAML login to Brandworkz still doesn't work or only partly works raise a support ticket with us describing what you are trying to achieve, how much of it is working and which specific parts aren't working.

Also, when raising a support ticket please send us an example of the SAML assertion you/Azure AD are sending.

To generate a test assertion do the following:

•    log in to Azure AD and go to the Enterprise App you have set up for Brandworkz

•    Click on "Set up single sign on"

•    Scroll to the bottom and click the Test button

•    Click "Sign in as current user" (or as someone else more relevant who you have the credentials for and who have permission to this app)

• When you hit the Sign in button your browser may switch to a new tab which it opens with the Brandworkz login screen on. If this happens then switch back to the Azure AD window
• Click on "Download the SAML response" (which is the assertion your Azure AD is posting to us) and attach it to the Brandworkz support ticket.

Note that this screen might also help you troubleshoot the issue yourself if it's to do with Token Claims/Properties. Expand "Token Claims" and you can easily see which claims you are sending through so you can then e.g. see if these field mappings are set up correctly over in the Brandworkz SSO screen.