OAuth APIs and Authenticator Service

The OAuth Authenticator introduced in TIBCO Cloud™ API Management - Local Edition 5.0 includes the Basic Authenticator for an OAuth API endpoint, and a Public Key Authenticator configured and targeted for an OAuth service endpoint. This page describes the configuration of the OAuth Authenticator and also provides sample calls to OAuth APIs.

OAuth Authenticator Service Configuration

Authorization for the OAuth Authenticator Service depends on the configuration of "com.mashery.service.onprem.oauth.authenticator.oauth-service-authenticator" in mashery-proxy-config.json.

OAuth API requests can be authenticated using Basic Authentication and/or Public Key Authentication:

If the OAuth API endpoint is exposed or used directly, Basic Authentication should be configured.
If a proxy OAuth API service endpoint is used, Public Key Authentication should be configured.

The following is an example of the configuration in mashery-proxy-config.json for both Basic and Public Key Authentication:

"com.mashery.service.onprem.oauth.authenticator.oauth-service-authenticator" : {
        "publicKeyName": "public_key",
        "publicKeyValue": "3bvu8u3p8l",
        "username": "root",
        "password": "057ba03d6c44104863dc7361fe4578965d1887360f90a0895882e58a6248fc86"
},

The username/password pair is to support Basic Authentication. The password can be generated by any SHA256 Hash generator. "057ba03d6c44104863dc7361fe4578965d1887360f90a0895882e58a6248fc86" is a SHA256 for "changeme".
The encoded string "cm9vdDpjaGFuZ2VtZQ==" in the curl header -H ’Authorization: Basic cm9vdDpjaGFuZ2VtZQ==' (as shown in the curl examples below) is for "root:changeme".
The publicKeyName/publicKeyValue pair is for public key authentication when setting up an OAuth API service endpoint.
The public key is extracted from the request parameters when the request is received by the OAuth API service endpoint created in either tethered or untethered mode (refer to sample OAuth API service endpoint setup below for more details).

To use the endpoint, the publicKeyName and publicKeyValue properties must be configured in mashery-proxy-config.json and their values should match their corresponding parameter string in the endpoint.

For example, if publicKeyName/publicKeyValue is set to "public_key/3bvu3p8l ", its parameter string should be "public_key=3bvu8u3p8l".
Basic Authenticator is disabled if the username property of service "com.mashery.service.onprem.oauth.authenticator.oauth-service-authenticator" is not present in mashery-proxy-config.json.

The request must pass public key authentication when Basic Authentication is disabled.
Public key authentication is disabled if the publicKeyName property of service "com.mashery.service.onprem.oauth.authenticator.oauth-service-authenticator" is not present in mashery-proxy-config.json.

If public key authentication is disabled, Basic Authentication should be enabled by configuring the username and password.

Different Ways to Make OAuth API Calls

Call via Internal OAuth API Endpoint Basic Authentication

curl -v -d '{"id":1,"method":"oauth2.createAccessToken","params":
{"service_key":"m9f5kyzfjjrssz6d5sfkbuw3","client":
{"client_id":"yq7chp6ufkeea587gp6wqa6x","client_secret":"Azn4Xa"},"token_data":
{"grant_type":"implicit"},"uri":
{"redirect_uri":"https://some.com/cb"},"user_context":"testUser1455730448397"},"jsonrpc":"2.0"}' 'https://api.mashery.com:8083/v2/java/json-rpc' -u root:changeme -k

This call uses the username/password pair in mashery-proxy-config.json and is for API Management - Local Edition 4.x backward compatibility.

Call via Proxied OAuth API Endpoint with Public Key Authentication

curl -v -d '{"id":1,"method":"oauth2.createAccessToken","params":
{"service_key":"m9f5kyzfjjrssz6d5sfkbuw3","client":
{"client_id":"yq7chp6ufkeea587gp6wqa6x","client_secret":"Azn4Xa"},"token_data":
{"grant_type":"implicit"},"uri":
{"redirect_uri":"https://some.com/cb"},"user_context":"testUser1455730448397"},"jsonrpc":"2.0"}' -H 'Content-Type: application/json' 'http://api.mashery.com/oauth/authorization/?api_key=8qavf83pg2uzgndtxz2w4dg3'

This call is new in Local Edition 5.x. It uses the URL path /oauth/authorization and publicKeyName/publicKeyValue pair in mashery-proxy-config.json, along with the URL parameter string setting in the proxy endpoint.

