Have you implemented OpenMRS? Please participate in the Implementation Site Survey. If you already have, thank you!
Child pages
  • OAuth2 Module - Client REST Controller
Skip to end of metadata
Go to start of metadata

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

  1. 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 :

ParameterRequiredValueDescription
usernameYESString

username of OpenMRS client developer

passwordYESStringpassword of OpenMRS client developer
nameYESStringName of the client application
descriptionNOString

Some description of the client application

websiteNOStringWebsite of the client
redirectionUriYESStringRedirect Uri of the client. If SMART client, then give uri for "index.html".
clientTypeYES
WEB_APPLICATION, USER_AGENT_BASED_APPLICATION, NATIVE_APPLICATION,SMART_APPLICATION

Type of the client (Must be of only one permitted type)

scopesYESread, write, launch, patient/*.read, patient/*.write, patient/*.*, user/*.read, user/*.write, user/*.*, profile, openidScopes for the client. Include "launch" if client is a SMART client.
grantTypesYES
authorization_code,implicit,password,client_credentials,refresh_token

OAuth grant-types for the client (Multiple values can be selected)

isSmartOPTIONALboolean"true" if the client is a SMART client
launchUrlOPTIONALStringIf 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 :

 

ParameterRequiredValue
usernameYESString (Client developer username)
passwordYESString (Client developer password)
client_idOPTIONALString (Giving client_id will filter results and display the exact id)
isSmartOPTIONALboolean (Filters all SMART clients)

 

Sample Requesthttp://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 :

ParameterRequiredValue
usernameYESString (Client developer username)
passwordYESString (Client developer password)
client_idYESString (Client_id of the client to be deleted)
isSmartOPTIONALboolean (Provide if client is a SMART client)

Alternately,

ParameterRequiredValue
client_idYESString
client_secretYESString
isSmartOPTIONALboolean

 

Sample Requesthttp://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 :

ParameterRequiredValueDescription
usernameYESString

username of OpenMRS client developer

passwordYESString

password of OpenMRS client developer

client_idYESStringclient_id of OAuth client
nameOPTIONALStringName of the client application
descriptionOPTIONALString

Some description of the client application

websiteOPTIONALStringWebsite of the client
redirectionUriOPTIONALStringRedirect Uri of the client
clientTypeOPTIONAL
WEB_APPLICATION, USER_AGENT_BASED_APPLICATION, NATIVE_APPLICATION,SMART_APPLICATION

Type of the client (Must be of only one permitted type)

scopesOPTIONALread, write, launch, patient/*.read, patient/*.write, patient/*.*, user/*.read, user/*.write, user/*.*, profile, openidScopes for the client
grantTypesOPTIONAL
authorization_code,implicit,password,client_credentials,refresh_token
OAuth grant-types for the client (Multiple values can be selected)
isSmartOPTIONALboolean"true" if SMART client
launchUrlOPTIONALStringLaunch Url for SMART client
  • No labels