Workflows to Request and Manage Client Credentials

From wiki.gpii
Jump to: navigation, search

Introduction

A GPII security issue is to protect the communication between GPII apps and GPII Cloud. That means, at receiving http requests, GPII Cloud needs to ensure these requests are sent from authorized GPII apps rather than random sources.

After some research, the proposed solution is to use OAuth 2.0 Resource Owner Password Credentials Grant. With this OAuth 2.0 grant type, each GPII app will be assigned an unique client credential, a pair of client id and secret. This client credential will be stored within the GPII app. Before accessing any user information from GPII Cloud, the GPII app needs to send the client credential to GPII Cloud where the client credential will be verified to ensure the party at the other end is an authorized GPII app.

Due to the technical involvement of OAuth 2.0 and the use of client credentials, this wiki page suggests three possible workflows of how a GPII app can request a client credential from GPII Cloud. These workflows are to provide initial thinking. The understanding of how people/administrators prefer to install/manage GPII apps will help to select and improve one of these workflows.

The finalization of the workflow is required before the implementation design can start.

Terminology

This wiki page uses the following terms:

  • GPII app: A GPII application that is installed to a user's device. It includes two applications:
    • GPII app: It reads in a GPII user token and applies GPII preferences associated with the token to this device.
    • GPII Manager: It manages the input (or the request) and revoke of the GPII client credential on that machine. The use of GPII Manager requires the admin access on that machine - the user will be prompted to login as an admin.
  • Client: A client here means a GPII application, not a person or a GPII user.
  • Client Credential: One client credential, which is a pair of unique client id and secret, is assigned to one or more GPII applications by GPII Cloud. It is verified by GPII Cloud before any user information can be requested from GPII Cloud by a GPII app.
  • OAuth: In this wiki page, OAuth refers to The OAuth 2.0 authorization framework that enables a third-party application to obtain limited access to an HTTP service.

Using OAuth Client Credential

Before a GPII app requests any user information from GPII Cloud, it first needs to request an access token by providing its OAuth client credential:

Auth-how to use client id and secret.png


  1. The GPII application sends a request with these request parameters: OAuth2 client id, OAuth2 client secret, GPII token;
  2. GPII Cloud verifies these information. If matches, sends back an access token;
  3. The GPII application then sends http requests along with the assigned access token to access user information from GPII Cloud.

Revoking OAuth Client Credential

In the case that a client credential is compromised, the person who manages the associated GPII app can revoke it and re-request a new client credential from GPII Cloud. Once a client credential is revoked, GPII Cloud will reject requests sent from sources that use this client credential to prove their identity.

Use cases

These use cases are considered:

  1. Public machines
    1. An admin installs onsite machines by replicating a pre-made disk image, where one client credential will be shared by multiple machines;
    2. An admin installs machines individually by running the application installer, where each GPII app can request its own unique client credential;
    3. A mix of both
  2. Machines shared by trusted parties, such as a family shared computer (similar to use case 1.2)
  3. Private machines (similar to use case 1.2)

Note: The risk of sharing one OAuth Client Credential among multiple machines is, in the case that this client credential is compromised and needs to be revoked, all these machines will lose their GPII cloud access.

Options to Request Client Credential for GPII App

The input (or the request) and the revoke of a client credential can be performed with either one of these 2 methods:

  1. At the installation
  2. Via "GPII manager" application

In the case that the installing person choose to skip the installation step that provides a client credential, the GPII application can continue to perform local adaptations, such as reading and reacting to GPII Bearer tokens. However, this GPII application cannot perform any actions that GPII Cloud needs to be involved. To allow the GPII application to gain access on user information from GPII Cloud, a client credential needs to be input/requested from GPII Cloud via "GPII manager" application.

Each workflow only shows the process to input/request a client credential. Revoking process is not presented but will be following the same strategy suggested by each workflow.

Note: The UI sketches in this section are for clarifying the workflow. They are nowhere near actual designs for interfaces we might show to the user.

Option 1: Separately Request Client Credential from GPII Central Website

In this option, the installing person or the person who manages GPII application will:

  1. Login to the central GPII account management system and request a client credential;
  2. Input the requested client credential into the GPII app at the installation or via "GPII manager".

Workflow Mockups

Step 1: Request a client credential from GPII account management system;

Step 1.1: Login with a GPII account

Login.png

Step 1.2: Go to the page "Manage OAuth 2.0 Client Credentials"

This page is the entry point for creating a new client credential or managing all existing client credentials.

Note:

  1. The "delete" button is to delete multiple credential records: checked checkboxes of multiple records -> click the "delete" button.
  2. Deleting one single record can be achieved by clicking the "remove" icon in the "actions" column.
  3. The deletion of credential records doesn't remove these records completely from the database. These records are permanently revoked for auditing purpose. The revoked process is not undoable.
Manage credentials.png

Step 1.3: Create a New OAuth 2.0 Client Credential

Click the "Create an OAuth 2.0 Client Credential" button:

Create A Credential.png

Step 1.4: Create a Credential for a GPII Application

Select the application type: GPII Application

Create for Native GPII App - Step 1.png

Click the "Create" button -> Client credential is generated -> the user copies the client id and secret that will be input at installing GPII application or via GPII manager

Create for Native GPII App - Step 2.png

Step 1.5: If the user needs to download a client credential record

Click the "download" icon listed on the "actions" column for each existing client credential record on the "Manage OAuth 2.0 Client Credentials" page.

The JSON format of a client credential record assigned to a GPII application:

{
  "installed": {
    "client_id": "53684234497-hgd07kcq01tjod4mg0rt8k8omt2phak5",
    "client_secret": "ClMxQY6JM1lwfMp5Gr_9EMw4",
    "name": "Bakerfield AJC - PC1",
    "token_uri": "https://flowmanager.gpii.net/oauth2/access_token"
  }
}

