OAuth2 setup

Topics:

Creating a project

  1. Create your project

    1. Go to your project management page.
    2. Select "Create a new OAuth2 data request project".
    3. Fill in some project details. (You can edit these later!)
    4. Click "Create project".

  2. View project details
    To view project details:

    1. Go to your project management page.
    2. Click on your project's name.
  3. Edit configuration
    To update project configuration:

    1. Go to your project management page.
    2. Find on your project name.
    3. Click the "Edit" button.

    (See below for more information on configuration items.)

  4. Set up OAuth2 credentials and URLs
    Go to your project detail page to get OAuth2 credentials. Use these to set up your OAuth2 authorization process. (Read more about OAuth2 authorization setup below for more details.)

  5. Test authorization with up to 20 test users.
    Once you've set up your OAuth2 authorization process, you can test user authorizations. (Note: your own account can be a test user too!)

    Try sending users to the "enrollment URL" you've specified to test the entire process.

  6. Test withdrawal/deauthorization and reauthorization
    Members can immediately withdraw/deauthorize a project on their connections management page.

    You can reauthorize a project by returning to its "signup URL".

    If a project changes requested permissions, new permissions will take effect only if/when a member has reauthorized the project.

  7. Test API data access
    If any test users have data from requested sources, it will become accessible to your project. Check that data access is working correctly.

  8. Test messaging
    If your project is planning to send messages to users, you can test this feature by sending messages to your test users.

  9. Test data upload
    If your project is planning to add or return data to member accounts, you can test the data upload process.

  10. Review project guidelines.
    Review our Activity Guidelines and ensure your project has good security and responsible data management practices before seeking project approval.

  11. Request project approval.
    Project approval is required to remove the 20 user cap. Once approved, we'll share your project with Open Humans members. For approval, we require any project classified as a "study" to have been reviewed and approved by an Institutional Review Board or equivalent ethics board.

    The project approval process is performed with feedback from the larger Open Humans community. Project approval is discussed publicly on our Discourse and project members are asked to weigh and ask questions to the project leads. A step-by-step guide can be found in our Approval How-To.

Closing a project

When you no longer wish to have new members join your project, edit your project's configuration to turn off "Active" status.

