# Users and Permissions

## How users and groups of users are organized in Flexible Intake <a href="#how-users-and-groups-of-users-are-organized-in-flexible-intake" id="how-users-and-groups-of-users-are-organized-in-flexible-intake"></a>

When you first have access to a Flexible Intake platform, you begin with a single sign-in identity that has complete access to all services and resources in the account. This identity is called the Administrator and is accessed by signing in with the email address and password that you provided. This user is capable of creating other user or group accounts as needed.

{% hint style="info" %}
We strongly recommend that you do not use the Administrator user for your everyday tasks, and keep it only for the higher-level activities.
{% endhint %}

### User accounts <a href="#user-accounts" id="user-accounts"></a>

A user account represents the person or service who uses the account to interact with Flexible Intake. A primary use for user accounts is to give people the ability to sign in to the Flexible Intake Management Interface for interactive tasks and to make programmatic requests using the API.

A user in Flexible Intake consists of a name, a password to sign in (or an identifier of an external identity provider, if using _Federated Identity_) and:

* _Several access keys and credentials_ to access the different Flexible Intake services (such as the API, the S3 protocol server, etc.).
* _Platform permissions_: Permissions to perform certain actions or to access certain platform elements.
* _Content permissions_: Permissions to see or change data containers and archival nodes in the Archival Structure.

When you create a user, you grant it permissions by making it a member of a group that has appropriate permission policies attached (recommended), or by directly attaching policies to the user.

### Groups <a href="#groups" id="groups"></a>

A Flexible Intake user group is a collection of Flexible Intake users.

You can use groups to specify permissions for a collection of users, which can make those permissions easier to manage for those users. For example, you could have a group called _Researchers_ and give that group the types of permissions that researchers typically need.

Any user in that group automatically has the permissions that are assigned to the group. If a new user joins your organization and should have similar privileges, you can assign the appropriate permissions by adding the user to that group. Similarly, if a person changes jobs in your organization, instead of editing that user's permissions, you can remove him/her from the old groups and add him/her to the appropriate new groups.

### Permissions <a href="#permissions" id="permissions"></a>

Two types of permissions exist:

* Permissions governing access to the content (**content** permissions): Used, for example, to limit what data containers or content a user or group of users are allowed to see.
* Permissions governing the actions in the platform (**action** permissions): That include, for example, if a user is able to configure the lifecycle settings, storage configuration, etc.

Permissions can be assigned to users or groups. Assigning them to groups usually makes the management easier, and it is the recommended way.

## Managing users and groups <a href="#managing-users-and-groups" id="managing-users-and-groups"></a>

### Using the Management Interface <a href="#using-the-management-interface" id="using-the-management-interface"></a>

1. Sign in to the Flexible Intake Management Interface
2. Select **Configuration** (1) and then **Users or Groups** (2), depending on what you need to do.

