Globus Connect Server Administration Guides
  • Quickstart Guide
  • Installation Guide
  • Data Access Admin Guide
  • Domain Guide
  • HTTPS Access to Collections
  • Identity Mapping Admin Guide
  • Globus OIDC Installation Guide
  • Troubleshooting Guide
  • Command-Line Reference
    • Command summary
    • Audit
      • Load
      • Query
      • Dump
    • Endpoint
      • Setup
      • Show
      • Update
      • Reset Advertised Owner String
      • Set Advertised Owner String
      • Set Owner
      • Set Subscription ID
      • Cleanup
      • Key Convert
      • Domain
      • Role
      • Upgrade
    • OIDC
      • Create
      • Delete
      • Register
      • Show
      • Update
    • Node
      • Create
      • Disable
      • Enable
      • New Secret
      • Setup
      • List
      • Show
      • Update
      • Cleanup
      • Delete
    • Login
    • Session
      • Consent
      • Show
      • Update
    • Whoami
    • Logout
    • Storage Gateway
      • Create
      • List
      • Show
      • Update
      • Delete
    • Collection
      • Create
      • List
      • Show
      • Batch Delete
      • Reset Advertised Owner String
      • Set Advertised Owner String
      • Set Owner
      • Set Subscription Admin Verified Collection Property
      • Update
      • Delete
      • Domain
      • Check
      • Role
    • Auth Policy
      • Create
      • List
      • Show
      • Update
      • Delete
    • Sharing Policy
      • Create
      • List
      • Show
      • Delete
    • User Credentials
      • Activescale Create
      • OAuth Create
      • Delete
      • List
      • S3 Create
      • S3 Keys Add
      • S3 Keys Delete
      • S3 Keys Update
    • Self Diagnostic
  • Globus Connect Server Manager API
    • Authorization
    • Versioning
    • Endpoint
    • Roles
    • Nodes
    • Storage Gateways
    • Collections
    • User Credentials
    • Domains
    • Sharing Policies
  • API Access for Portals
  • Automated Endpoint Deployment
  • Data Access Application Guide
  • Application Migration Guide
  • Change Log
Skip to main content
Globus Docs
  • APIs
    Auth Flows Groups Search Timers Transfer Globus Connect Server Compute Helper Pages
  • Applications
    Globus Connect Personal Globus Connect Server Premium Storage Connectors Compute Command Line Interface Python SDK JavaScript SDK
  • Guides
  • Support
    FAQs Mailing Lists Contact Us Check Support Tickets
  1. Home
  2. Globus Connect Server
  3. v5.4
  4. Data Access Admin Guide

Globus Connect Server v5 Data Access Admin Guide

Table of Contents
  • 1. Introduction
  • 2. Storage Gateways Overview
    • 2.1. Commands
  • 3. Creating a Storage Gateway
    • 3.1. Select a Connector and a Display Name
    • 3.2. Configure Authentication Requirements
      • 3.2.1. Authentication Policies
    • 3.3. Configure Identity Mapping
      • 3.3.1. Identity Mapping Policies
    • 3.4. Configure Data Access Restrictions
      • 3.4.1. Data Access Policies
    • 3.5. Configure User Access Restrictions
      • 3.5.1. User Policies
    • 3.6. Create the Storage Gateway
  • 4. Collections
    • 4.1. Mapped Collection
    • 4.2. Guest Collection
    • 4.3. Commands
  • 5. Create a Collection
    • 5.1. Select a Storage Gateway
    • 5.2. Configure Collection Base Path
    • 5.3. Display Name
    • 5.4. Metadata
    • 5.5. Sharing Configuration
    • 5.6. User Message and Link
    • 5.7. Enable or Disable HTTPS Access
    • 5.8. Create a Collection
  • 6. Path Restrictions
    • 6.1. Path Restriction Override Precedence
  • 7. User Sharing Path Restrictions
    • 7.1. Sharing Policy Overview
      • 7.1.1. Sharing Policy Evaluation
    • 7.2. Examples
  • 8. User Sharing Domain Restrictions
    • 8.1. Overview
    • 8.2. Examples
  • 9. Globus Help Resources
    • 9.1. Documentation Website
    • 9.2. Mailing Lists
    • 9.3. Globus Support
  • Appendix A: StorageGateway Document
  • Appendix B: Collection Document

Last Updated: March 10, 2021

1. Introduction

This document describes the common tasks a Globus administrator would need to do to create and manage storage gateway and collection resources associated with the endpoints that they run. This document assumes that you have already created and deployed an endpoint by following the Globus Connect Server version 5 Installation Guide. The commands in this guide assume you have access to the globus-connect-server command-line tool.

Storage Gateways provide the policies for a storage system connected to the endpoint, and Collections provide the data access interfaces for users.

A storage gateway contains policies for

  • Authentication requirements,

  • Mapping Globus identities to local accounts,

  • Allowing or denying accounts access to the storage gateway

  • Controlling which paths are accessible, and with what level of access.

A collection contains GridFTP and HTTPS interfaces for data access, and policies that govern sharing data with other users.

Important

In this document, we will show some example invocations of the Globus Connect Server version 5 management commands. If you plan to follow along on your own system, you’ll need to change the commands to reflect your organization and login policies. Anywhere you see something highlighted like this you’ll need to replace the text with something that matches the desired policies for your own endpoint.