Step 2: Input client credential into GPII app

Option 1: Input at the installation

Input GPII client credential at installation.png

Option 2: Input via "GPII manager" application

1. start "GPII manager" application

GPII Manager1.png

2. Click "Set GPII Client Credential"

GPII Manager2.png

3. Enter the machine admin login

GPII Manager3.png

4. Input the client credential and save

GPII Manager4.png

Pros and Cons

Pros: Secured by requesting client credentials at a central website. No risk to leak GPII user login.

Cons: Might be overwhelming for non-tech users.

Option 2: Login and Request Client Credential within GPII App

In this option, the installing person or the person who manages GPII application will login with own GPII account and request the client credential within the GPII app. The communication to request the client credential from GPII Cloud and the save of the credential are automatically performed by the GPII app.

Workflow Mockups

The same workflow is shared at the installation and the use of "GPII Manager". The mockups skip the steps to start "GPII Manager", which can be referred to at the option 1.

Input OAuth2 Client Credential at Installation.png


Request client credential - success.png

Pros and Cons

Pros: Simplest workflow.

Cons: Risk of the stolen of user's GPII account login (user name and password) if a malicious fake GPII installer is downloaded and executed.

Option 3: Request Client Credential within GPII App while Login at GPII website

In this option, the installing person or the person who manages GPII application will:

  1. Request the client credential within the GPII app;
  2. The GPII app finds and opens an available http port, opens the GPII central account management system in a browser, with the port number as an url parameter;
  3. The person logins the own GPII account, enter the required information, either choose to create a new client credential or pick an existing client credential;
  4. GPII Cloud creates and returns a short lived token and tells the browser to redirect the token back to the GPII app at the URL of http://localhost:{given_port_number}. (Note: The client credential is not directly sent back in the redirect URL is to avoid the redirect URL being saved into the browser history);
  5. The GPII app then sends the token to GPII Cloud to request the client credential;
  6. The GPII app receives and saves the client credential.

Workflow Mockups

The same workflow is shared at the installation and the use of "GPII Manager". The mockups skip the steps to start "GPII Manager", which can be referred to at the option 1.

Request client credential1.png


Request client credential2.png


Request client credential3.png


Request client credential - success.png

Pros and Cons

Pros: A balanced approach of option 1 & 2 to accommodate both the security and users' convenience.

Cons: Not as simple as option 2 but more secured.

Manage/Create/Edit OAuth 2.0 client credentials

Once client credential(s) are created, admins, or GPII managers, can manage, edit, or even create new, OAuth 2.0 client credentials at a central GPII account management system.

At the moment that this wiki page is written (May 25, 2017), a live GPII site already exists for GPII users to define their privacy settings. One possibility is to extend this website to include the workflow described in this section.

Login

Login with GPII user account:

Login.png

Manage OAuth 2.0 Client Credentials

This page is the entry point to create a new client credential or manage all existing client credentials.

Manage credentials.png

Note:

  1. The "Revoke" button is to revoke multiple credential records: checked checkboxes of multiple records -> click the "revoke" button. All selected client credentials will be reoked.
  2. Revoking one single record can be achieved by clicking the "revoke" icon in the "actions" column.
  3. The revoking process is not irreversible. The credentials that have been revoked are permanently revoked.

Create a New OAuth 2.0 Client Credential

Click the "Create an OAuth 2.0 Client Credential" button:

Create A Credential.png

Create a Credential for a GPII Application

Create a Credential for a GPII Application - Step 1

Select the application type: GPII Application

Create for Native GPII App - Step 1.png

Create a Credential for a GPII Application - Step 2

Click the "Create" button

Create for Native GPII App - Step 2.png

Create a Credential for a Web Application

GPII authorization server already supports OAuth2 authorization code grant that is for authorizing web applications. This sketch takes that grant type into consideration.

If the selected application type is "Web Application"

Create for a Web App.png

Edit a Credential for a GPII Application

Click the "edit" icon listed on the "actions" column for each existing client credential record on the "Manage OAuth 2.0 Client Credentials" page. If the record to edit is for a GPII application:

Edit an Credential for Native GPII App.png

Edit a Credential for a web Application

Click the "edit" icon on a client credential assigned to a web application:

Edit an Credential for a Web App.png

Download a Client Credential Record

Click the "download" icon listed on the "actions" column for each existing client credential record on the "Manage OAuth 2.0 Client Credentials" page.

The JSON format of a client credential record assigned to a GPII application:

{
  "installed": {
    "client_id": "53684234497-hgd07kcq01tjod4mg0rt8k8omt2phak5",
    "client_secret": "ClMxQY6JM1lwfMp5Gr_9EMw4",
    "name": "Bakerfield AJC - PC1",
    "token_uri": "https://flowmanager.gpii.net/oauth2/access_token"
  }
}

The JSON format of a client credential record assigned to a web application:

{
  "installed": {
    "client_id": "53684234497-hgd07kcq01tjod4mg0rt8k8omt2phak5",
    "client_secret": "ClMxQY6JM1lwfMp5Gr_9EMw4",
    "name": "IDRC Website",
    "auth_uri": "https://flowmanager.gpii.net/oauth2/authorize",
    "token_uri": "https://flowmanager.gpii.net/oauth2/access_token",
    "origins": ["https://idrc.ocadu.ca"],
    "redirect_uris": ["https://idrc.ocadu.ca/oauth_callback"]
  }
}

Note

The mockups above assume users already have GPII accounts. Please consider the UX design that allows users to register GPII accounts if they don't have one.

References