Users do not need to specify any credentials (username/password) in the curl commands.

Sample Proxy Endpoint Setup with publicKeyName/publicKeyValue Parameter String in Tethered/Untethered

The following screenshot shows the settings on "Call Transformation" of the proxied OAuth API endpoint.

In this setup:

The service URL is set to "/oauth/authorization" and can either be sent with HTTP or HTTPS.
The parameters include the publicKeyName/publicKeyValue set in "com.mashery.service.onprem.oauth.authenticator.oauth-service-authenticator".
The protocol and IP address of the Origin Endpoint correspond to the internal OAuth API endpoint setting in mashery-proxy-config.json.

Support for HTTPS Connection

This setting is in mashery-proxy-config.json to support an HTTPS connection for OAuth.

"com.mashery.service.onprem.oauth.api-server": {
        "http.enabled": true,
        "https.enabled": true,
        "http.port": 9083,
        "https.port": 8083,
        "ssl.keystore": "/etc/mashery-server-ssl/mashery-local.jks",
        "ssl.password": "changeit",
        "ssl.keypassword": "changeit"
},

In Local Edition 5.x, only https.port is configured in the .yml file and exposed when the container is started. The http.port works only in calls within the containers.

You should always use HTTPS configuration for OAuth API calls outside the container.

OAuth APIs

Sample calls through proxy endpoint using above settings.

Create access token

