# Claims-based identity provisioning: users, Account access and user groups
## Claims-based Account access and User Group provisioning in Exivity
In the case of large organizations with a large number of users that log in through SSO, giving [Account](https://olddocs.exivity.io/reports/accounts) access to each one of them or assigning them to a [group](https://olddocs.exivity.io/administration/user-management/groups), quickly becomes an intensive manual labour. To avoid this, Exivity implemented a mechanism that automatically assigns appropriate permissions to SAML2 users. For example, users will have [Metadata](https://olddocs.exivity.io/data-pipelines/metadata) applied (such as *Security Groups* memberships), which could be leveraged to automatically give each user access to the appropriate *Account(s)* in Exivity. Apart from Account level Access, the Exivity Group membership can also be provisioned automatically, without the need for any manual intervention from an Administrator.
## Claims-based identity & SAML2
A claim is a statement that one subject, such as a user or organization, makes about itself. For example, the statement can be about a name, group, privilege, association or capability. Claims are held in an authentication token which is then used to authenticate against multiple applications. Apart from enhanced security, a claims-based identity has the potential to simplify authentication logic for large amounts of users that require account provisioning and configuration across multiple applications.
SAML works by exchanging user information, such as identifiers, and other relevant attributes between the Identity Provider (IdP) and Service Provider(SP). As a result, it optimizes and secures the authentication process as the user only needs to log in once with a single set of authentication credentials. When the user tries to access a website (SP), the IdP passes the SAML authentication to the SP, who then grants the user entry and access to its resources. The diagram below exemplifies the SAML2 flow between Exivity and the IdP:
## Tutorial: configure claims-based identity and Account access provisioning
{% hint style="warning" %}
This feature is currently in Beta, so make sure to [enable Beta features](https://olddocs.exivity.io/administration/settings#enable-beta-features) in order to configure claims-based access provisioning.
{% endhint %}
{% hint style="info" %}
For demonstration purposes, this tutorial uses [OneLogin](https://www.onelogin.com/) as an Identity Provider.
{% endhint %}
This tutorial is divided into three main sections:
1\) [The configuration of a OneLogin account to integrate SSO with Exivity](#part-1-configure-onelogin).
2\) [The configuration of your Exivity instance, so that it can be used as a Service Provider](#part-2-configure-your-exivity-instance).
3\) [The necessary configuration to automatically provision users with Account access and assign them to User Groups based on a claims-based identity.](#part-3-configure-the-saml2-attributes-for-claims-based-identity-provisioning)
{% hint style="success" %}
If you already have an SSO configuration enabled and configured, you may be interested only in the 3rd part of this tutorial, therefore skip sections 1 and 2.
{% endhint %}
### Part 1: Configure OneLogin
1\. In order to use OneLogin as an Identity Provider, you need to set up a new application. To do so, navigate to the OneLogin administration, hover over **Applications** in the navigation bar, and click on **Applications***:*
2\. Click on the **Add App** button in the top right corner:
3*.* In the list of applications, search for "saml" and click on the item *SAML Custom Connector (Advanced)*:
4\. Provide a meaningful name for your app, then click **Save**.
5\. Click the **Configuration** tab. You will notice there are some fields to configure:
The required information to fill in these fields can be found at the **Administration** > **Settings** > **Single Sign-on** > **Endpoints** section in the Exivity GUI:
Follow this mapping between OneLogin and the Endpoints:
6\. After filling in the fields, click the **Save** button in the top right corner.
### Part 2: Configure your Exivity instance
1. Now, you have to copy and paste some values from the OneLogin application into the Exivity instance Single Sign-on settings. In OneLogin, click on the **SSO** tab:
2\. In a separate browser tab, open the Exivity GUI. Navigate to the **Administration** > **Settings** > **Single sign-on** menu and select the **SAML** tab. Copy over the following settings from OneLogin with this correspondence:
3\. Now, let's set up the OneLogin certificate in Exivity. In the same **SSO** tab in OneLogin, under the label *X.509 Certificate*, click the **View Details** link.
4\. Copy the X.509 Certificate and paste it in the *X-509 certificate* field in the Exivity *SAML* settings:
5\. Click **Update** to apply your new settings.
6\. You also need to add the OneLogin domain for your organization to the [CORS](https://olddocs.exivity.io/security/security#cross-origin-resource-sharing-cors) whitelist as well. Navigate to the **System** tab in the **Administration** > **Settings** menu and add your domain in the *CORS origins* field.
Your domain may look similar to: `https://`*`name`*`.onelogin.com`
{% hint style="success" %}
Make sure to separate the CORS origins domains with a comma.
{% endhint %}
7\. Click **Update** to apply your new settings.
### Part 3: Configure the SAML2 attributes for claims-based identity provisioning and Account access
1. Navigate to the **Administration** > **Settings** > **Single sign-on** menu and select the **SAML** tab.
2. Scroll down to the *User Provisioning*, *User group* and *Account Provisioning* sections. You will notice that for each section you can fill in some *attributes*.
{% hint style="warning" %}
If you don't see the aforementioned sections, it might be that you haven't [enabled Beta Features](https://olddocs.exivity.io/administration/settings#enable-beta-features).
{% endhint %}
In order to understand the attributes in a SAML2 response and the configuration that we have to do, it's important to understand the following workflow, which describes the communication between a Service Provider and an Identity Provider:
{% hint style="success" %}
1. The user opens their browser and navigates to the Service Provider's web application (In this case, Exivity), which uses an Identity Provider (In this case, OneLogin) for authentication.
2. The web application responds with a SAML request.
3. The browser passes SAML request to the IdP.
4. The IdP parses the SAML request.
5. The IdP authenticates the user by prompting for a username and password or some other authentication factor. *NOTE*: The IdP will skip this step if the user is already authenticated.
6. The IdP generates the SAML response and returns it to the user's browser.
7. The browser sends the generated SAML response to the Service Provider's web application which verifies it.
8. If the verification succeeds, the web application grants the user access.
{% endhint %}
Assume there is a user called *Foo* who is a member of the AD (Active Directory) group: ***group2***. After *step 7* in the above example, the SAML2 response in an XML format may look like this:
```
anca@exivity.com
group2
```
{% hint style="info" %}
In the SAML2 response, we can observe that there are `Attribute Names` and `Attributes Values`. \
We are interested in the attribute name that holds the ***group2*** value. In this case, the attribute name is *Department*.
{% endhint %}
\
3\. In order to provision [Account](https://olddocs.exivity.io/reports/accounts) access based on claims (for example, the user *Foo* is part of a group), you must [create a Metadata](https://olddocs.exivity.io/data-pipelines/metadata#step-1-defining-metadata-fields) definition and [associate it with the Account(s)](https://olddocs.exivity.io/data-pipelines/metadata#step-2-associate-metadata-to-report-levels) that you want to be accessible for the user(s) which are part of that group.
Consult the [Metadata](https://olddocs.exivity.io/data-pipelines/metadata) article for a detailed guide about how to create a metadata definition and link it to an account.
\
4\. In this tutorial, we configured a custom Exivity Metadata Field *"Azure AD Security Group"* and set this value for the Accounts *"Manufacturing", "Marketing"* and *"Retail"* to ***group2***.
  
5\. In your OneLogin configuration screen, navigate to the **Parameters** tab and click the **+** button to add *Attributes*. In this case, we added an Attribute named "Department":
To test our claims-based Account provisioning scenario, we must assign a value to the Department attribute. To do that, open the **User** tab, click on your user and add your prefered value to Department. In this case, we want a user who is part of the ***group2***, in accordance with the Metadata value we configured earlier:
6\. In the *Account provisioning* section mentioned earlier, this definition must be mapped by filling in the fields:
In the picture above, the SAML attribute "Department" is checked against the metadata field "Azure AD Security Group". If the values of these two keys match, then the user will receive [Account](https://olddocs.exivity.io/reports/accounts) access to that/those Account(s) that are connected to this Metadata definition.
The following diagram illustrates how the mapping between user attributes and metadata fields works when doing claims-based Account access provisioning:
If the user's claims (i.e. the attributes in the SAML2 response) don't match any of the Metadata values assigned to one or more Accounts, then the user will not receive access and visibility to those Accounts, unless an Administrator configures it manually.
### Account key vs Metadata
If you select **Account Key** instead of Metadata, then the attribute value will be matched against every Account with that name. For example, if we would have selected Account key with the same *Department* attribute (whose value we know is equal to ***group2***), then the user/s would get access to all the Accounts that are named ***group2***.
7\. Now that you know how the mapping of SAML2 attributes works, fill in the details for the *User Provisioning* and *User Groups* settings with the corresponding SAML2 attributes:
{% hint style="info" %}
*Note*: These attributes here are specific to OneLogin. For other Identity Providers, they might differ.
{% endhint %}
The *User Provisioning* attributes have the purpose of assigning a relevant *name*, *email* and *display name* when an SSO user logs in for the first time.
The *User group* attributes have the purpose of assigning the user to the right group, if it has been sent through a SAML2 attribute. For example, in the picture above, if *MemberOf* = *managers*, then the user would be assigned to the Managers group. Otherwise, it will be assigned to the Default chosen group.
8\. Click **Update** to apply your changes.
9\. Finally, we can test our automatic Account access provisioning. Enable Single Sign-On in Exivity by navigating to **Administration** > **Settings** and then clicking on the **System** tab. Make sure the *Single Sign-On* option is set to an option including *SAML2 Authentication:*
10\. Click **Update** to apply your change.
11\. Log out of the current session and you will be redirected to the login page which may look like this:
12\. And by clicking on the **Login** button, you'll be taken to the OneLogin login screen.
13\. After logging in, we can observe that the user only has access to the Accounts *"Manufacturing", "Marketing"* and *"Retail",* as expected*:*
  
Depending on which Metadata fields you configured (for example a *Security Group*), you will observe that your user(s) whose claims/attributes match with the metadata fields, automatically received access to one or more Accounts, eliminating the need for manual configuration.