Globus-identity-profile-group-tutorial.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introduction\n",
    "\n",
    "### Requirements\n",
    "#### Globus Nexus Client\n",
    "\n",
    "* git clone https://github.com/globusonline/python-nexus-client\n",
    "* python setup.py install\n",
    "\n",
    "\n",
    "#### Create a Globus Account\n",
    "* https://www.globus.org/SignUp\n",
    "\n",
    "#### Save Access Token to a File\n",
    "* curl -k --user &lt;username&gt;  'https://nexus.api.globusonline.org/goauth/token?grant_type=client_credentials'\n",
    "* Copy the \"access_token\" from the response into a file \"globus-token\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Background\n",
    "\n",
    "Configure the following variables required to use the client: the server address, username, and the file in which your access token is stored. \n",
    "\n",
    "You can then create a Globus Nexus client object to interact with Globus Nexus via its REST APIs. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "from nexus import GlobusOnlineRestClient\n",
    "\n",
    "server = \"nexus.api.globusonline.org\" \n",
    "username = \"INSERT USERNAME\"\n",
    "token_file = \"/PATH_TO_TOKEN/globus-token\"\n",
    "tutorial_group_id = \"50b6a29c-63ac-11e4-8062-22000ab68755\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "with open(token_file, 'r') as f:\n",
    "    globus_token = f.read()\n",
    "\n",
    "config ={\"server\": server,\n",
    "        \"client\": username, \n",
    "        \"goauth_token\": globus_token, \n",
    "        \"client_secret\": None}\n",
    "client = GlobusOnlineRestClient(config)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Interacting with Globus identities and profiles\n",
    "\n",
    "The following steps will show you how to interact with Globus identities and profiles. \n",
    "### Retrieve a user profile\n",
    "The profile includes information such as full name, email address, and institution. Additionally, custom attributes can be associated with a Globus identity. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "response, data = client.get_user(username)\n",
    "print data[\"fullname\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Retreive other attributes of the user profile\n",
    "For example, profiles include any linked public SSH keys. These keys are often used for automatic provisioning of user accounts."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "print list(data.iteritems())\n",
    "print \n",
    "print data[\"ssh_pubkeys\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Update a user profile\n",
    "Many profile attributes can be updated, a notable exception is the username."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "response, data = client.put_user(username, fullname=\"Jeff Smith\")\n",
    "print data[\"fullname\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Interacting with Globus Groups\n",
    "\n",
    "The following steps will show you how to interact with Globus Groups. \n",
    "\n",
    "### Get the groups for a user\n",
    "You can set filters on user roles (e.g., admin, manager, member) and memberships (active, invited, pending, suspended, rejected). Groups include information such as name and description, parent groups, and links to retrieve and manage memberships, policies, and email templates. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "response, data = client.get_group_list(my_roles=[\"member\"])\n",
    "for group in data:\n",
    "    print \"%s (%s)\" % (group[\"name\"], group[\"id\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Retrieve an individual group\n",
    "All Globus groups are uniquely identified by an id. Assuming the policies of the group permit visibility, you can retrieve a summary of the group's attributes, policies regarding membership and invitation as well as the requesting user's membership status and role via the unique id. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "response, data = client.get_group_summary(tutorial_group_id)\n",
    "print data[\"name\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Retrieve group members\n",
    "Note: the policies associated with this group do not allow non-members to see other members. If you are not a member yet, you should see an error response. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "response, data = client.get_group_members(tutorial_group_id)\n",
    "print response"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Request to join the group \n",
    "Individual users can request to join groups (assuming group policies permit it). Administrators may also invite users to join groups via their username or email address. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "response, data = client.post_membership(tutorial_group_id, usernames=[username])\n",
    "print data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Retreive the members of this group\n",
    "After your membership has been approved, you should be able to view the other members of the group. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "response, data = client.get_group_members(tutorial_group_id)\n",
    "for member in data[\"members\"]:\n",
    "    print member[\"name\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Create a new group\n",
    "Users may create and manage their own groups. The only required information when creating a group is a name. After creation, you can change group attributes, invite users, and modify the group policies. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "response, data = client.post_group(\"%s's first group\" % username)\n",
    "created_group_id = data[\"id\"]\n",
    "print \"Group created with id: %s\" % created_group_id"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Invite other users to join this group \n",
    "You can invite users to join your group using their Globus identity name or email address. Try to invite a user using your email adress. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "response, data = client.post_membership(created_group_id, emails=[\"myemailaddress\"])\n",
    "print data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Interacting directly with the REST API\n",
    "\n",
    "The Globus Nexus REST API provides additional capabilities (a superset) that aren't supported via the Python client.\n",
    "\n",
    "### Retrieve a user profile via the REST API"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "response, data = client._issue_rest_request('/users/%s' % username)\n",
    "print data[\"fullname\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Retrieve any linked credentials\n",
    "If your Globus account has linked credentials (e.g., X509 certificates or SSH keys), you can retrieve a list as follows. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "response, data = client._issue_rest_request('/users/%s/credentials' % username)\n",
    "print data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Other REST API calls\n",
    "Similarly, group operations can be called via the REST API. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "response, data = client._issue_rest_request('/groups?my_roles=member')\n",
    "for group in data:\n",
    "    print group['name']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "response, data = client._issue_rest_request('/groups/%s/policies' % tutorial_group_id)\n",
    "print \"Memberships visible publicly: %s\" % data[\"group_member_visibility\"][\"value\"][\"public\"][\"value\"]"
   ]
  }
 ],
 "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.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}