2. Storage Gateways Overview

A storage gateway provides the access policies for the endpoint’s connected storage systems. It is a named interface by which authorized users can create and manage collections on the connected storage system. A single storage system may be associated with multiple storage gateways, each with its own policies.

Storage gateway policies describe what type connector the storage gateway uses, the paths it allows access to, the login requirements are for the storage gateway, and the algorithm to map Globus identities to the user namespace of the storage gateway (e.g. local accounts).

Version 1.1.0 includes support for multi-factor authentication requirements for high assurance storage gateways.

Version 1.2.0 includes support for admin managed credentials.

Version 1.3.0 includes support for overriding the endpoint’s network use parameters on a storage gateway.

2.1. Commands

Storage gateways are managed via the globus-connect-server storage-gateway command:

globus-connect-server storage-gateway create

Create a storage gateway

globus-connect-server storage-gateway delete

Delete a storage gateway

globus-connect-server storage-gateway list

List storage gateways

globus-connect-server storage-gateway show

Show a storage gateway definition

globus-connect-server storage-gateway update

Update an existing Storage Gateway

3. Creating a Storage Gateway

We’re going to walk through creating a storage gateway, discussing the policies associated with the different aspects of the storage gateway.

3.1. Select a Connector and a Display Name

A Connector is the part of Globus Connect Server that connects it to the data stored on a storage system. Globus Connect Server v5.4 supports may different connectors. This document covers configuring the POSIX connector. To configure a different connector, it’s helpful to follow through this guide as it explains the basic concepts and policies available in Globus Connect Server. See the Premium Connectors Guide for information about connecting a different type of storage to Globus.

Example 1. Storage Gateway Connector and Name

We’ll use the POSIX connector for our example. We’ll call the storage gateway Example Gateway. Those will be used as positional parameters to create the storage gateway, so we’ll be using this command-line:

globus-connect-server storage-gateway create posix "Example Gateway" [OPTION]...

Note, that this is not yet a complete enough command-line to use, we’ll be adding more policy parameters to replace [OPTION]…​ in the command-line.

3.2. Configure Authentication Requirements

Globus users will authenticate with their identity providers before being able to access Globus Connect Server version 5 collections. Each storage gateway has policies that require identities from one or more providers to access storage on collections associated with the gateway. Administrators can also set policies to control how recently the authentications must have occurred, and whether the storage gateway serves protected data that requires High Assurance authentications.

3.2.1. Authentication Policies

There are three command-line options that control which user identities are allowed access to the data on a storage gateway: --domain, --authentication-timeout-mins, and --high-assurance.

The value of the --domain command-line option restricts access to users who have an identity in the given domain. This may be configured to be multiple values to allow authentication by multiple identity providers. If more than one domain is allowed, the storage gateway needs to have an identity mapping method configured to decide how to process names from the different identity namespaces. See Identity Mapping Policies for more information.

Note

The --domain command-line option is only available to domains associated with identity providers listed by Globus Auth. Linked email identities, and the domains associated with them, are not supported by this policy.

The value of the --authentication-timeout-mins command-line option defines the timeout (in minutes) after which a user will need to re-authenticate in order to access mapped collections on non high assurance storage gateways or for any data access on high assurance storage gateways. If this is not supplied, the default value of this timeout is 11 days.

The value of the --high-assurance command-line option defines whether the storage gateway manages high assurance data. If it is set, then the authentication timeout is enforced on per application sessions. This option can only be set when the storage gateway is created and is immutable.

Example 2. Require a Specific Domain and Monthly Reauthentication

For our example, we’ll require users to have an identity with the example.org domain, and will use an authentication timeout of 30 days. This means that the user must authenticate at least once every month with that identity to access data.

The following command line option can be used for that:

--domain example.org \
--authentication-timeout-mins $((60 * 24 * 30))

3.3. Configure Identity Mapping

Identity mapping in Globus Connect Server version 5 controls how user’s identity is granted access to accounts on storage gateways serving collections. Each Globus user has one or more identities linked to their Globus accounts. The identity mapping feature of Globus Connect Server version 5 allows administrators to configure which identity providers they allow access, and how the user information from identity provider (user name, id, email) is used to select a local account name that is relevant to the storage gateway.

See the Identity Mapping Admin Guide, which includes some helpful recipes as well as a full specification of the documents used to configure custom identity mappings.

3.3.1. Identity Mapping Policies

Globus Connect Server v5.4 supports a flexible system for mapping user identity information in Globus to the local account needed to access data on a variety of storage systems. This includes a default mapping for cases where there is only one allowed domain, as well as pattern-based mappings and callouts to external programs for custom mapping algorithms.

Default Identity to Username Mapping

By default, if the storage gateway is configured to allow identities from a single domain, one of the following mappings are done from the user’s identity in the allowed domain to the storage gateway user namespace:

  • For connectors such as Black Pearl, Ceph, POSIX, when Globus Connect Server maps an identity to an account, it strips off the data after the @ character. So the username user@example.org is mapped to the account user.

  • Some connectors (Box, Google Cloud Storage, Google Drive) require that the account name must be qualified by a domain name. When Globus Connect Server maps an identity to an account, it retains the entire username by default, so the username user@example.org is mapped to the account user@example.org.