curl -v -d '{"id":1,"method":"oauth2.createAccessToken","params":{"service_key":"m9f5kyzfjjrssz6d5sfkbuw3","client":{"client_id":"yq7chp6ufkeea587gp6wqa6x","client_secret":"Azn4Xa"},"token_data":{"grant_type":"implicit"},"uri":{"redirect_uri":"https://some.com/cb"},"user_context":"testUser1455730448397"},"jsonrpc":"2.0"}' -H 'Host: api.mashery.com' -H 'Content-Type: application/json' 'http://X.X.99.100:80/oauth/authorization/?api_key=8qavf83pg2uzgndtxz2w4dg3'
*   Trying X.X.99.100...
* Connected to X.X.99.100 (X.X.99.100) port 80 (#0)
> POST /oauth/auth/v2/?api_key=8qavf83pg2uzgndtxz2w4dg3 HTTP/1.1
> Host: api.mashery.com
> User-Agent: curl/7.43.0
> Accept: */*
> Content-Type: application/json
> Content-Length: 310
>
* upload completely sent off: 310 out of 310 bytes
< HTTP/1.1 200 OK
< X-Mashery-Responder: 8abfe284898c
< Content-Type: application/json;charset=UTF-8
< Cache-Control: no-store
< Content-Length: 231
< Date: Tue, 30 Oct 2018 00:38:26 GMT
<
* Connection #0 to host X.X.99.100 left intact
{"jsonrpc":"2.0","id":1,"result":{"token_type":"bearer","return_type":"json","access_token":"unrct8wsweny8h3b3kw39wab","expires_in":36000,"scope":null,"user_context":"testUser1455730448397","uri":null,"extended":null,"state":null}}

Create authorization code

curl -v -d '{ "id":1,"method":"oauth2.createAuthorizationCode","params":{"service_key":"m9f5kyzfjjrssz6d5sfkbuw3","client":{"client_id":"yq7chp6ufkeea587gp6wqa6x"},"response_type":"code","uri":{"redirect_uri":"https://some.com/cb"},"user_context": "testUser1455730448397"},"jsonrpc":"2.0"}' -H 'Host: api.mashery.com' -H 'Content-Type: application/json' 'http://X.X.99.100:80/oauth/authorization/?api_key=8qavf83pg2uzgndtxz2w4dg3'
*   Trying X.X.99.100...
* Connected to X.X.99.100 (X.X.99.100) port 80 (#0)
> POST /oauth/auth/v2/?api_key=8qavf83pg2uzgndtxz2w4dg3 HTTP/1.1
> Host: api.mashery.com
> User-Agent: curl/7.43.0
> Accept: */*
> Content-Type: application/json
> Content-Length: 277
>
* upload completely sent off: 277 out of 277 bytes
< HTTP/1.1 200 OK
< X-Mashery-Responder: 8abfe284898c
< Content-Type: application/json;charset=UTF-8
< Cache-Control: no-store
< Content-Length: 168
< Date: Tue, 30 Oct 2018 00:42:12 GMT
<
* Connection #0 to host X.X.99.100 left intact
{"jsonrpc":"2.0","id":1,"result":{"code":"p2kjsmn8mw2xb3d2ksryxk6z","uri":{"redirect_uri":"https://some.com/cb?code=p2kjsmn8mw2xb3d2ksryxk6z","state":""}},"error":null}

Create access token with authorization code

curl -v -d '{"id":1,"method":"oauth2.createAccessToken","params":{"service_key":"m9f5kyzfjjrssz6d5sfkbuw3","client":{"client_id":"yq7chp6ufkeea587gp6wqa6x","client_secret":"Azn4Xa"},"token_data":{"grant_type":"authorization_code","code":"p2kjsmn8mw2xb3d2ksryxk6z","scope":"scope1"},"uri":{"redirect_uri":"https://some.com/cb"},"user_context": "testUser1455730448397"},"jsonrpc":"2.0"}' -H 'Content-Type: application/json'  -H 'Host: api.mashery.com' 'http://X.X.99.100:80/oauth/authorization/?api_key=8qavf83pg2uzgndtxz2w4dg3'
*   Trying X.X.99.100...
* Connected to X.X.99.100 (X.X.99.100) port 80 (#0)
> POST /oauth/auth/v2/?api_key=8qavf83pg2uzgndtxz2w4dg3 HTTP/1.1
> Host: api.mashery.com
> User-Agent: curl/7.43.0
> Accept: */*
> Content-Type: application/json
> Content-Length: 372
>
* upload completely sent off: 372 out of 372 bytes
< HTTP/1.1 200 OK
< X-Mashery-Responder: 8abfe284898c
< Content-Type: application/json;charset=UTF-8
< Cache-Control: no-store
< Content-Length: 274
< Date: Tue, 30 Oct 2018 00:49:18 GMT
<
* Connection #0 to host X.X.99.100 left intact
{"jsonrpc":"2.0","id":1,"result":{"token_type":"bearer","return_type":"json","access_token":"rjzb2k26cgv7tufe2j8cs7rm","expires_in":36000,"refresh_token":"zgwyg64s2ejc6catffvg5kbx","scope":null,"user_context":"testUser1455730448397","uri":null,"extended":null,"state":null}}

Update access token

curl -v -d '{"id":1,"method":"oauth2.updateAccessToken","params":{"service_key":"m9f5kyzfjjrssz6d5sfkbuw3","client":{"client_id":"yq7chp6ufkeea587gp6wqa6x","client_secret":"Azn4Xa"}, "access_token":"rjzb2k26cgv7tufe2j8cs7rm","user_context":"testUser1455730448397", "expires_in":600},"jsonrpc":"2.0"}' -H 'Host: api.mashery.com'  -H 'Content-Type: application/json'  'http://X.X.99.100:80/oauth/authorization/?api_key=8qavf83pg2uzgndtxz2w4dg3'
*   Trying X.X.99.100...
* Connected to X.X.99.100 (X.X.99.100) port 80 (#0)
> POST /oauth/auth/v2/?api_key=8qavf83pg2uzgndtxz2w4dg3 HTTP/1.1
> Host: api.mashery.com
> User-Agent: curl/7.43.0
> Accept: */*
> Content-Type: application/json
> Content-Length: 287
>
* upload completely sent off: 287 out of 287 bytes
< HTTP/1.1 200 OK
< X-Mashery-Responder: 8abfe284898c
< Content-Type: application/json;charset=UTF-8
< Cache-Control: no-store
< Content-Length: 322
< Date: Tue, 30 Oct 2018 01:01:50 GMT
<
* Connection #0 to host X.X.99.100 left intact
{"jsonrpc":"2.0","id":1,"result":{"token_type":"bearer","access_token":"rjzb2k26cgv7tufe2j8cs7rm","expires":"2018-10-30T11:01:50Z","refresh_token_expires":1540864158505,"scope":null,"user_context":"testUser1455730448397","uri":null,"grant_type":"authorization_code","client_id":"yq7chp6ufkeea587gp6wqa6x","extended":null}

Fetch access token

curl -v -d '{"id": 1,"jsonrpc":"2.0","method": "oauth2.fetchAccessToken","params": {"service_key":"m9f5kyzfjjrssz6d5sfkbuw3","access_token": "rjzb2k26cgv7tufe2j8cs7rm"}}' -H 'Host: api.mashery.com' -H 'Content-Type: application/json' 'http://X.X.99.100:80/oauth/authorization/?api_key=8qavf83pg2uzgndtxz2w4dg3'
*   Trying X.X.99.100...
* Connected to X.X.99.100 (X.X.99.100) port 80 (#0)
> POST /oauth/auth/v2/?api_key=8qavf83pg2uzgndtxz2w4dg3 HTTP/1.1
> Host: api.mashery.com
> User-Agent: curl/7.43.0
> Accept: */*
> Content-Type: application/json
> Content-Length: 157
>
* upload completely sent off: 157 out of 157 bytes
< HTTP/1.1 200 OK
< X-Mashery-Responder: 8abfe284898c
< Content-Type: application/json;charset=UTF-8
< Cache-Control: no-store
< Content-Length: 242
< Date: Tue, 30 Oct 2018 01:05:25 GMT
<
* Connection #0 to host X.X.99.100 left intact
{"jsonrpc":"2.0","id":1,"result":{"token_type":"bearer","expires":"2018-10-30T11:01:50Z","scope":null,"user_context":"testUser1455730448397","uri":null,"grant_type":"authorization_code","client_id":"yq7chp6ufkeea587gp6wqa6x","extended":null}}

Fetch application

curl -v -d '{"id": 1,"jsonrpc":"2.0","method":"oauth2.fetchApplication","params":{"service_key":"m9f5kyzfjjrssz6d5sfkbuw3","client":{"client_id":"yq7chp6ufkeea587gp6wqa6x","client_secret":"Azn4Xa"}}}' -H 'Host: api.mashery.com' -H 'Content-Type: application/json' 'http://X.X.99.100:80/oauth/authorization/?api_key=8qavf83pg2uzgndtxz2w4dg3'
*   Trying X.X.99.100...
* Connected to X.X.99.100 (X.X.99.100) port 80 (#0)
> POST /oauth/auth/v2/?api_key=8qavf83pg2uzgndtxz2w4dg3 HTTP/1.1
> Host: api.mashery.com
> User-Agent: curl/7.43.0
> Accept: */*
> Content-Type: application/json
> Content-Length: 187
>
* upload completely sent off: 187 out of 187 bytes
< HTTP/1.1 200 OK
< X-Mashery-Responder: 8abfe284898c
< Content-Type: application/json;charset=UTF-8
< Cache-Control: no-store
< Content-Length: 82
< Date: Tue, 30 Oct 2018 01:10:58 GMT
<
* Connection #0 to host X.X.99.100 left intact
{"jsonrpc":"2.0","id":1,"result":{"id":251547,"name":"TestOAuthRegisterCallBack"}}

Fetch user application

curl -v -d  '{ "id":1, "method":"oauth2.fetchUserApplications", "params":{ "service_key":"m9f5kyzfjjrssz6d5sfkbuw3",  "user_context":"testUser1455730448397" },"jsonrpc":"2.0"}' -H 'Host: api.mashery.com' -H 'Content-Type: application/json' 'http://X.X.99.100:80/oauth/authorization/?api_key=8qavf83pg2uzgndtxz2w4dg3'
*   Trying X.X.99.100...
* Connected to X.X.99.100 (X.X.99.100) port 80 (#0)
> POST /oauth/auth/v2/?api_key=8qavf83pg2uzgndtxz2w4dg3 HTTP/1.1
> Host: api.mashery.com
> User-Agent: curl/7.43.0
> Accept: */*
> Content-Type: application/json
> Content-Length: 162
>
* upload completely sent off: 162 out of 162 bytes
< HTTP/1.1 200 OK
< X-Mashery-Responder: 8abfe284898c
< Content-Type: application/json;charset=UTF-8
< Cache-Control: no-store
< Content-Length: 195
< Date: Tue, 30 Oct 2018 01:12:32 GMT
<
* Connection #0 to host X.X.99.100 left intact
{"jsonrpc":"2.0","id":1,"result":[{"id":251547,"name":"TestOAuthRegisterCallBack","access_tokens":["rjzb2k26cgv7tufe2j8cs7rm","unrct8wsweny8h3b3kw39wab"],"client_id":"yq7chp6ufkeea587gp6wqa6x"}]}

Revoke access token

curl -v -d  '{ "id":1, "method":"oauth2.revokeAccessToken", "params":{ "service_key":"m9f5kyzfjjrssz6d5sfkbuw3", "client": { "client_id":"yq7chp6ufkeea587gp6wqa6x", "client_secret":"Azn4Xa" }, "access_token":"rjzb2k26cgv7tufe2j8cs7rm" },"jsonrpc":"2.0"}' -H 'Host: api.mashery.com' -H 'Content-Type: application/json' 'http://X.X.99.100:80/oauth/authorization/?api_key=8qavf83pg2uzgndtxz2w4dg3'
*   Trying X.X.99.100...
* Connected to X.X.99.100 (X.X.99.100) port 80 (#0)
> POST /oauth/auth/v2/?api_key=8qavf83pg2uzgndtxz2w4dg3 HTTP/1.1
> Host: api.mashery.com
> User-Agent: curl/7.43.0
> Accept: */*
> Content-Type: application/json
> Content-Length: 240
>
* upload completely sent off: 240 out of 240 bytes
< HTTP/1.1 200 OK
< X-Mashery-Responder: 8abfe284898c
< Content-Type: application/json;charset=UTF-8
< Cache-Control: no-store
< Content-Length: 38
< Date: Tue, 30 Oct 2018 01:17:10 GMT
<
* Connection #0 to host X.X.99.100 left intact
{"jsonrpc":"2.0","id":1,"result":true}

Revoke user application

curl -v -d  '{ "id":1, "method":"oauth2.revokeUserApplication", "params":{ "service_key":"m9f5kyzfjjrssz6d5sfkbuw3", "client": { "client_id":"yq7chp6ufkeea587gp6wqa6x", "client_secret":"Azn4Xa" }, "user_context":"testUser1455730448397" },"jsonrpc":"2.0"}' -H 'Host: api.mashery.com' -H 'Content-Type: application/json'  'http://X.X.99.100:80/oauth/authorization/?api_key=8qavf83pg2uzgndtxz2w4dg3'
*   Trying X.X.99.100...
* Connected to X.X.99.100 (X.X.99.100) port 80 (#0)
> POST /oauth/auth/v2/?api_key=8qavf83pg2uzgndtxz2w4dg3 HTTP/1.1
> Host: api.mashery.com
> User-Agent: curl/7.43.0
> Accept: */*
> Content-Type: application/json
> Content-Length: 241
>
* upload completely sent off: 241 out of 241 bytes
< HTTP/1.1 500 Server Error
< X-Mashery-Responder: 8abfe284898c
< Content-Type: application/json;charset=UTF-8
< Cache-Control: no-store
< Content-Length: 81
< Date: Tue, 30 Oct 2018 16:41:56 GMT
<
* Connection #0 to host X.X.99.100 left intact
{"jsonrpc":"2.0","id":1,"error":{"message":"Internal Server Error","code":-2001}}

Refresh token

curl -k -v -d '{"id":1,"method":"oauth2.createAccessToken","params":{"service_key":"m9f5kyzfjjrssz6d5sfkbuw3","client":{"client_id":"yq7chp6ufkeea587gp6wqa6x","client_secret":"Azn4Xa"},"token_data":{"grant_type":"refresh_token","refresh_token":"8f9qy6jrw3r23j2r6wqwp2jh"},"uri":{"redirect_uri":"https://some.com/cb"},"user_context":null},"jsonrpc":"2.0"}'  -H 'Host: api.mashery.com' -H 'Content-Type: application/json' 'http://X.X.99.100:80/oauth/authorization/?api_key=8qavf83pg2uzgndtxz2w4dg3'
*   Trying X.X.99.100...
* Connected to X.X.99.100 (X.X.99.100) port 80 (#0)
> POST /oauth/auth/v2/?api_key=8qavf83pg2uzgndtxz2w4dg3 HTTP/1.1
> Host: api.mashery.com
> User-Agent: curl/7.43.0
> Accept: */*
> Content-Type: application/json
> Content-Length: 339
>
* upload completely sent off: 339 out of 339 bytes
< HTTP/1.1 200 OK
< X-Mashery-Responder: 8abfe284898c
< Content-Type: application/json;charset=UTF-8
< Cache-Control: no-store
< Content-Length: 274
< Date: Tue, 30 Oct 2018 16:55:36 GMT
<
* Connection #0 to host X.X.99.100 left intact
{"jsonrpc":"2.0","id":1,"result":{"token_type":"bearer","return_type":"json","access_token":"79rkkkxd4rk2zzbrqj4z93vb","expires_in":36000,"refresh_token":"7db67za3xvdg99nc7gnctkqw","scope":null,"user_context":"testUser1455730448397","uri":null,"extended":null,"state":null}}

Sample direct calls with Basic Authentication