Single Sign On (SSO) Role Assignment and Contextual Security

Once you’ve got your Single Sign On (SSO) up and running, you will need to configure your role assignment via SSO and apply contextual security rules. 

There are a number of options available when setting up role assignments via Single Sign On (SSO), and as a One Model customer, your choice will be guided by; 

• Your rollout plan.
• The number of user groups within your organization, and;  
• How the permission needs of those user groups differ.  

If you have questions about the best option for your organization, please speak with your Customer Success Lead. 

Before you begin:

Ensure that you do not already have an existing Role Assignment configured, and you will need to have completed the following steps:

1. Your SSO is up and running. If you need help with your initial SSO configuration, please refer to the Introduction to Single Sign On (SSO) article. 
2. Configured the Application Access and Data Access Roles applicable to your relevant user groups. Check out our Role Based Permission articles for more information. 

How to set up your Role Assignment via SSO

Follow these steps: 

1. Navigate to the SAML 2 Integration screen. 

Go to the Admin tab, then select Company and scroll down to SAML 2 Integration. 

Click Edit at the top right of the SAML 2 Integration section.

• If the Edit button doesn’t appear to do anything, and you see the + Add SAML 2 Integration button as shown below, that means you don’t have SSO setup. Before continuing here, you will need to add a SAML2 Integration by following the steps in the Introduction to Single Sign On (SSO) article. 

2. Scroll down the SAML2 Integration section to Roles as shown below.

The options include:

1. Don’t automatically assign One Model roles based on SAML roles
2. Assign One Model roles based on SAML attribute named ‘roleid’
3. Assign One Model roles based on SAML attribute with a custom name 

1. Select Don’t automatically assign One Model roles based on SAML roles if you have no automated role assignment (i.e. you’re applying roles to users manually), OR if you are applying default roles for all new users. 

2. Select Assign One Model roles based on SAML attribute… if you are applying multiple default roles managed via SAML, OR if you are applying multiple default roles managed via CSV. The choice between ‘roleid’ and ‘custom name’ is dependent upon the SAML response attribute. If the SAML attribute  isn’t named ‘roleId’, then select the ‘custom name’ option and provide that custom attribute. More information is provided in the next sections.   

Option 1 = SSO + Default Roles

In this option, all new users are assigned the same default roles on first login. 

Leave the option selected for Don’t automatically assign One Model roles based on SAML roles. 

Click on None to open the list of Application Access and Data Access Roles. Now select the Application Access Role/s and Data Access Role/s that will be assigned to ALL users on first login. 

• If you do not see any Application Access or Data Access Roles, this means that you need to go back a step and configure your roles by following the instructions in these Role Based Security articles. 

If no roles are selected, i.e. roles stay as None, then a new user will be created upon their first login via SSO, but only granted access to the Home Page and you will need to assign roles manually. 

It is possible to have multiple Default roles. If you have contextual rules (more on that later) applied in your Data Access Roles, then the rule/s (combined with user person ID and relevant data hierarchy) dynamically control the data viewed by individual users. This means that Manager 1 only sees data for their team while Manager 2 only sees data for their team, and so on. 

The Default roles won’t likely suit every user. In these ‘user exception’ cases, after their first login is completed and user account created, an Admin can open the user account to manually change the roles, and those changes will be retained. Remember, the default roles are assigned on first login only. 

Note that if you need to make changes to the Default roles being applied, these will only be applied to any new users who login after you’ve made your changes. Existing users will retain their originally applied default roles and you will need to update their roles. 

Option 2 = SSO + Customer Role Mapping (Multiple Default Roles managed via SAML)

In this option, all new and existing users are assigned a set of default roles on every login. The roles are determined according to their specific grouping which is setup in the customer’s identity provider (IDP) and configured in One Model. 

You cannot operate option 1 and option 2 together. If one set of Default roles is sufficient for all users, then go for option 1. If there are multiple user groups with differing role permission requirements, then go for option 2 (or 3). 

This article gives all the details for setting up Multiple Default Roles managed via SAML, and the following is an example of what the completed Customer Role Mapping table in One Model (under Admin > Company > SAML 2) might look like. 

As you can see below, the default roles from option 1 are captured in a role group called Line Managers (the largest / default user group for this customer). They also have 3 other role groups, with different role combinations being assigned. The management of which employees / users belong to which role group all happens within the customer’s IdP, with the relevant roleid (or custom name) being passed through via SSO. 

Option 3 = SSO + File Based User Upload (Multiple Default Roles managed via CSV)