Note

The S3 connector uses account names qualified by a domain name, but the account name is used solely for logging purposes.
Custom Identity to Username Mapping

The --identity-mapping command-line option configures a storage gateway to use either an expression based identity mapping or an external identity mapping program. See the Identity Mapping Guide for more information.

The --identity-mapping command-line option can be passed on the command-line with a few different types of data as its arguments:

--identity-mapping external:CMD

When mapping a identity to a username, Globus Connect Server invokes the command-line program CMD to map the identity. The value of the CMD string will be parsed as a shell command-line, so arguments may be included if quoted. A full description of the input, output, and arguments to the program are included in Identity Mapping Guide.

--identity-mapping file:JSON_FILE
--identity-mapping JSON

The JSON_FILE argument is a path to a file which contains a JSON document containing the mapping configuration, as described in the Identity Mapping Guide. The JSON argument is the json document itself.

Example 3. Default Identity Mapping

Since we’re only allowing a single identity provider, and our account namespace matches that of example.org, we’ll not set any identity mapping options.

Read the Identity Mapping Guide for recipes to configure custom user identity to storage account mappings, so you can manage access to your storage via Globus for users with identities from different organizations.

3.4. Configure Data Access Restrictions

Even with an account from a provider you trust, and a username that you’ve allowed access to the storage gateway, there may be some areas of the filesystem that you need to restrict, either to disallow writing to data in a directory, or to completely disallow access to some directories of the file system via Globus.

3.4.1. Data Access Policies

The --restrict-paths command-line option controls access to subtrees of the data provided by the storage gateway. This is configured using the PathRestrictions document type.

Path restrictions provide a framework for administrators to constrain data access on the storage gateway. Restrictions can be set at the folder level. They may allow read, write, or deny access to data. These are absolute paths from the root of the storage gateway virtual file system.

Example 4. Restrict Access to $HOME

For this example, we’ll restrict access to the home directories of our users. Each user will only see their home directory when they list collections on this storage gateway. To enable this, we’ll create a file containing the path restrictions, and then pass that file’s path as a parameter to the --restrict-paths command-line option.

First, create the path restriction document. Create a file called path-restrictions.json with the following content:

{
  "DATA_TYPE": "path_restrictions#1.0.0",
  "read_write": [
    "$HOME"
  ],
  "none": [
    "/"
  ]
}

Then we’ll add it to the command-line:

--restrict-paths file:path-restrictions.json

3.5. Configure User Access Restrictions

As an administrator, you can further restrict access to the storage gateway to subset of users - either allow or deny of subset of accounts. Once a Globus account is mapped to a storage gateway account, it is further subject to this user policy, where you can explicitly allow or deny some subset of those accounts.

3.5.1. User Policies

The --user-allow and --user-deny command-line options control which users may access data on a storage gateway. These operate on the result of the identity mapping, a user name that is in the namespace of storage gateway. This may be a user name, id, or email address based on the storage gateway requirements.

A username is allowed or denied access depending on whether the --user-allow and --user-deny command-line option are set on a storage gateway, and whether the username is present in one or both of those policies. In general, if a username is in the value of --user-deny it is always denied, and if a --user-allow policy is provided the username must be in the policy value in order to be allowed access.

The full set of effects of these policies are contained in the following table:

--user-allow --user-deny result

member

-

Allowed

member

not a member

Allowed

-

-

Allowed

-

not a member

Allowed

-

member

DENIED

not a member

-

DENIED

not a member

not a member

DENIED

not a member

member

DENIED

member

member

DENIED

Note

The POSIX connector includes additional policies related to POSIX groups, which change the allow/deny handling slightly. See POSIX user policies section of the command line tool for more information.

Example 5. Disable System Users

We’ll filter out the access to the root user. This makes it so even if someone has the root@example.org identity, they won’t be granted access to the storage gateway.

--user-deny root

3.6. Create the Storage Gateway

Now that we have decided on all our policies, we’ll use the command to create the storage gateway.

Example 6. Create a Storage Gateway
% globus-connect-server storage-gateway create posix "Example Gateway" \
    --domain example.org \
    --authentication-timeout-mins $((60 * 24 * 30)) \
    --restrict-paths file:path-restrictions.json \
    --user-deny root
Storage Gateway ID: 7187a9a0-68e4-48ea-b3b9-7fd06630f8ab

This was successful and the output the ID of the new storage gateway ( 7187a9a0-68e4-48ea-b3b9-7fd06630f8ab in this case) for our reference. Note that this will always be a unique value if you run the command. If you forget the id of a storage gateway, you can always use the command globus-connect-server storage-gateway list to get a list of the storage gateways on the endpoint.

Note that this creates the storage gateway, but does not yet make it accessible via Globus and HTTPS. You’ll need to follow the steps in Create a Collection to do that.

There are many storage-gateway specific policy options to this command, they are documented in full in the reference manual.

Important

If you are using Globus Connect Server version 5 with high assurance features, you will need to set all storage gateways that have access to protected or restricted data as high assurance by passing the --high-assurance and --authentication-timeout-mins command-line options when you create a Storage Gateway. Once a storage gateway is created, the high-assurance feature can not be changed from enabled to disabled or vice versa.