![](https://gblobscdn.gitbook.com/assets%2F-MVFE6MnOK93sACDCxxx%2F-MY19b2P-seWyiYq-mYy%2F-MY1A35J_bQhSX16MU-6%2Fimage.png?alt=media\&token=0ceedcc9-7fbd-4328-a494-9fee58ec27a4)

#### For groups <a href="#for-groups" id="for-groups"></a>

In **Groups**, you can add new groups selecting Add Group in the menu and introducing the group name and description.

![](https://gblobscdn.gitbook.com/assets%2F-MVFE6MnOK93sACDCxxx%2F-MY19b2P-seWyiYq-mYy%2F-MY1E7PqtzjOX66syITt%2Fimage.png?alt=media\&token=6357bdf3-536a-49ff-8036-c1ffac64f81c)

When the group has been created, you can edit it and then modify the **Platform Permissions** for the group by selecting **Permissions**.

![](https://gblobscdn.gitbook.com/assets%2F-MVFE6MnOK93sACDCxxx%2F-MY19b2P-seWyiYq-mYy%2F-MY1EZDeN3fsYXtYMMMA%2Fimage.png?alt=media\&token=d404add9-c16c-4f9b-90dc-6845a9e834eb)

​

#### Creating a user account <a href="#creating-a-user-account" id="creating-a-user-account"></a>

In **Users**, you can add new users selecting **Add user** and then, indicating the following details:

![](https://gblobscdn.gitbook.com/assets%2F-MVFE6MnOK93sACDCxxx%2F-MY19b2P-seWyiYq-mYy%2F-MY1AhwvTNE9JAu0ft1U%2Fimage.png?alt=media\&token=ff433d42-45ac-49aa-91e2-d7df0cc024bd)

In the **Auth Type**, you can select **Password** when you do not want to use an external Identity provider or **Identifier**, if you want to use a 3rd-party Identity Provider to manage the user log-in. See how this is obtained in [Users and Permissions - Using a 3rd party Identity provider](#using-a-3rd-party-saml-identity-provider).

{% hint style="info" %}
Note that you can add more than one identifier for a single user. This is making Flexible Intake to use the same account, no matter what IdP the user is using to log-in.
{% endhint %}

#### Deleting a user account <a href="#deleting-a-user-account" id="deleting-a-user-account"></a>

In **Users**, you can select **Edit User** and set **Active** to **No.**

Users cannot be deleted in Flexible Intake, to preserve platform logs and events (that are linked to the activity of a given user account), but they can be disabled and archived.

​

#### Archival node or container permissions (content permissions) <a href="#archival-node-or-container-permissions-content-permissions" id="archival-node-or-container-permissions-content-permissions"></a>

Once a group or user exists, you can go to the **Configuration** and then to **Archival Structure**:

![](https://gblobscdn.gitbook.com/assets%2F-MVFE6MnOK93sACDCxxx%2F-MZ8lvvCRRBl9tU-bOYU%2F-MZ8mstPS-mkc_FniPKO%2Fimage.png?alt=media\&token=6004c27d-b25b-4619-95d0-989dc04bff29)

For the node where you want to adjust permissions, select Edit node and go to the Permissions section:

![](https://gblobscdn.gitbook.com/assets%2F-MVFE6MnOK93sACDCxxx%2F-MZ8lvvCRRBl9tU-bOYU%2F-MZ8nHby26BEpeNZAi7S%2Fimage.png?alt=media\&token=3997c5bd-a50e-4eb6-8ac7-2b8d8375ce81)

More information about permissions in the [Archive organization](archive-organization) section.

​

### Using the API (Groups) <a href="#using-the-api-groups" id="using-the-api-groups"></a>

{% hint style="info" %}
API examples here are shown just for illustrative purposes. Check the [Flexible Intake API documentation](../developers-guide/using-the-api) for additional information and all available methods.
{% endhint %}

#### Creating groups <a href="#creating-groups" id="creating-groups"></a>

1. Sign in to the Flexible Intake Management Interface
2. Obtain your Flexible Intake API key by selecting your name and then **Access Methods:**

![](https://gblobscdn.gitbook.com/assets%2F-MVFE6MnOK93sACDCxxx%2F-MVaHSX-G_bFFXPQn-Od%2F-MVaJWnwSfyMMFbO42X1%2Fimage.png?alt=media\&token=7047e304-094c-4c46-a50e-102ba2513abe)

1. Use this method:

```
curl --request POST \     --url "$your_platform_url/api/group" \     --header "Content-Type: application/json" \     --header "authorization: Bearer $your_platform_api_key" \     --data '{         "name": "New group name",         "description": "New group description"     }'
```

​

#### Get existing groups <a href="#get-existing-groups" id="get-existing-groups"></a>

1. Sign in to the Flexible Intake Management Interface
2. Obtain your Flexible Intake API key by selecting your name and then **Access Methods:**

![](https://gblobscdn.gitbook.com/assets%2F-MVFE6MnOK93sACDCxxx%2F-MVaHSX-G_bFFXPQn-Od%2F-MVaJWnwSfyMMFbO42X1%2Fimage.png?alt=media\&token=7047e304-094c-4c46-a50e-102ba2513abe)

1. Use this method:

```
    curl --request GET \      --url "$your_platform_url/api/groups" \      --header "authorization: Bearer $your_platform_api_key"
```

​

#### Assigning content permissions (archival node or container) to a group <a href="#assigning-content-permissions-archival-node-or-container-to-a-group" id="assigning-content-permissions-archival-node-or-container-to-a-group"></a>

See the [Archive organization](archive-organization) section.

​

#### Assigning action permissions to a group <a href="#assigning-action-permissions-to-a-group" id="assigning-action-permissions-to-a-group"></a>

1. Sign in to the Flexible Intake Management Interface
2. Obtain your Flexible Intake API key by selecting your name and then **Access Methods:**

![](https://gblobscdn.gitbook.com/assets%2F-MVFE6MnOK93sACDCxxx%2F-MVaHSX-G_bFFXPQn-Od%2F-MVaJWnwSfyMMFbO42X1%2Fimage.png?alt=media\&token=7047e304-094c-4c46-a50e-102ba2513abe)

1. Use this method:

```
@TO DO LIBNOVA ticket https://trello.com/c/fFj5PZsK/197​/container/{id}/permission/{permission}/{type}/{type_id}​​
```

**Type:** Use "User" or "Group" to assign the permission to a user or to a group.

**id:** The user or group id to assign the permission to.

**Permissions:** Include the permission keys here. See below for a list of permission keys.

You can get a list of all available permission keys you can include in the previous call using the following method:

```
curl --request GET \    --url "$your_platform_url/api/permissions" \    --header "Content-Type: application/json" \    --header "authorization: Bearer $your_platform_api_key" \    --data '{}'
```

​

### Using the API (Users) <a href="#using-the-api-users" id="using-the-api-users"></a>

{% hint style="info" %}
API examples here are just illustrative. Check the [Flexible Intake API documentation](../developers-guide/using-the-api) for additional information and all available methods.
{% endhint %}

#### Creating users <a href="#creating-users" id="creating-users"></a>

1. Sign in to the Flexible Intake Management Interface
2. Obtain your Flexible Intake API key by selecting your name and then **Access Methods:**

![](https://gblobscdn.gitbook.com/assets%2F-MVFE6MnOK93sACDCxxx%2F-MVaHSX-G_bFFXPQn-Od%2F-MVaJWnwSfyMMFbO42X1%2Fimage.png?alt=media\&token=7047e304-094c-4c46-a50e-102ba2513abe)

1. Use this method:

```
    curl --request POST \     --url "$your_platform_url/api/user/internal" \     --header "Content-Type: application/json" \     --header "authorization: Bearer $your_platform_api_key" \     --data '{         "name": "New user",         "password": "password",         "groups": [1, 2],         "keywords": ["user"],         "identifier": "Identifier"     }'
```

All content permissions and action permissions available for user groups that are showcased in the previous section are also available to users.

​

## Using a 3rd party SAML Identity Provider <a href="#using-a-3rd-party-saml-identity-provider" id="using-a-3rd-party-saml-identity-provider"></a>

An identity provider (abbreviated IdP or IDP) is a system entity that creates, maintains, and manages identity information for principals and also provides authentication services to relying applications (Service Providers, abbreviated SP) within a federation or distributed network.

Identity providers offer user authentication as a service. Flexible Intake outsources the user authentication step to a trusted identity provider, consuming its federated identity services.

This way, users do not need to provide their credentials to log-in into the platform.

### Authorizing the Flexible Intake Service Provider

In order to start using SAML authentication, both your Identity Provider and our Service provider must be able to communicate with each other. There are two ways that this can be achieved:

#### If your organization is federated

If your organization is already part of a SAML federation such as InCommon, eduGAIN, UK Federation among others, the configuration required to authorize the LIBNOVA Service Provider is minimal. Your IdP should release at least the [eduPersonTargetedID](https://www.switch.ch/aai/support/documents/attributes/edupersontargetedid/) attribute, and optionally any other attribute that might be used to configure automated account creation (affiliation, groups, etc). Please use our Service Provider's entityID ([`https://access.libnova.com/shibboleth`](https://access.libnova.com/shibboleth)) for attribute release.

#### If your organization is not federated

In the case that your organization is NOT part of any federation, please contact LIBNOVA Support to initiate a metadata exchange process. We will send you the metadata for the Service Provider, and your organization will have to provide us with your Identity Provider's metadata. Attributes described in the previous section should also be released by your IdP.

If the Identity Provider you are using is Microsoft Azure, please follow the [configuring-azure-saml-based-authentication](../cookbook/configuring-azure-saml-based-authentication "mention") guide.

### Identity workflows <a href="#identity-workflows" id="identity-workflows"></a>

Flexible Intake offers extreme flexibility on how accounts are created and user identities are managed. There are several platform settings that impact how the user identities are managed, and how the authentication process gets managed:

* **List of authorized IdPs** for automated user account creation
* **Regular expression for automated permissions assignment**
* **Allow insecure accounts creation**, to allow the user to provide its own email and name if the IdP is not providing them.

When a log-in request is received by the platform, Flexible Intake will check if the identity for the user that is provided by the IdP matches any of the identities assigned to the Flexible Intake users.

* If the **identity matches**, the user is logged-in in the account
* If **there is not a matching identity**,
  *   If the issuing IdP is in the list of **authorized IdPs for automated user account creation**, Flexible Intake analyzes the request looking for the user email and name

      * If the IdP **is releasing the email and user attributes** to the Flexible Intake platform, two options are offered to the user:
        * **"Create a new Flexible Intake account"**: To create a new account with the received email and name already filled-in, with no possibility of changing them
        * **"Associate this identity to an existing Flexible Intake account"**: In which the user is presented its IdP identity identifier, along with instructions on how to add it to its existing account. The user will then log-in with its existing account, go to its user settings, and add/paste the provided identifier in the Identifiers field. Next time the user tries to log-in using the identity, he/she will be logged in.

      ​

      * If the IdP is not releasing the email and user name, Flexible Intake will check for the **Allow insecure accounts creation** setting
        * If **it is enabled**, two options are offered to the user:
          * **"Create a new Flexible Intake account":** Flexible Intake asks the user for its email and name and
            * If the email is not already associated to an existing account, Flexible Intake creates the account based on them
            * If the email is already associated, we redirect the user to the association instructions (below)
          * **"Associate this identity to an existing Flexible Intake account":** In which the user is presented its IdP identity identifier, along with instructions on how to add it to its existing account. The user will then log-in with its existing account, go to its user settings, and add/paste the provided identifier in the Identifiers field. Next time the user tries to log-in using the identity, he/she will be logged in.
        * If the **Allow insecure accounts creation** is not enabled, the user is presented with its identity identifier and a message to provide it to a Flexible Intake administrator, in order for the account to be created. No automated account is created.
  * If the **issuing IdP is NOT in the list of authorized IdPs** for automated user account creation, the user is presented a message indicating that its IdP is not within the allowed IdPs, and accounts cannot be created. The IdP identifier and the user identifier are presented to the user so they can be sent to the administrator in the case he/she wants to configure them.

{% hint style="danger" %}
Please note that if the **Allow insecure accounts creation** setting is enabled, the user can provide a fake name and email to the platform, and the account will be created without verifying them, potentially making impersonation attacks possible.
{% endhint %}

​

### Automated account creation <a href="#automated-account-creation" id="automated-account-creation"></a>

When your users try to log-in for the first time, if the Identity Provider id has been included in the authorized IdP list, an account for the user will be created.

To include an IdP in the authorized IdPs' list:

1. Go to **Configuration** and then to **Federated Authentication**:

![](https://gblobscdn.gitbook.com/assets%2F-MVFE6MnOK93sACDCxxx%2F-MchZyLL4JK-GC9O12PN%2F-Mchbnm3Y7t-l2Bi8EMa%2Fimage.png?alt=media\&token=c75052a3-ff11-4b35-a3b8-929bea408a8e)

1. Add the **id of the authorized IdP** to the list.

![](https://gblobscdn.gitbook.com/assets%2F-MVFE6MnOK93sACDCxxx%2F-MciySscdJdQdhaM4Bch%2F-McjoybLMikZNS4hPOEL%2Fimage.png?alt=media\&token=53b87fbe-f249-43c4-8244-3f6a64dd4ec2)

{% hint style="info" %}
If you do not know your IdP's id, ask one user to try to log-in using it and then review the **Log section** in this page. The id of the failed log-in attempt is retained there.
{% endhint %}

{% hint style="info" %}
If you want to receive a notification every time a new account is automatically created, go to your notification settings (in the account name menu and then **My Profile**) and enable the **Automatic account create** notification.
{% endhint %}

### Automated permissions <a href="#automated-permissions" id="automated-permissions"></a>

When the accounts are automatically created for users, they do not belong to any Flexible Intake group by default. If you want to make them part of a group, you can use the **Automated Permissions Configuration** to create a rule that will be applied every time an account is created:

1. Go to **Configuration** and then to **Federated Authentication**:

![](https://gblobscdn.gitbook.com/assets%2F-MVFE6MnOK93sACDCxxx%2F-MchZyLL4JK-GC9O12PN%2F-Mchbnm3Y7t-l2Bi8EMa%2Fimage.png?alt=media\&token=c75052a3-ff11-4b35-a3b8-929bea408a8e)

1. Go to the **Automated account configuration** section.
2. Select **Add**
3. Indicate a **meaningful name for the rule** that you are creating, indicate the **group to which the users will belong** and then the **SAML attribute** and the **regular expression** you want. If the value for the attribute matches the regular expression, Flexible Intake will make the user a member of the group.

![](https://gblobscdn.gitbook.com/assets%2F-MVFE6MnOK93sACDCxxx%2F-Mchm9zcQRZ2FA83Op4z%2F-MchnvxzHXnSAUQcB034%2Fimage.png?alt=media\&token=465a9eb0-b54c-4e96-b524-5de3ebb27dbc)

{% hint style="info" %}
For instance, let's say you want any user with the attribute "affiliation" set to admins@acme.com to be part of the group "System Administrators". You would add a new rule and define:‌

* **Name**: Make admins@acme.com part of Sysadmin group
* **Group**: Select "System Administrators"
* Select **Add**, and then,
  * In the **Attribute**, set "affiliation"
  * In the **Regex** field, set "^admins@acme.com.com$"
{% endhint %}

![](https://gblobscdn.gitbook.com/assets%2F-MVFE6MnOK93sACDCxxx%2F-MdH928nZ0QQFWSZ1nQ0%2F-MdHAdWFU2mMnN082xAq%2Fimage.png?alt=media\&token=fcc441e2-4d99-4f38-9f51-e6bce1387ffe)

Select **OK** and **Create**.

{% hint style="danger" %}
Much like any programming language, a regular expression is a succinct language in its own right. For instance, in the Regex syntax, a non-escaped dot means "any" character. If misused, this may allow users to access content they should not be able to access. When creating your regex expression, make sure to test that it works for the cases it should work **and that it does not work for the cases it should not.**
{% endhint %}

{% hint style="info" %}
The IdPs do not always release all available attributes to the Service Providers (Flexible Intake). The attribute you are looking for may not be part of what the IdP is providing. If this is the case, ask your IdP administrator to release the attributes you need.

When a user logs-in, full details of the IdP's released attributes are saved in the log. This may be useful for you to know the attributes that it is releasing to Flexible Intake.
{% endhint %}

### How to log in using an IdP <a href="#how-to-log-in-using-an-idp" id="how-to-log-in-using-an-idp"></a>

In case you want to use an external Identity Provider:

1.Select the **Your Identity Provider** link in the log-in page of Flexible Intake :

![](https://4041101886-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MgzI4gmAMX6UHf919le%2Fsync%2F610e812f24f00b3f81d798441901e73399389a5e.png?generation=1628855371562256\&alt=media)

1. A list of Identity Providers will be presented. Select yours:

![](https://gblobscdn.gitbook.com/assets%2F-MVFE6MnOK93sACDCxxx%2F-MY19b2P-seWyiYq-mYy%2F-MY1CPfLpZ_UasMTYJYF%2Fimage.png?alt=media\&token=ddaf042e-211b-4658-9e7e-74b2d345bff6)

​

1. Select **Continue.**

{% hint style="info" %}
If you do not have a Flexible Intake account and your IdP has been authorized, an account will be created for you.
{% endhint %}

### How to log in with more than one identity to the same Flexible Intake account <a href="#how-to-log-in-with-more-than-one-identity-to-the-same-flexible-intake-account" id="how-to-log-in-with-more-than-one-identity-to-the-same-flexible-intake-account"></a>

Users can link a single Flexible Intake account to more than one of the federated identities available. This way, when the user is using more than one email account for more than one organization, the user can log-in with any of them to the same Flexible Intake account.

To do this, a user with permissions to manage user accounts in Flexible Intake needs also to introduce the identifier in the user authentication section.

{% hint style="info" %}
If the user has already created two accounts in Flexible Intake with two different identities, move all existing content from one account to the other, remove the **eduPersonTargetedID** from the one to erase and add it as an additional identifier to the Flexible Intake account that you want the user to use. Then, disable the previous account.
{% endhint %}

To do it, a user with permission to manage user accounts in Flexible Intake needs to introduce the identifier in the user authentication section.

The identifier **must be the eduPersonTargetedID** attribute. The eduPersonTargetedID is used in lieu of the eduPersonPrincipalName to guarantee uniqueness across all possible Identity Providers:

![](https://gblobscdn.gitbook.com/assets%2F-MVFE6MnOK93sACDCxxx%2F-MciySscdJdQdhaM4Bch%2F-McjqERZsWbja81qCi92%2Fimage.png?alt=media\&token=2d80ce84-7e82-4bf4-86e1-4e0aee68b542)

{% hint style="warning" %}
One Identity Provider/user identifier cannot be used for more than one Flexible Intake account, but one Flexible Intake user can use multiple user identifiers.
{% endhint %}

​
