OAuth2 Module - Client REST Controller

What this controller does

This REST Controller provides dynamic OAuth client creation and management. Also it supports registration of SMART clients for the functionality of SMART's EHR Launch Flow.

Configuration Options

By default, the controller is mapped at ws/oauth/clientManagement however, users can change this mapping to their liking in the ClientManagementController.java file and change intercept-url mappings in WebModuleApplicationContext.xml

Video Demo

HOW TO's

Create a new OAuth client

To create a new OAuth Client through the controller you need to make the following request:

Request type : POST

Endpoint : /ws/oauth/clientManagement

Response : JSON (default)

Request Parameters :

Parameter	Required	Value	Description

Parameter	Required	Value	Description
username	YES	String	username of OpenMRS client developer
password	YES	String	password of OpenMRS client developer
name	YES	String	Name of the client application
description	NO	String	Some description of the client application
website	NO	String	Website of the client
redirectionUri	YES	String	Redirect Uri of the client. If SMART client, then give uri for "index.html".
clientType	YES	^{WEB_APPLICATION, USER_AGENT_BASED_APPLICATION, NATIVE_APPLICATION,SMART_APPLICATION}	Type of the client (Must be of only one permitted type)
scopes	YES	read, write, launch, patient/.read, patient/.write, patient/., user/.read, user/.write, user/., profile, openid	Scopes for the client. Include "launch" if client is a SMART client.
grantTypes	YES	^{authorization_code,implicit,password,client_credentials,refresh_token}	OAuth grant-types for the client (Multiple values can be selected)
isSmart	OPTIONAL	boolean	"true" if the client is a SMART client
launchUrl	OPTIONAL	String	If client is SMART client, then this must be the respective Launch Url for the SMART Appliction

Sample Request : http://localhost:8080/openmrs/ws/oauth/clientManagement?username=admin&password=Admin123&name=test2&description=some desci&website=www.abc.com&redirectionUri=http://localhost:8080/smart/index.html&clientType=SMART_APPLICATION&scopes=launch,read,write&grantTypes=authorization_code,implicit,password,refresh_token&isSmart=true&launchUrl=http://localhost:8080/smart/launch.html

Sample Response :

Sample Response (POST)

{
    "id": 42,
    "name": "test2",
    "description": "some desci",
    "clientType": "SMART_APPLICATION",
    "clientIdentifier": "iakbnhm081f8399q94v5bhd01l",
    "clientSecret": "gvkq41p0bsc8au9bqjteue578o",
    "website": "www.abc.com",
    "redirectUri": [
        "http://localhost:8080/smart/index.html"
    ],
    "uuid": "72bf7c1d-707d-4bfc-9d07-87ff948b1b7b",
    "creator": "admin",
    "dateCreated": 1503856161000,
    "changedBy": "admin",
    "dateChanged": 1503856161000,
    "voided": false,
    "dateVoided": null,
    "voidReason": null,
    "voidedBy": null,
    "accessTokenValiditySeconds": 600,
    "refreshTokenValiditySeconds": 600,
    "scopes": [
        "read",
        "write"
    ],
    "grantType": [
        "implicit",
        "refresh_token",
        "password",
        "authorization_code"
    ]
	"smartId": 6,
   	"launchUrl": "http://localhost:8080/smart/launch.html"
}

2. View Clients for a Client developer

To view clients for a client developer, you need to make the followig request :

Request type : GET

Endpoint : /ws/oauth/clientManagement

Response : JSON (default)

Request Parameters :

Parameter	Required	Value

Parameter	Required	Value
username	YES	String (Client developer username)
password	YES	String (Client developer password)
client_id	OPTIONAL	String (Giving client_id will filter results and display the exact id)
isSmart	OPTIONAL	boolean (Filters all SMART clients)

Sample Request : http://localhost:8080/openmrs/ws/oauth/clientManagement?username=admin&password=Admin123

Sample Response (GET)