4. Collections

A collection consists of metadata about the collection, a DNS domain for accessing data on the collection, and configuration on the Data Transfer Nodes to access the collection data. Globus Connect Server version 5 supports two types of collections: mapped and guest.

Version 1.1.0 adds support for enabling or disabling https access for individual collections, as well as the ability for collection administrators to add an optional message and web link to be shown on the Globus Web App when users visit the collection.

Version 1.2.0 adds the ability to enable or disable sharing by specific users.

Version 1.3.0 add support for custom DNS domains on collections.

Version 1.4.0 allows optional multi-factor authentication requirements to high assurance collections and the ability to require checksums when transferring data on this collection.

Version 1.5.0 allows administrators to disable permissions that would allow anonymous users to have write access to an endpoint.

Version 1.6.0 allows administrators of mapped collections to associate policies that users accessing guest collections must meet beyond the guest collection permissions.

Version 1.7.0 increases the maximum allowed length of the user_message property.

Version 1.8.0 adds the delete_protected property. While it is set to true on a mapped collection, the collection may not be deleted. As of GCS 5.4.69, this is true by default.

Version 1.9.0 adds the read-only last_access and created_at properties.

Version 1.10.0 adds the acl_expiration_mins property to HA mapped collections.

Version 1.11.0 adds the acl_expiration_mins property to HA guest collection.

Version 1.12.0 adds the restrict_transfers_to_high_assurance property to HA collections.

Version 1.13.0 adds the auto_delete_timeout property to mapped collections and the skip_auto_delete property to guest collections.

Version 1.14.0 adds the subscription_admin_verified property to collections and activity_notification_policy to guest collections.

Version 1.15.0 adds the associated_flow_policy property to the collection.

4.1. Mapped Collection

A mapped collection allows access to data for users who have accounts in the storage gateway’s user space (or local account). The collection uses the identity mapping method configured on the storage gateway to map the Globus account of the user accessing the collection to an account in the Storage Gateway’s user space. All accesses to the data on the collection are performed using the local account and (if needed for the storage gateway) the account’s credentials.

Mapped collections can only be created by those with an administrator or owner role on the Endpoint, and can be created against any storage gateway that exists on the endpoint.

4.2. Guest Collection

If your endpoint is managed, you can configure policies to allow data sharing for a collection via Globus. When you enable data sharing, you allow your users to create new guest collections related to a mapped collection.

A guest collection is a collection that uses an existing mapped collection and adds the ability of a user to share access to their data on that collection. All access to the data is performed using the account of the user who created the guest collection. That user can also add entries to an access control list to allow others to access some parts of the guest collection owner’s data.

A guest collection document has additional properties mapped_collection_id and user_credential_id to describe the relationship between the collection and a mapped collection where it was created and the credential used for data access.

4.3. Commands

Collections are managed via the globus-connect-server collection command:

globus-connect-server collection create

Create a new collection.

globus-connect-server collection delete

Delete a collection.

globus-connect-server collection list

List collections.

globus-connect-server collection show

Show information about a collection.

globus-connect-server collection update

Update information about a collection.

In addition, once a collection is created, it may be viewed and edited using the Globus Web App.

5. Create a Collection

With the storage gateway created, the next step is to create a mapped collection to allow access to the storage gateway’s data.

This is also where you will add metadata about the collection so prospective users can more easily find ways to access the data that they are interested in.

The command we’ll be using is globus-connect-server collection create. It requires a few positional parameters and has many options. We’ll show the format of the command, and then explain more about what those positional parameters and options mean.

Example 7. Collection Create Command Syntax

The basic syntax for this command

globus-connect-server collection create \
    STORAGE_GATEWAY_ID \
    COLLECTION_BASE_PATH \
    DISPLAY_NAME \
    [OPTION]...

5.1. Select a Storage Gateway

We can create a mapped collection for any storage gateway configured on this endpoint. You can list the available storage gateways using the globus-connect-server storage-gateway list command. The ID column of the output is the one that contains the id to use here.

Example 8. Storage Gateway

For this example, we’ll use the output of the storage gateway command from the previous section.

7187a9a0-68e4-48ea-b3b9-7fd06630f8ab

5.2. Configure Collection Base Path

Each mapped collection has a base_path property, which is the starting directory relative to the root of the storage gateway’s virtual file system that will act as the root of the collection. A user who accesses the collection will never be able to see any files that do not exist in that directory or one of its subdirectories.

Note

When a user creates a guest collection, there is also a base_path property to that collection. That path is interpreted relative to the base_path of the mapped collection the user used to create the collection.

The path restriction setting above already restricts the parts of the storage gateway’s virtual filesystem to the user’s $HOME directory. This means that if we select a base path outside of a user’s home directory, they will not be able to see any files or directories (except for an empty root directory) when accessing the collection.

Example 9. Base Path

Since we’ve already restricted access to $HOME, we can do a few different things with the base path.

If we expect users to use this collection to access only their home directories, it might make sense to use $HOME as the base path. Then, the root directory listing will show their home directory contents.

If we anticipated adding other path restrictions later on to allow access to other directories, (e.g. /projects), we could use / as the base path. In that case, the users can see files in their home directories, but the / directory would be otherwise empty. We’ll do that for this example.

