Authentication Model

Irakli Nadareishvili edited this page Oct 10, 2013 · 29 revisions

CAUTION: EARLY DRAFT.

Authentication

PMP API authentication complies with and implements OAuth2 Client Credentials Flow.

Production authentication domain is: http://auth.pmp.io (not: api.pmp.io)

Terminology

  1. User - a registered PMP API user, generally represented by a human being, that has the ability to grant access to their own data hosted in the PMP API
  2. PMP API - the content/data API.
  3. Auth API - an API largely independent of PMP API (even if co-hosted) the sole purpose of which is to provide authentication facilities.
  4. Client - applications interacting with PMP API. Examples: various iPhone, Android, web apps are all independent clients even if they belong to the same user.

Basic Principles:

  1. Users must be granted user/pass. This should be used by human beings (or: in manual API calls, until/if there's no UI), but cannot be used for anything but managing authentication and should NEVER be embedded in any client code.

  2. Using user/password a user can generate client_id and client_secret for each individual client it develops. client_id and client_secret do not auto-expire. They can be embedded and shipped with client code given that reasonable security precautions are made.

  3. Users must be able to revoke client_id/client_secret combo if they believe a client was compromised.

  4. Clients can and do use client_id/client_secret to request a temporary auth_token from Auth API. Authentication tokens have limited time to live and do expire. When issuing auth_token Auth API lets the client know the duration of validity of the token.

  5. Clients make all API calls to PMP API using auth_token they have pre-acquired.

API Endpoints

Also @see: Auth Property of User Profile

Client Credentials Management

List all client credentials associated with the user account

GET /auth/credentials

  1. Arguments: none
  2. Authentication: Basic Auth using user/pass over SSL
Issue new client credentials

POST /auth/credentials

with the optional HTTP BODY of:

scope={scope}&token_expires_in={num_seconds}&label={label}
  1. Arguments:
    • scope: can be "read" or "write" for most consumers. In the future version, "admin" or "root" consumers can also set "admin" scope. In the current version "admin" and "root" are granted manually.
    • token_expires_in - indicates how long the tokens issued for this client will last. Defaults to system-wide default.
  2. Authentication: Basic Auth using user/pass over SSL.
Revoke an existing client credential

DELETE /auth/credentials/{client_id}

  1. Arguments:
    • client_id: the client_id of the credential to be revoked.
  2. Authentication: Basic Auth using user/pass over SSL.

Token Management

NOTE: There's only one token per client_id. If you request a new token, it will keep returning the same value per client_id, for all consumers, until the token expires. If you need to refresh a token (e.g. if the existing one got compromised) you need to revoke it.

Issue a new token or grab the value of the existing one

To issue a new token or grab the value of the existing one

POST /auth/access_token

with the HTTP header of:

Content-Type: application/x-www-form-urlencoded
Authorization: Basic YzNhNWEzMzEtZWMwYS00MjczLTlkN2MtYzI2MjI5NWE1NTQyOjUwOTgyMjUwZDdjM2U3ZWE0NDQ3YTFlMg==

Where the long hash is base64-encoded, colon-separated client_id, client_secret. Example code in PHP:

<?php
$hash = base64_encode("c3a5a331-ec0a-4273-9d7c-c262295a5542" . ":" . "50982250d7c3e7ea4447a1e2");

The request must also include form-urlencoded parameter of:

grant_type=client_credentials

Example response:

{
   "access_token":"50982250d7c3e7ea4447a1e2",
   "token_type":"Bearer",
   "expires_in":3600,
   "scope":"read"
}
Revoke a token
DELETE /auth/access_token

with the HTTP header of:

Authorization: Basic YzNhNWEzMzEtZWMwYS00MjczLTlkN2MtYzI2MjI5NWE1NTQyOjUwOTgyMjUwZDdjM2U3ZWE0NDQ3YTFlMg==

Where the long hash is base64-encoded, colon-separated client_id, client_secret. Example code in PHP:

$hash = base64_encode("c3a5a331-ec0a-4273-9d7c-c262295a5542" . ":" . " 50982250d7c3e7ea4447a1e2");

Example response:

HTTP 204 No Content

Making PMP API Calls

All PMP API calls are made using Bearer Access tokens, by providing authorization HTTP Header, such as:

Authorization: Bearer 50982250d7c3e7ea4447a1e2