- Log in as an administrator to your okta.com account.
If you aren't in the Admin section then click "Admin" in the masthead.
- Go to "Applications", and then search for "Brandworkz" to find us in the Okta App Integration Catalog dropdown. Click Brandworkz in the dropdown.
- On the Brandworkz page click "Add"
- On the General Settings page you can change the name from Brandworkz to something else if you have given your Brandworkz instance a custom name. Hit Done.
- Switch to the "Sign On" tab and click Edit.
- Scroll down the page and click on "View Setup Instructions".
Follow these setup instructions and your base SSO setup should now be done.
- Switch to the Assignments tab and asset the app to yourself, and of course if you already know which groups of your Okta users should see the Brandworkz app then also assign it to those groups now, otherwise do this later.
- Time to test out your connection!
Log out of Brandworkz (or test in an Incognito window or different browser)
Back in Okta go to "My end-user dashboard" (or "My Apps" depending on which version you are on)
- Click the Brandworkz app tile
You should now be signed in to the Brandworkz homepage.
Please note: Brandworkz will do auto-provisioning of users. Also note that it will allow creation of users beyond your licensed limit. If the limit is exceeded then we will of course notify your Brandworkz sysadmin about this.
After the initial setup is complete there will most likely be various tweaks you - or your Brandworkz sysadmin - will want to make to both sides of the equation, e.g. send through Group names to Brandworkz and map these to permission groups, change the name of the SSO button and description etc.
Please see the tooltips on the Brandworkz SAML edit page for further options.
Mapping Okta group names to Brandworkz permission groups
Brandworkz has the capability to map your Okta groups to correspondingly-named Brandworkz permission groups. Okta also has the ability to pass through AD groups if you have your Okta connected to Azure and/or AD so if you have this, you can indirectly also pass through your user's AD group memberships through Okta although this is beyond this article.
In the first instance, as the Brandworkz admin, get together with your organization's Okta admin and discuss with him/her if/how your end-users are member of relevant groups in Okta and if these groups also make sense for your Brandworkz install. For instance, users in Okta may be assigned one or more of these groups "Sales", "Marketing", "Administrative".
It could also be that you have geographical groups such as "EMEA", "APAC", "US".
If these group memberships also make sense in terms of corresponding Brandworkz permissions, then the Brandworkz sys admin should set up Brandworkz groups with names that EXACTLY matches the Okta groups you would like to map end-users to when they log in.
Note that as mentioned previously in the setup, even if you have these matched, you must have a Default Group assigned as well in case an SSO user logs in which isn't a member of any of the groups that you are mapping to. This should be a group with minimal permissions - typically read-only - which works for all SSO users regardless of who they are.
Note the following in relation to groups (see screenshot above):
If you have "User details update" enabled on the Brandworkz SAML screen then on each login the users details will be updated, e.g. if they have changed surname. If their group membership in Okta has updated then this will also be updated in Okta. However, you as the Brandworkz admin may not want this to update if you are planning to assign certain SSO users to additional/custom groups beyond their SSO groups. If you would like their personal details to update but not their group memberships, then click Enabled under "Do not overwrite groups on subsequent logins".
In terms of Okta config for group mapping then do the following in the Application setup do the following:
- As an Okta admin go to the Brandworkz application → General Settings - SAML → Edit
- Hit Next on the initial screen
- Under group attribute statements create an attribute called "groups" (basic) = Matches regex: .*
This will send through all of the group names which the current user is a member of and on login this user will be assigned to any correspondingly-named groups over in Brandworkz.
Note that there are lots of options in Okta to limit down the names of the groups that are sent through the various filters and RegEx options, as well as passing through linked AD groups, but this is beyond this article.