/

Note, that this is not yet a complete enough command-line to use, we’ll be adding more policy parameters in the following sections.

5.3. Display Name

Like the storage gateway above, we need to choose a display name for this collection. The collection display name is a bit more important because your users will see this as part of the interface to accessing data on this collection.

Example 10. Display Name

Since this collection will only allow access to the home directories of users in the example.org domain, and it’s a posix collection, we’ll call it POSIX example.org home directories, so our users can easily find it.

"POSIX example.org home directories"

5.4. Metadata

A collection is only useful if your users can find it. Globus Connect Server version 5 supports a large number of metadata properties on the collection objects to make it easy to describe who is operating the collection, where it is, and any other keywords that might make sense for your organization or project.

The options which allow you to set metadata are:

--keywords string,string,…​

Comma separated list of keywords to help searches for the collection

--department DEPARTMENT

Department which operates the collection

--organization ORGANIZATION

Organization for the Collection

--contact-email EMAIL

Email address of the support contact for this collection. This is visible to end users so that they may contact your organization for support.

--contact-info INFO

Other non-email contact information for the collection, e.g. phone and mailing address. This is visible to end users for support.

--info-link URL

Link to a web page containing info about the collection.

--description STRING

Description of the collection.

Example 11. Add some metadata

We’d like to make it easy for our users to get information about our collection, so we’ll add some information about our organization, and a link to our documentation about the storage systems at our site, a description, and some keywords.

--organization 'Example organization' \
--contact-email support@example.org \
--info-link \https://example.org/storage/info \
--description "Collection of home directories for the example.org's users" \
--keywords example.org,home

5.5. Sharing Configuration

We’re going to assume this is a managed endpoint, and that we want to allow our users to share data with their collaborators. We’ll need to enable the guest collections option at a minimum, and we can also put some data access restrictions. This may restrict what access types users can share with others, or which users may create guest collections to share data.

Example 12. Enable sharing

First, we’ll enable sharing by using the --allow-guest-collections command-line option. This can only be used with a mapped collection and only if the endpoint is managed by a subscription.

--allow-guest-collections
Example 13. Allow read-only sharing

For this example, we’ll allow users to share any path that they can access on the mapped collection, but only in a read-only mode. Recall that the guest collection can only see files visible on the mapped collection, so users will only be able to share their home directories in this example.

Create a file called sharing_restrictions.json with the following content.

{
  "DATA_TYPE": "path_restrictions#1.0.0",
  "read": [
    "/"
  ]
}

Then we’ll add it to the command-line:

--sharing-restrict-paths file:sharing_restrictions.json
Example 14. Restrict which users can share data (New in GCSv5.4.8)

For this example, we’ll allow sharing to an enumerated list of users. This can also be configured to denying a list of users and allowing all others, or, for the POSIX connector, allow or deny members of a POSIX group permission to create guest collections.

For our example, we’ll allow users alice and bob to create shares on our collection:

--sharing-user-allow alice --sharing-user-allow bob

User-specific sharing restrictions are new in GCSv5.4.18 and described in User Sharing Path Restrictions. These allow sharing path restrictions to be set for specific sets of users.

5.6. User Message and Link

If there is information about your collection that you want your users to see, then you can use the --user-message and --user-message-link command-line options to add a message and optional link to the collection. This will be visible on the Globus Web App when users access the collection as well as in the endpoint documents returned by the Globus Transfer API. You can use this feature, for example, to provide guidance on how to use the collection or a link to upcoming system maintenance downtime. When the user message and link are set on a mapped collection, their values are also displayed when accessing related guest collections.

This feature is available in Globus Connect Server v5.4.5 and later.

Example 15. Add User Message and Link

For this example, we’ll add a user message that indicates that this collection is backed by a tape storage system and should not be used to store directories with many small files, with a link to a data usage policy.

--user-message "Tape storage: Do not upload small files" \
--user-message-link \https://example.org/tape-policy

5.7. Enable or Disable HTTPS Access

If you have a managed endpoint, Globus Connect Server provides a HTTPS interface that allows direct upload and download of data via HTTPS, using Globus Auth security tokens. By default Globus Connect Server will enable the HTTPS interface to all collections supported by the endpoint.

If you want to explicitly enable or disable this for a collection, use the --enable-https and --disable-https command line options. Guest collections can only have HTTPS access enabled if the related mapped collection has HTTPS enabled.

This feature is available in Globus Connect Server v5.4.5 and later.

Example 16. Enable HTTPS

For this example, we’ll enable the HTTPS access feature.

--enable-https

5.8. Create a Collection

Now that we have decided on all our policies, we’ll use the command to create the collection.

Example 17. Create a Collection
% globus-connect-server collection create \
    7187a9a0-68e4-48ea-b3b9-7fd06630f8ab \
    / \
    "POSIX example.org home directories" \
    --organization 'Example organization' \
    --contact-email support@example.org \
    --info-link \https://example.org/storage/info \
    --description "Collection of home directories for the example.org's users" \
    --keywords example.org,home \
    --allow-guest-collections \
    --sharing-restrict-paths file:sharing_restrictions.json \
    --sharing-user-allow alice --sharing-user-allow bob \
    --user-message "Tape storage: Do not upload small files" \
    --user-message-link \https://example.org/tape-policy \
    --enable-https

