notebook/mrdp-notebook.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# The Modern Research Data Portal: A Design Pattern for Networked, Data-Intensive Science\n",
    "\n",
    "In this notebook we demonstrate the core logic for developing a Modern Research Data Portal (MRDP). This code leverages the Globus platform to manage identities and data access. We first demonstrate how to use the Globus SDK before stepping through the MRDP logic. \n",
    "\n",
    "The following notebook contains a brief introduction to the Globus SDK. More complete documentation and example notebooks are avaialble in the following locations:\n",
    "\n",
    "* https://docs.globus.org/\n",
    "* https://docs.globus.org/research-data-portal\n",
    "* https://github.com/globus/globus-jupyter-notebooks\n",
    "* https://github.com/globus/globus-sample-data-portal"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Setup\n",
    "\n",
    "To use the following notebook you must first install the Globus Python SDK. This can be done by downloading the SDK and installing it manually (https://github.com/globus/globus-sdk-python) or via Python pip as follows. \n",
    "\n",
    "```\n",
    "pip install globus-sdk\n",
    "```\n",
    "\n",
    "To access the SDK you must authenticate using your Globus identity. In this notebook we use the NativeAppAuthClient as a way of acquiring tokens. If the MRDP code is deployed in a service web-based authentication flows should be used. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from globus_sdk import AuthClient, TransferClient, AccessTokenAuthorizer, NativeAppAuthClient, TransferData\n",
    "\n",
    "\n",
    "CLIENT_ID = '2f9482c4-67b3-4783-bac7-12b37d6f8966'\n",
    "\n",
    "client = NativeAppAuthClient(CLIENT_ID)\n",
    "client.oauth2_start_flow()\n",
    "\n",
    "authorize_url = client.oauth2_get_authorize_url()\n",
    "print('Please go to this URL and login: {0}'.format(authorize_url))\n",
    "\n",
    "# this is to work on Python2 and Python3 -- you can just use raw_input() or\n",
    "# input() for your specific version\n",
    "get_input = getattr(__builtins__, 'raw_input', input)\n",
    "auth_code = get_input(\n",
    "    'Please enter the code you get after login here: ').strip()\n",
    "token_response = client.oauth2_exchange_code_for_tokens(auth_code)\n",
    "\n",
    "AUTH_TOKEN = token_response.by_resource_server['auth.globus.org']['access_token']\n",
    "TRANSFER_TOKEN = token_response.by_resource_server['transfer.api.globus.org']['access_token']\n",
    "\n",
    "tc = TransferClient(AccessTokenAuthorizer(TRANSFER_TOKEN))\n",
    "ac = AuthClient(authorizer=AccessTokenAuthorizer(AUTH_TOKEN))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "## Using the Globus SDK\n",
    "\n",
    "We first show how the Globus SDK can be used to discover endpoint IDs. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# discover an Endpoint ID\n",
    "search_str = \"Globus Tutorial Endpoint\"\n",
    "endpoints = tc.endpoint_search(search_str)\n",
    "print(\"==== Displaying endpoint matches for search: '{}' ===\".format(search_str))\n",
    "for ep in endpoints:\n",
    "    print(\"{} ({})\".format(ep[\"display_name\"] or ep[\"canonical_name\"], ep[\"id\"]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The Research Data Portal function\n",
    "\n",
    "The following code uses the Globus SDK to create, manage access to, and delete shared endpoints, as follows. \n",
    "\n",
    "It first sets up variables for the host endpoint on which the shared enpoint will be created (in this case the \"Globus Tutorial Endpoint\"), the source path for the data to be copied and shared, and the email address of the user to be shared with. \n",
    "\n",
    "import sys, random, uuid\n",
    "It then creates a TransferClient and an AuthClient object and uses the Globus SDK function endpoint_autoactivate to ensure that the portal admin has a credential that permits access to the endpoint identified by host_id. Activation of the endpoint assumes that the endpoint is configured to trust the Globus IdP (as is the case with Globus Connect Personal)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import sys, random, uuid\n",
    "from globus_sdk import AuthClient, TransferClient, AccessTokenAuthorizer, TransferData\n",
    "\n",
    "host_id = 'ddb59aef-6d04-11e5-ba46-22000b92c6ec' # Endpoint for shared endpoint\n",
    "source_path = '/share/godata/' # Directory to copy data from\n",
    "email ='chard@uchicago.edu' # Email address to share with\n",
    "\n",
    "tc = TransferClient(AccessTokenAuthorizer(TRANSFER_TOKEN))\n",
    "ac = AuthClient(authorizer=AccessTokenAuthorizer(AUTH_TOKEN))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We use the Globus SDK function operation_mkdir to create a directory (in our example call, a UUID) on the existing endpoint with identifier host_id. \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "share_path = '/~/' + str(uuid.uuid4()) + '/'\n",
    "r = tc.operation_mkdir(host_id, path=share_path)\n",
    "print (r['message'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then we use the Globus SDK function create_shared_endpoint to create a shared endpoint for the new directory. At this point, the new shared endpoint exists and is associated with the new directory. However, only the creating user has access to this new shared endpoint at this point."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "shared_ep_data = {\n",
    "    'DATA_TYPE': 'shared_endpoint',\n",
    "    'host_endpoint': host_id,\n",
    "    'host_path': share_path,\n",
    "    'display_name': 'RDP shared endpoint',\n",
    "    'description': 'RDP shared endpoint'\n",
    "}\n",
    "\n",
    "r = tc.create_shared_endpoint(shared_ep_data)\n",
    "share_id = r['id']\n",
    "print(share_id)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To provide access to the requested data we copy data to the shared endpoint. We use sample data contained on the Globus Tutorial Endpoint under path \"/share/godata\".\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tc.endpoint_autoactivate(share_id)\n",
    "tdata = TransferData(tc, host_id, share_id, label='RDP copy data', sync_level='checksum')\n",
    "tdata.add_item(source_path, '/', recursive=True)\n",
    "r = tc.submit_transfer(tdata)\n",
    "o = tc.task_wait(r['task_id'], timeout=1000, polling_interval=10)\n",
    "print (r['task_id'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To confirm all data is in place for sharing we check the contents of the shared endpoint. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "for f in tc.operation_ls(share_id):\n",
    "    print (f['name'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We now share the endpoint with the appropriate user. We first use the Globus SDK function get_identities to retrieve the user identifier associated with the supplied email address; this is the user for whom sharing is to be enabled. (If this user is not known to Globus, an identity is created.) We then use the function add_endpoint_acl_rule to add an access control rule to the new shared endpoint to grant the specified user readonly access to the endpoint. The various elements in the rule_data structure specify, among other things:\n",
    "\n",
    "* principal_type: the type of principal to which the rule applies: in this case, ’identity’ —other options are ’group’, ’all_authenticated_users’, or ’anonymous’;\n",
    "* principal: as the principal_type is ’identity’, this is the user id with whom sharing is to be enabled;\n",
    "* permissions: the type of access being granted: in this case read-only (’r’), but could also be read and write (’rw’);\n",
    "* notify_email: an email address to which an invitation to access the shared endpoint should be sent; and\n",
    "* notify_message: a message to include in the invitation email.\n",
    "\n",
    "As our add_endpoint_acl_rule request specifies an email address, an invitation email is sent to the user. At this point, the user is authorized to download data from the new shared endpoint. \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "r = ac.get_identities(usernames=email)\n",
    "user_id = r['identities'][0]['id']\n",
    "rule_data = {\n",
    "    'DATA_TYPE': 'access',\n",
    "    'principal_type': 'identity', # Grantee is\n",
    "    'principal': user_id, # a user.\n",
    "    'path': '/', # Path is /\n",
    "    'permissions': 'r', # Read-only\n",
    "    'notify_email': email, # Email invite\n",
    "    'notify_message': # Invite msg\n",
    "    'Requested data is available.'\n",
    "}\n",
    "r = tc.add_endpoint_acl_rule(share_id, rule_data)\n",
    "print (r['message'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The shared endpoint will typically be left operational for some period, after which it can be deleted. Note that deleting a shared endpoint does not delete the data that it contains. The portal admin may want to retain the data for other purposes. If not, we can use the Globus SDK function submit_delete to delete the folder."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "r = tc.delete_endpoint(share_id)\n",
    "print (r['message'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Putting it all together\n",
    "\n",
    "The following code integrates the code above into a single callable function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from globus_sdk import TransferClient, TransferData, AccessTokenAuthorizer\n",
    "from globus_sdk import AuthClient\n",
    "import sys, random, uuid\n",
    "\n",
    "def rdp(host_id, # Endpoint for shared endpoint\n",
    "    source_path, # Directory to copy data from\n",
    "    email):      # Email address to share with\n",
    "    \n",
    "    # Instantiate transfer and auth clients\n",
    "    tc = TransferClient(AccessTokenAuthorizer(TRANSFER_TOKEN))\n",
    "    ac = AuthClient(authorizer=AccessTokenAuthorizer(AUTH_TOKEN))\n",
    "    tc.endpoint_autoactivate(host_id)\n",
    "\n",
    "    # (1) Create shared endpoint:\n",
    "    # (a) Create directory to be shared\n",
    "    share_path = '/~/' + str(uuid.uuid4()) + '/'\n",
    "    tc.operation_mkdir(host_id, path=share_path)\n",
    "    \n",
    "    # (b) Create shared endpoint on directory \n",
    "    shared_ep_data = {\n",
    "        'DATA_TYPE': 'shared_endpoint',\n",
    "        'host_endpoint': host_id,\n",
    "        'host_path': share_path,\n",
    "        'display_name': 'RDP shared endpoint',\n",
    "        'description': 'RDP shared endpoint'\n",
    "    }\n",
    "\n",
    "    r = tc.create_shared_endpoint(shared_ep_data)\n",
    "    share_id = r['id']\n",
    "\n",
    "    # (2) Copy data into the shared endpoint\n",
    "    tc.endpoint_autoactivate(share_id)\n",
    "    tdata = TransferData(tc, host_id, share_id, label='RDP copy data', sync_level='checksum')\n",
    "    tdata.add_item(source_path, '/', recursive=True)\n",
    "    r = tc.submit_transfer(tdata)\n",
    "    tc.task_wait(r['task_id'], timeout=1000, polling_interval=10)\n",
    "\n",
    "    # (3) Enable access by user\n",
    "    r = ac.get_identities(usernames=email)\n",
    "    user_id = r['identities'][0]['id']\n",
    "    rule_data = {\n",
    "        'DATA_TYPE': 'access',\n",
    "        'principal_type': 'identity', # Grantee is\n",
    "        'principal': user_id, # a user.\n",
    "        'path': '/', # Path is /\n",
    "        'permissions': 'r', # Read-only\n",
    "        'notify_email': email, # Email invite\n",
    "        'notify_message': # Invite msg\n",
    "        'Requested data is available.'\n",
    "    }\n",
    "    tc.add_endpoint_acl_rule(share_id, rule_data)\n",
    "\n",
    "    # (4) Ultimately, delete the shared endpoint\n",
    "    #tc.delete_endpoint(share_id)\n",
    "    \n",
    "rdp('ddb59aef-6d04-11e5-ba46-22000b92c6ec', '/share/godata/' , 'chard@uchicago.edu')"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}