In this option, all new and existing users are assigned a set of default roles on every login. The roles are determined according to the details contained in a specific CSV template that is uploaded manually by the customer on an as-needs basis, as well as the customer role mapping table configured in One Model. 

This article gives all the details about File Based User Upload. The Customer Role Mapping table in One Model will look similar to the one shown in option 2. So first, here’s an example of what a few rows of the CSV file might look like. In this case, the Admin user (Bob Smith) is not part of a role group. He has the additional permission of local sign in (username and password) and no automated role assignment. His Admin permissions can be assigned manually at the user level. Jane and Simon are part of the Executive group, Steve is a HRBP, and Beth is a Line Manager and HRBP.

The accompanying role mapping table would look like this

If you need assistance with testing or have any questions about Role Assignment, please chat with your Customer Success Lead. 

What about Contextual Security?

Contextual role based security is one of the great features of One Model as it allows for dynamic, flexible, permission-based access that drives self-service and a seamless user experience. 

Contextual security is managed by a data access rule based on an individual’s position in the data; typically their position in the organization hierarchy or supervisor hierarchy which restricts a user to only see “their” part of the organization or “their” reports down the supervisor hierarchy. 

As a new customer, you will start with a small group of Admin users whose user accounts are created manually and these Admins will get full access to all functionality and data where no contextual security is required. However, when you start thinking about your roll-out plan, and the permission requirements for your user groups, that’s when you will want to implement contextual security.

Contextual security will work with any of the three Role Assignment options outlined in the previous sections, it also works without SSO or Role Assignment. There are a few components to consider as detailed below, but if you are ready to set up contextual rules then you can jump straight to this article about Contextual Security Rules in Data Access Roles.  

Let’s look at each of the components:

1. SAML 2 Integration (SSO)

When you set up your SSO in the Company settings (read about it here), you will configure the Person ID.  

The Populated field is found on the individual user account which is found under the Admin tab>Users>Name of user. In the example below, we can see the User - Franco Smith. 

With Don’t populate Person ID selected in SAML 2 Integration, as an Admin, I can manually create a user - like Franco - and manually enter the unique employee ID that identifies their position in the data. While this may be an easier option initially, this quickly becomes unsuitable long-term as creating many individual users is time-consuming and prone to human error. 

With Populate Person ID with SAML NameID or Populate Person ID with SAML Attribute selected, when a new user logs in via SSO, the information being passed from the customer IDP to One Model includes the Person ID (as a NameID or Attribute) will automatically create a new user account AND populate the Person ID. This is a much easier option than manually creating users. 

2. User Contextual Rules Configuration

Also in the Company settings there is a section called User Contextual Rules Configuration which is separate to the SAML 2 Integration section. Your Customer Success Lead will help set this up initially. 

This configuration defines where in the data we find the matching ID. In this example, the ID is in the one.employee_contextual table in a column called person_id. 

Note, the Employee ID Column does not have to be person_id, it could be user_id, employeenumber or any other unique ID field, as long as it is the field to give us the matching value of “1209457” for our example user, Franco Smith. 

The Use Additional Filter field may be selected on legacy configurations (using a one.employee table) but is not required for one.employee_contextual tables. 

3. Data Access Roles - Contextual Rules

With the Person ID in the user account and the User Contextual Rules Configuration saved, you are at the final step to enabling contextual security. 

As mentioned above, contextual security is designed for users who need some kind of restricted data access, like a Manager viewing data for their reports only (rather than full data access like an Admin user). If Franco is a Manager, you will want them permissioned to a Data Access Role with a User Contextual Rule applied. 

If we take the Business users data access role from our Role Assignment options above, you can check for contextual rules by going to Admin > Data Access Roles and then click on the Rules link for Business users. 

If the rule is already set up, you will see a description of the contextual rule being applied to any user with the Business users role. It doesn’t matter whether that role is applied manually at the user level, via the Default roles, via SAML or CSV, this rule is telling the system to only give Franco access to data that relates to his Supervisory Org and the descendants of that org unit (as determined by his person ID and link to the employee table).  

If you need help to set up the contextual rule, there’s a great video walkthrough here.

When a role with a contextual rule is permissioned to a user, their user account will have a message added as a reminder that a Person ID is required. If the Person ID is missing, or doesn’t exactly match to the ID in the field defined in the User Contextual Rules Configuration, then the user will have NO data access. 

We recommend testing contextual security before roll out and please speak with your Customer Success Lead if you have any questions.