Collection ID: 56c3dff0-d827-4f11-91f3-b0704c53aa4c

This was successful and the output the ID of the new collection ( 56c3dff0-d827-4f11-91f3-b0704c53aa4c in this case) for our reference. Note that this will always be a unique value if you run the command. If you forget the id of a collection, you can always use the command globus-connect-server collection list to get a list of the collections on the endpoint.

You can use this value with the Globus transfer service and web application, or when editing or deleting this collection.

There are many policy-related options to this command, they are documented in full in the reference manual, but many are discussed in later sections of this document.

6. Path Restrictions

This object represents the path restrictions for a storage gateway or a sharing path restrictions for a mapped collection.

The values of each of the path lists in this object are interpreted using the POSIX pattern matching notation as described in fnmatch(3) with flags set to 0 with additional support for some special user-specific value interpolation:

~, $HOME

The user’s home directory if the storage gateway supports such a concept, / otherwise

$USER

The effective Storage Gateway-specific username that is being used for data access. For a Guest Collection, this is the username of the identity that created the Guest Collection.

These restrictions are evaluated at every data access. When evaluating restrictions, the user-specific interpolation is applied before the file name matching is evaluated.

Globus Connect Server evaluates its path restrictions from longest leading expression match to shortest. When pattern matching characters are present, they are considered as a lower priority match than a literal character, with more specific pattern characters given precedence. The precedence is thus literal character, bracket expression, ? (single-character wildcard), * (wildcard).

If multiple path restrictions apply, all matches are applied from longest to shortest, with the following rules for overriding values:

6.1. Path Restriction Override Precedence

longer restriction shorter restriction result
read_write
read
read_write
read_write
none
read_write
read
read_write
read_write
read
none
read
none
read_write
none
none
read
none

7. User Sharing Path Restrictions

7.1. Sharing Policy Overview

When a mapped collection is configured to allow users to create guest collections, there are policies that restrict which users can create guest collections, as well as policies which restrict which paths available on the mapped collection can be accessed from the guest collections, and with what permissions.

Sharing policies provide a way to restrict sharing of data to certain paths for certain users, even if their account would otherwise have access to the data. Each sharing policy contains information on which collection it applies to, what storage-gateway specific usernames it applies to, and which paths it applies to. Sharing policies are new in v5.4.18.

The commands in this section allow administrators with sufficient permissions to create, delete, list, and show sharing policies.

7.1.1. Sharing Policy Evaluation

When a user creates or accesses a guest collection, the values of the mapped collection’s sharing_restrict_paths and the sharing_policies that relate to the user who created the collection are combined. The resulting set of sharing path restrictions are passed to the GridFTP server which will enforce that only files which match the sharing path restrictions and policies are visible.

It is important to remember that the default sharing_restrict_paths policy is to allow accessing any path visible to the mapped collection in a guest collection. This can be changed by updating the collection using the --sharing-restrict-paths command-line option. If you want to use only user-specific sharing policies, you can set the sharing restrict paths to disallow all accesses with this policy:

{
    "DATA_TYPE": "path_restrictions#1.0.0",
    "none": ["/"]
}

and then create user specific sharing policies.

If you want to allow some sharing by default, you can specify those paths in the sharing_restrict_paths policy, and then add additional allowed paths in the user-specific sharing paths policy.

7.2. Examples

For our example collection created above, we could include additional policies to allow or deny particular sharing paths to our alice and bob users.

For example, we can allow more access to alice, to allow her to create guest collections that have read-write access to the /home/$USER/projects directory.

To do so, we can use the following command:

Example 18. Allow more permissions for a user
% globus-connect-server sharing-policy create 56c3dff0-d827-4f11-91f3-b0704c53aa4c \
    --user alice \
    --read-write '/home/$USER/projects'

We could also restrict accesses so that bob can not share files at all in the /home/$USER/private directory

Example 19. Restrict permissions for a user
% globus-connect-server sharing-policy create 56c3dff0-d827-4f11-91f3-b0704c53aa4c \
    --user bob
    --none '/home/$USER/private'

Note that in both of these cases, the user’s access is a union of both the collection’s sharing_restrict_paths value and the user-specific sharing policies. Also, access can not be granted to paths which are denied by the underlying storage gateway’s path restrictions.

The example collection defined above has additional path restrictions, so alice would have an effective sharing restriction of :

{
  "DATA_TYPE": "path_restrictions#1.0.0",
  "read": [
    "/"
  ],
  "read_write": [
    "/home/$USER/projects"
  ]
}

For more details on the syntax and use of these commands to set the user-specific policies, see the documentation for the globus-connect-server sharing-policy command.

8. User Sharing Domain Restrictions

8.1. Overview

As of GCS 5.4.57, mapped collection admins may assign authentication policies to mapped collections in order to restrict which identity provider domains can be used to access guest collections. In this way, the mapped collection admin can place boundaries on whom guest collection owners may share data. Note that this does not prevent guest collection owners from setting permissions for these domains. Instead, it filters which permissions (including guest collection owner or admin permissions) are considered when authorizing a user to access the guest collection.

An authentication policy defines these criteria which a user must meet in order to satisfy the authentication policy so that the user may be granted access to the data. Authentication policies are stored within the Globus Auth service and can be shared between GCS endpoints.

