Skip to end of metadata
Go to start of metadata

Types of code grants

OAuth as implemented in Transmart supports different grant types:

Authorization Code Grant

Appropriate for non-web applications (e.g. R client). Example exchange (in dev):

// Send resource owner here
http://localhost:8080/transmart/oauth/authorize?response_type=code&client_id=api-client

// User agent gets forwarded and an authorization code (a short value such as pztwSa) is presented,
// which should be copy pasted into the client.
// Client then issues this request to exchange the code for an access and a refresh token
curl -X POST \
     -d "client_id=api-client" \
     -d "client_secret=api-client" \
     -d "grant_type=authorization_code" \
     -d "code=pztwSa" \
	 http://localhost:8080/transmart/oauth/token
// result
{  
   "access_token":"260d0fb8-a00c-419b-897b-da04fd8a94a7",
   "token_type":"bearer",
   "refresh_token":"4f02a629-136c-4eac-8411-8aa710b8f521",
   "expires_in":43199,
   "scope":"read write"
}
// use as
curl -H 'Accept: application/hal+json' -H 'Authorization: Bearer 260d0fb8-a00c-419b-897b-da04fd8a94a7' -v http:/localhost:8080/transmart/studies
// when the access token has expired, a new one can be obtained with the refresh token
curl -X POST \
     -d "client_id=api-client" \
	 -d "client_secret=api-client" \
     -d "grant_type=refresh_token" \
     -d "refresh_token=4f02a629-136c-4eac-8411-8aa710b8f521" \
     http://localhost:8080/transmart/oauth/token
{  
   "access_token":"f7acaacd-cbc9-43ed-8c20-4ed3c26cd10d",
   "token_type":"bearer",
   "refresh_token":"41ff2640-0309-47ea-9900-9e02de6b2df2",
   "expires_in":43199,
   "scope":"read write"
}

 

Implicit Grant

Appropriate for web applications with which the user's credentials (password) should not be shared. Example exchange:

http://localhost:8080/transmart/oauth/authorize?response_type=token&client_id=glowingbear-js&redirect_uri=http%3A%2F%2Flocalhost%3A8001%2Fconnections
// fw to http://localhost:8001/connections#access_token=eb8b1231-932e-4546-835f-ee24e6c23902&token_type=bearer&expires_in=43199&scope=read%20write
// validate token -- the application should verify that the clientId is the correct application (itself)
curl -H 'Authorization: Bearer eb8b1231-932e-4546-835f-ee24e6c23902' -v http://localhost:8080/transmart/oauth/inspectToken
{
  "clientId": "glowingbear-js",
  "redirectUri": "http://localhost:8001/#/login",
  "token": {
    "additionalInformation": {
    },
    "class": "org.springframework.security.oauth2.common.DefaultOAuth2AccessToken",
    "expiration": "2015-06-12T21:30:04Z",
    "expired": false,
    "expiresIn": 43174,
    "refreshToken": null,
    "scope": 
    [
      "write",
      "read"
    ],
    "tokenType": "bearer",
    "value": "eb8b1231-932e-4546-835f-ee24e6c23902
  },
  "principal": {
    "id": 1,
    "username": "admin",
    "userRealName": "Sys Admin",
    "authorities": 
    [
      "ROLE_ADMIN"
    ]
  }
}

 

Resource Owner Credentials Grant

For web applications with which the user credentials can be shared. Example exchange:

http://localhost:8080/transmart/oauth/token?grant_type=password&client_id=glowingbear-js&username=admin&password=admin&scope=read%20write
{  
   "access_token":"dab387fc-2bdb-405b-8492-b2beeed3a065",
   "token_type":"bearer",
   "expires_in":42329,
   "scope":"write read"
}

Note: If your client has a client secret set you need to add a &client_secret=<client secret> parameter. The client must be configured to allow usage of the password grant type in Config.groovy.

List of terms

  • Resource owner: This is defined by the OAuth2.0 specification as: "An entity capable of granting access to a protected resource. When the resource owner is a person, it is referred to as an end-user”. This usually means the resource owner is an end-user who has been granted certain access privileges to studies in the tranSMART databse and wishes to grant those same privileges to the a client.
  • scope: The scope parameter in the OAuth protocol specifies a list of permissions that the client requests. Currently Transmart does not implement that and access is an all or nothing proposition. The parameter can be left off in most situations.
  • No labels