Master Key APIs

Background

Currently content update is done by the user who created it which creates problem and is complex in scenarios where an admin want to update content by retired user. There should be an easy way to allow users to update content at the same time it should have authentication.

Problem Statement 1

What is the approach to generate the key?

Solution 1

Create JWT token with data passed upon. A JWT token will be created using secret key and below data

channel
name
description
organisationId
createdBy
createdOn

Solution 2

Custom generated time based key.

Solution 3

Using keycloak to generate an verify token to be used as masterkey.

Pros and Cons

Key Generation Approach	Pros	Cons

Key Generation Approach

Pros

Cons

JWT

no need to store the key in DB

Custom

method is available so negligible time consuming

key needs to be stored in db

Keycloak

comparatively faster to implement

no support for channel or organisation based key

key would expire based on keycloak configuration

Problem Statement 2

What are the APIs required to manage master keys?

API Specifications

Create API

name and channel / organisationId is mandatory.

URL:

POST /v1/auth/masterkey/create

Headers:

Authorization
x-authenticated-user-token

Request Params:

param name	type	description

param name	type	description
channel	String	channel for which master key is applicable for, if not provided can be calculated from organisationId
name	String	consumer name
organisationId	String	organisationId for which master key is applicable for, if not provided can be calculated from channel

Response Params:

param name	type	description

param name	type	description
key	String	generated master key, mapped with the requested channel/organisationId and name

Errors:

status code	error code	error message

status code	error code	error message
400	INVALID_ORG_DATA	Given Organization Data doesn't exist in our records. Please provide a valid one.
400	MANDATORY_PARAMETER_MISSING	Mandatory parameter {channel/organisationId, name} is missing.
400	PARAMETER_MISMATCH	Mismatch of given parameters: channel, organisationId.
400	KEY_EXISTS	Key exists for given channel {} and consumer {}

Sample Request and Response:

Request

{
	request : {
		"channel" : "sunbird",
		"name" : "DikshaImplTeam",
		"orgId" : "01262366359399628812"
	}
}

Response

{
  "id": "api.auth.masterkey.create",
  "result": {
		"key" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjaGFubmVsIjoic3VuYmlyZCIsIm5hbWUiOiJEaWtzaGFJ bXBsVGVhbSIsImNyZWF0ZWRCeSI6MTUxNjIzOTAyMiwiY3JlYXRlZE9uIjoxNTE2MjM5MDIyLCJleHBpcmVzT24iOjE1MTYyNDkwMjIsIm9yZ0lkIjoiMjM0NTY1NDU2In0.Cs5-FW7OHip6njkQvMP6zpIVB5Q-xLLgz_jnYW3zPOw"
	}
}

Verify API

URL:

POST /v1/auth/masterkey/verify

Headers:

Authorization

Request Params:

param name	type	description

param name	type	description
key	String	master key to verify

Response Params:

param name	type	description

param name	type	description
channel	String	channel name related to master key
name	String	consumer name
description	String	describes the purpose for master key
organisationId	String	organisation Id mapped with key
createdBy	String	userId of the person who created the key
createdOn	timestamp	timestamp when master key was created

Errors:

status code	error code	error message

status code	error code	error message
400	INVALID_KEY	Given master key is invalid
400	MANDATORY_PARAMETER_MISSING	Mandatory parameter key is missing.

Sample Request and Response:

Request

{
	request : {
		"key" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjaGFubmVsIjoic3VuYmlyZCIsIm5hbWUiOiJEaWtzaGFJ bXBsVGVhbSIsImNyZWF0ZWRCeSI6MTUxNjIzOTAyMiwiY3JlYXRlZE9uIjoxNTE2MjM5MDIyLCJleHBpcmVzT24iOjE1MTYyNDkwMjIsIm9yZ0lkIjoiMjM0NTY1NDU2In0.Cs5-FW7OHip6njkQvMP6zpIVB5Q-xLLgz_jnYW3zPOw"
	}
}

Response 

{
  "id": "api.auth.masterkey.verify",
  "result": {
  		"channel": "sunbird",
  		"name": "DikshaImplTeam",
		"description": "organisation content"
		"organisationId": "01262366359399628812"
  		"createdBy": "00dd6646-be73-4fb0-b676-ccd01bda085e",
  		"createdOn":1548932815386,
  	}
}

Delete API

URL:

POST /v1/auth/masterkey/delete

Headers:

Authorization
x-authenticated-user-token

Request Params:

param name	type	description

param name	type	description
channel	String	channel for which master key needs to be deleted
name	String	consumer name
organisationId	String	organisationId for which master key needs to be deleted

Response Params:

None

Errors:

status code	error code	error message

status code	error code	error message
400	MANDATORY_PARAMETER_MISSING	Mandatory parameter {channel/organisationId, name} is missing.
400	KEY_NOT_EXISTS	Key does not exists for given channel {} and consumer {}

Sample Request and Response:

Request 

{
	request : {
		"channel" : "sunbird",
		"name" : "DikshaImplTeam",
		"orgId" : "01262366359399628812"
	}
}

Response

{
  "id": "api.auth.masterkey.delete",
  "responseCode": "OK",
  "result": {
	}
}

Problem Statement 3

What is the DB design for storing information about master keys?

approach 1:

JWT token Table Structure

column	type	description

column	type	description
channel*	text	consist user provide channel name
name*	text	provided by user
organisationId	text	provided by user or root org id mapped with channel
createdBy	text	user id who created the master key
createdOn	timestamp	created time

approach 2:

custom generated key

column	type	description

column	type	description
channel*	text	consist user provide channel name
name*	text	provided by user
organisationId	text	provided by user or root org id mapped with channel
key	text	holds custom generated key
createdBy	text	user id who created the master key
createdOn	timestamp	created time

Problem Statement 4

How to use generated master key to bypass existing user authentication?

approach 1:

master key will be passed in X-authenticated-user-token
use an extra header (X-authentication-type) declaring the type of authentication as master( for master key and user for user authentication).

approach 2:

extra header (X-authentication-master-key) to pass master key.
If above header is present it supersedes the user authentication

Pros and Cons

Key Usage Approach	Pros	Cons

Key Usage Approach	Pros	Cons
X-authentication-type	In future it can support additional authentication types