Included Domains (Optional)

List of identity provider domains allowed for guest collection permissions. Users accessing the guest collection must have an identity from at least one of the included domains and that identity must have a valid guest collection permission. If Included Domains is empty, all of the user’s guest collection permissions are considered. The domains may include wildcards, ie '*.edu'.

Excluded Domains (Optional)

List of identity provider domains not allowed for guest collection permissions. Any of the user’s guest collection permissions from Excluded Domains will not be considered for guest collection access. Any domain listed in both Included Domains and Excluded Domains will not be able to access the guest collection. The domains may include wildcards, ie '*.edu'.

The following option indicates the type of collection the policy will be used on.

High Assurance (Optional)

When a policy is set as high assurance, only permissions for identities from included identity provider domains which have been authenticated within the current session will be considered for guest collection access. A policy is required to be configured as high assurance in order to be placed on high assurance collections. Likewise, if the policy is not high assurance, it can only be used with regular collections. This setting is immutable.

8.2. Examples

Using an authentication policy, we can limit data access to the guest collections attached to our example mapped collection created above. In this example, we limit access to only users whose guest permissions are from the example.edu domain.

To do so, we can use the following commands:

Example 20. Create an authentication policy which limits guest collection access to example.edu identities
globus-connect-server auth-policy create \
    --include example.edu \
    "Only allow example.edu identities" \
    "example.edu-only policy"
Authentication Policy ID: 18be6172-43a8-438c-aaa8-e8e36707399e
Example 21. Assign the policy to an existing mapped collection
globus-connect-server collection update \
    --guest-auth-policy-id 18be6172-43a8-438c-aaa8-e8e36707399e \
    56c3dff0-d827-4f11-91f3-b0704c53aa4c
code: success

9. Globus Help Resources

9.1. Documentation Website

This website (docs.globus.org) contains a wealth of information about configuring and using the Globus service. Many common issues can be resolved quickly by browsing our frequently asked questions and reading the relevant guides and how-tos. We recommend consulting these resources first when looking for fast resolution to any issue you are having with the Globus service.

9.2. Mailing Lists

If you use Globus, then participating in one or more of the public email lists is an excellent way to keep in touch with your peers in the Globus Community. For questions about managing your Globus deployment, e.g. installing software for a Globus endpoint, configuring your firewall, and integrating your institution’s identity system, subscribe to the admin list. For other inquiries and discussions, try the user or developer lists. For more information on mailing lists and how to subscribe, click here.

9.3. Globus Support

Questions or issues that pertain to Globus Connect Server version 5 installation or to any client or service that is used in the Globus software-as-a-service (SaaS) or platform-as-a-service (PaaS) offering can be directed to the Globus support team by submitting a ticket. Subscriptions include a guaranteed support service level.

When submitting a ticket for an issue with Globus Connect Server, please include the endpoint name, a description of your issue, and screenshot/text dumps of any errors you are seeing. Please also include the output of Globus Connect Server’s self-diagnostic command, run as root, from the server hosting the endpoint:

globus-connect-server self-diagnostic

Appendix A: StorageGateway Document

A storage gateway provides the access policies for the endpoint’s connected storage systems. It is a named interface by which authorized users can create and manage collections on the connected storage system. A single storage system may be associated with multiple storage gateways, each with its own policies.

Storage gateway policies describe what type connector the storage gateway uses, the paths it allows access to, the login requirements are for the storage gateway, and the algorithm to map Globus identities to the user namespace of the storage gateway (e.g. local accounts).

Version 1.1.0 includes support for multi-factor authentication requirements for high assurance storage gateways.

Version 1.2.0 includes support for admin managed credentials.

Version 1.3.0 includes support for overriding the endpoint’s network use parameters on a storage gateway.

One of the following schemas:

  • StorageGateway_1_0_0

  • StorageGateway_1_1_0

  • StorageGateway_1_2_0

  • StorageGateway_1_3_0

​

{
  "DATA_TYPE": "storage_gateway#1.0.0",
  "allowed_domains": [
    "string"
  ],
  "authentication_assurance_timeout": 1,
  "authentication_timeout_mins": 1,
  "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  "deleted": true,
  "display_name": "string",
  "high_assurance": true,
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "identity_mappings": [
    {
      "DATA_TYPE": "external_identity_mapping#1.0.0",
      "command": [
        "string"
      ]
    }
  ],
  "load_dsi_module": "string",
  "policies": {
    "DATA_TYPE": "s3_storage_policies#1.0.0",
    "s3_buckets": [
      "string"
    ],
    "s3_endpoint": "https://s3.amazonaws.com",
    "s3_user_credential_required": true
  },
  "process_user": "string",
  "require_high_assurance": true,
  "restrict_paths": {},
  "users_allow": [
    "string"
  ],
  "users_deny": [
    "string"
  ]
}

Appendix B: Collection Document

A collection consists of metadata about the collection, a DNS domain for accessing data on the collection, and configuration on the Data Transfer Nodes to access the collection data. Globus Connect Server version 5 supports two types of collections: mapped and guest.

Version 1.1.0 adds support for enabling or disabling https access for individual collections, as well as the ability for collection administrators to add an optional message and web link to be shown on the Globus Web App when users visit the collection.