Configuration details

  • Study or activity?
    Are you doing research? If so, you're a "study". We expect all studies to have be approved by an Institutional Review Board (IRB) or equivalent ethical review.

    Non-study projects are also welcome, for example: data analysis tools, or projects to enable import of a certain type of data.

  • Project name
    Your project will be listed with this name.

  • Leader(s) or Principal Investigator(s)
    These will be listed in your project description.

  • Organization or Institution
    This will be listed in your project description.

  • Academic or non-profit?
    Select "yes" if your project's affiliation is academic or nonprofit. This affects how your project is listed in Open Humans.

  • Contact email for your project
    Members who wish to contact your project will use this email address. If your project sends messages, this email will be the "reply-to" in the emails members receive.

  • URL for general information about your project
    Members who want more information about your project can follow this URL to learn more.

  • Short description
    This description will be displayed for members when your project is listed.

  • Long description
    A longer description for members. (Note: This field isn't currently in use by our site, but might be later.)

  • Description of data you plan to upload to member accounts
    Describe any data your project is planning to add or return, via upload to the accounts of your project's members. Leave this blank if your project doesn't plan to add or return data via Open Humans.

  • Active
    Members can only join a project if it is "active". You should answer "Yes" during development to enable testing the join & authorization process.

    When you wish to close a study enrollment (i.e. no new members may join), remove "active" status for your project.

  • Badge image
    Badges should be circular images. Members that join your project will have this badge displayed on their profile.

  • Request sources access
    Select all data sources that you're requesting members to share with your project. New and updated data held by members will be shared in an ongoing manner as long as your project is authorized.

  • Are you requesting permission to message users?
    Answer "Yes" if you want your project to be authorized to send messages.

  • Are you requesting Open Humans usernames?
    Answer "Yes" if you want your project to have access to the usernames of your project members. This implicitly enables access to anything the user is publicly sharing on Open Humans.

    Username information is also potentially sensitive and/or identifying. You might want to avoid username access to improve security and potentially facilitate IRB review.

OAuth2 authorization setup

To facilitate the use of the OAuth2 API we offer two Python packages:

Of course, the API can also be accessed through the programming language of your choice without those packages. Below is a brief overview of how to use OAuth2 credentials and URLs to authorize a user from your app or website. If you're not familiar with OAuth2, we recommend you read the OAuth Wikipedia article and other online resources for general information about these processes.

  1. Direct your user to the Authorization URL.
    This URL should includethe following parameters:

    • "client_id" set to your Client ID

    • "response_type" set to "code"

    For example, for the authorization URL https://www.openhumans.org/direct-sharing/projects/oauth2/authorize/ and the client ID ABCDEFG1234567, you send your user to:
    https://www.openhumans.org/direct-sharing/projects/oauth2/authorize/?client_id=ABCDEFGJ1234567&response_type=code

  2. User returns with code.
    If the user authorizes your project, Open Humans will send them back to your "Redirect URL" with the parameter "code" set. For example, if your redirect URL is https://www.example.com/authorize_openhumans and the code is 123abc456def then we'll send the user to:
    https://www.example.com/authorize_openhumans/?code=123abc456def

    Your website or app will presumably know which user is associated with this code. You should immediately exchange the code for token data, which you'll store associated with your user's account.

  3. Exchange the code for a token.
    Your website or app needs to exchange the code for a more permanent token. Do this immediately: the code will expire soon after it's shared. Use your client ID and client secret as credentials for this transaction. Make sure you do this securely (use https).

    Use a POST request to the "access token URL" with the following data:

    • 'grant_type' set to 'authorization_code'

    • 'code' set to the value of the code you received

    • 'redirect_uri' set to the same redirect URL you've specified in Open Humans

    If everything is set correctly, the Open Humans website will return JSON data with values for 'access_token', 'refresh_token', and 'expires_in' (seconds). Keep this token and refresh token secure. The token can be used to access the OAuth2 project member API endpoint to retrieve this member's project member ID and other data.

    For example, the following Python code fragment exchanges a code for token data. (This uses the requests library.)

    import requests
    
    data = {
        'grant_type': 'authorization_code',
        'code': received_code,
        'redirect_uri': your_redirect_url
    }
    token_response = requests.post(
        open_humans_access_token_url,
        data=data,
        auth=requests.auth.HTTPBasicAuth(
            your_open_humans_client_id,
            your_open_humans_client_secret
        )
    )
    token_data = token_response.json()
    access_token = token_data['access_token']
    refresh_token = token_data['refresh_token']
    seconds_before_expiration = token_data['expires_in']

    Another example code-for-token exchange in JavaScript, using the request library.

    const request = require('request')
    
    request.post(
      {
        url: 'https://www.openhumans.org/oauth2/token/',
        auth: {
            'user': clientID,
            'pass': clientSecret
          },
        formData: {
            'grant_type': 'authorization_code',
            'code': code,
            'redirect_uri': redirectURI
        },
      }, function(err, res) {
        console.log(res.statusCode)
        console.log(res.body)
      })

  4. How to refresh your token.
    For security reasons, tokens expire after a period of time. To request a fresh token, use a POST request to the "access token URL" with the following data:

    • 'grant_type' set to 'refresh_token'

    • 'refresh_token' set to the refresh token you received

    If everything is set correctly, the Open Humans website will return JSON data with a new 'access_token', 'refresh_token', and 'expires_in' (seconds).

Webhooks

Deauthorization Webhook URL (optional)

A webhook can optionally be provided to automate handling when members leaving (deauthorize) an activity (for example, a request to erase personal data, to comply with GDPR). If provided, when a member leaves an activity a POST will be sent to that URL with JSON formatted data containing the following fields:

  • project_member_id: (string) identifying the project member performing deauthorization
  • erasure_requested: (true/false) whether the deauthorizing member is requesting the activity delete their personal data
  • timestamp: (string) ISO 8601 format timestamp of the deauthorization

Webhook secret (optional)

A webhook secret can optionally be provided, to be used to verify that incoming requests sent to the webhook are coming from Open Humans. If provided, POSTs to the webhook will use the secret to provide an hmac-sha1 a verification signature via a custom X-OpenHumans-Webhooks-Signature header. The value of this header is the string sha1= followed by the hmac-sha1 hexdigest of the payload.

For example, the secret: abcdefghijklmnop
would be used in combination with a payload:
{"project_member_id": "12345678", "erasure_requested": true, "timestamp": "2020-06-30T20:00:00.000000+00:00"}
to provide the following signature in the header: sha1=ebda5c0a38593a4350ad8401b7d8c8f1cd08ec67

# example Python code for generating this string
import hmac

key = 'abcdefghijklmnop'.encode('utf-8')
payload = '{"project_member_id": "12345678", "erasure_requested": true, "timestamp": "2020-06-30T20:00:00.000000+00:00"}'.encode('utf-8')
sig = 'sha1=' + hmac.hex