[
	{
        "id": 39,
        "name": "finaldemo2",
        "description": "somedesci",
        "clientType": "WEB_APPLICATION",
        "clientIdentifier": "finaldemo2",
        "clientSecret": "odqt3g0hjcnl39hbsi22t4ch4e",
        "website": "www.abc.com",
        "redirectUri": [],
        "uuid": "b072ecce-20f2-4752-8b4a-52c7715d281e",
        "creator": "admin",
        "dateCreated": 1503740189000,
        "changedBy": "admin",
        "dateChanged": 1503740190000,
        "voided": false,
        "dateVoided": null,
        "voidReason": null,
        "voidedBy": null,
        "accessTokenValiditySeconds": 600,
        "refreshTokenValiditySeconds": 600,
        "scopes": [
            "read",
            "write"
        ],
        "grantType": [
            "refresh_token",
            "implicit",
            "password",
            "authorization_code"
        ]
    },
    {
        "id": 40,
        "name": "finaldemo2",
        "description": "somedesci",
        "clientType": "WEB_APPLICATION",
        "clientIdentifier": "finaldemo2",
        "clientSecret": "39mnotbnr85nh3sp8nop2uusua",
        "website": "www.abc.com",
        "redirectUri": [
            "sanatt.me"
        ],
        "uuid": "1f40c348-cae0-4420-b0ba-838c5dd2a4b2",
        "creator": "admin",
        "dateCreated": 1503740890000,
        "changedBy": "admin",
        "dateChanged": 1503740890000,
        "voided": false,
        "dateVoided": null,
        "voidReason": null,
        "voidedBy": null,
        "accessTokenValiditySeconds": 600,
        "refreshTokenValiditySeconds": 600,
        "scopes": [
            "read",
            "write"
        ],
        "grantType": [
            "refresh_token",
            "implicit",
            "password",
            "authorization_code"
        ]
    }
]

3. To delete an OAuth Client

Request type : DELETE

Endpoint : /ws/oauth/clientManagement

Response : String (Default)

Request Parameters :

Parameter	Required	Value

Parameter	Required	Value
username	YES	String (Client developer username)
password	YES	String (Client developer password)
client_id	YES	String (Client_id of the client to be deleted)
isSmart	OPTIONAL	boolean (Provide if client is a SMART client)

Alternately,

Parameter	Required	Value

Parameter	Required	Value
client_id	YES	String
client_secret	YES	String
isSmart	OPTIONAL	boolean

Sample Request : http://localhost:8080/openmrs/ws/oauth/clientManagement?client_id=mydemo&username=admin&password=Admin123

OR http://localhost:8080/openmrs/ws/oauth/clientManagement?client_id=test9&client_secret=e7jm54j15kqdhud8bj4a1143q3

Sample Response : "Client deleted"

4. To update the details of an OAuth Client

This request will make changes to the fields as specified in the request and return an updated version of the client

Request type : PUT

Endpoint : /ws/oauth/clientManagement

Response : JSON (default)

Request Parameters :

Parameter	Required	Value	Description

Parameter	Required	Value	Description
username	YES	String	username of OpenMRS client developer
password	YES	String	password of OpenMRS client developer
client_id	YES	String	client_id of OAuth client
name	OPTIONAL	String	Name of the client application
description	OPTIONAL	String	Some description of the client application
website	OPTIONAL	String	Website of the client
redirectionUri	OPTIONAL	String	Redirect Uri of the client
clientType	OPTIONAL	^{WEB_APPLICATION, USER_AGENT_BASED_APPLICATION, NATIVE_APPLICATION,SMART_APPLICATION}	Type of the client (Must be of only one permitted type)
scopes	OPTIONAL	read, write, launch, patient/.read, patient/.write, patient/., user/.read, user/.write, user/., profile, openid	Scopes for the client
grantTypes	OPTIONAL	^{authorization_code,implicit,password,client_credentials,refresh_token}	OAuth grant-types for the client (Multiple values can be selected)
isSmart	OPTIONAL	boolean	"true" if SMART client
launchUrl	OPTIONAL	String	Launch Url for SMART client