Version 1.2.0 adds the ability to enable or disable sharing by specific users.

Version 1.3.0 add support for custom DNS domains on collections.

Version 1.4.0 allows optional multi-factor authentication requirements to high assurance collections and the ability to require checksums when transferring data on this collection.

Version 1.5.0 allows administrators to disable permissions that would allow anonymous users to have write access to an endpoint.

Version 1.6.0 allows administrators of mapped collections to associate policies that users accessing guest collections must meet beyond the guest collection permissions.

Version 1.7.0 increases the maximum allowed length of the user_message property.

Version 1.8.0 adds the delete_protected property. While it is set to true on a mapped collection, the collection may not be deleted. As of GCS 5.4.69, this is true by default.

Version 1.9.0 adds the read-only last_access and created_at properties.

Version 1.10.0 adds the acl_expiration_mins property to HA mapped collections.

Version 1.11.0 adds the acl_expiration_mins property to HA guest collection.

Version 1.12.0 adds the restrict_transfers_to_high_assurance property to HA collections.

Version 1.13.0 adds the auto_delete_timeout property to mapped collections and the skip_auto_delete property to guest collections.

Version 1.14.0 adds the subscription_admin_verified property to collections and activity_notification_policy to guest collections.

Version 1.15.0 adds the associated_flow_policy property to the collection.

One of the following schemas:

  • Collection_1_0_0

  • Collection_1_1_0

  • Collection_1_2_0

  • Collection_1_3_0

  • Collection_1_4_0

  • Collection_1_5_0

  • Collection_1_6_0

  • Collection_1_7_0

  • Collection_1_8_0

  • Collection_1_9_0

  • Collection_1_10_0

  • Collection_1_11_0

  • Collection_1_12_0

  • Collection_1_13_0

  • Collection_1_14_0

  • Collection_1_15_0

​

{
  "DATA_TYPE": "collection#1.0.0",
  "allow_guest_collections": true,
  "authentication_timeout_mins": 0,
  "collection_base_path": "string",
  "collection_type": "mapped",
  "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  "contact_email": "string",
  "contact_info": "string",
  "default_directory": "string",
  "deleted": true,
  "department": "string",
  "description": "string",
  "disable_verify": true,
  "display_name": "string",
  "domain_name": "string",
  "force_encryption": true,
  "high_assurance": true,
  "https_url": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "identity_id": "011a42b9-62d7-49eb-8328-c2e454af88a1",
  "info_link": "string",
  "keywords": [
    "string"
  ],
  "manager_url": "string",
  "mapped_collection_id": "b9348e97-77e7-49f6-a137-47587469ff1d",
  "organization": "string",
  "policies": {
    "DATA_TYPE": "s3_collection_policies#1.0.0"
  },
  "public": true,
  "root_path": "string",
  "sharing_restrict_paths": {},
  "storage_gateway_id": "62c250f4-af41-4074-89a9-b6aff8c56fcb",
  "tlsftp_url": "string",
  "user_credential_id": "321d94b1-e78a-4532-9d25-ac03c49fdaf3"
}
  • Quickstart Guide
  • Installation Guide
  • Data Access Admin Guide
  • Domain Guide
  • HTTPS Access to Collections
  • Identity Mapping Admin Guide
  • Globus OIDC Installation Guide
  • Troubleshooting Guide
  • Command-Line Reference
    • Command summary
    • Audit
      • Load
      • Query
      • Dump
    • Endpoint
      • Setup
      • Show
      • Update
      • Reset Advertised Owner String
      • Set Advertised Owner String
      • Set Owner
      • Set Subscription ID
      • Cleanup
      • Key Convert
      • Domain
      • Role
      • Upgrade
    • OIDC
      • Create
      • Delete
      • Register
      • Show
      • Update
    • Node
      • Create
      • Disable
      • Enable
      • New Secret
      • Setup
      • List
      • Show
      • Update
      • Cleanup
      • Delete
    • Login
    • Session
      • Consent
      • Show
      • Update
    • Whoami
    • Logout
    • Storage Gateway
      • Create
      • List
      • Show
      • Update
      • Delete
    • Collection
      • Create
      • List
      • Show
      • Batch Delete
      • Reset Advertised Owner String
      • Set Advertised Owner String
      • Set Owner
      • Set Subscription Admin Verified Collection Property
      • Update
      • Delete
      • Domain
      • Check
      • Role
    • Auth Policy
      • Create
      • List
      • Show
      • Update
      • Delete
    • Sharing Policy
      • Create
      • List
      • Show
      • Delete
    • User Credentials
      • Activescale Create
      • OAuth Create
      • Delete
      • List
      • S3 Create
      • S3 Keys Add
      • S3 Keys Delete
      • S3 Keys Update
    • Self Diagnostic
  • Globus Connect Server Manager API
    • Authorization
    • Versioning
    • Endpoint
    • Roles
    • Nodes
    • Storage Gateways
    • Collections
    • User Credentials
    • Domains
    • Sharing Policies
  • API Access for Portals
  • Automated Endpoint Deployment
  • Data Access Application Guide
  • Application Migration Guide
  • Change Log
© 2010- The University of Chicago Legal Privacy Accessibility