Integration Server 10.5 | Built-In Services Reference Guide | OAuth Folder | Summary of Elements in this Folder | pub.oauth:getToken
 
pub.oauth:getToken
WmPublic. Requests an access token from the Integration Server acting as the authorization server.
The authorization server validates the request and generates an access token and, optionally, a refresh token. The tokens, along with the client identifier, token expiration interval, and scope are stored in the authorization server's cache.
Input Parameters
grant_type
String Specifies the type of grant flow required by the client.
Specify one of the following:
*authorization_code for authorization code grant flows
*client_credentials for client credentials grant flows.
*password for resource owner password credentials grant flows.
*refresh_token for refresh token grant flows.
code
String Optional. The OAuth authorization code received from the authorization server. You must specify code when grant_type is authorization_code. The service ignores the code value for all other grant types.
client_id
String Optional. The client identifier generated by the authorization server when the client application is registered. The client_id is used to authenticate the client to the authorization server.
Public clients must provide a value for client_id when grant_type is authorization_code or password. Confidential clients do not need to provide a value for this parameter because they are required to use HTTP authentication to identify themselves.
The service ignores the client_id value if the grant_type is client_credentials.
redirect_uri
String Optional. The URI the authorization server used to redirect the client when the client request for authorization is approved.
redirect_uri is required when grant_type is authorization_code and the call to pub.oauth:authorize that initiated the authorization code grant included a redirect_uri value. The redirect_uri supplied for pub.oauth:getToken must exactly match the redirect_uri value supplied to the call to pub.oauth:authorize. If a redirect_uri value was not supplied to pub.oauth:authorize, then no redirect_uri value may be passed to the pub.oauth:getToken service. Doing so will result in an HTTP 400 status code being returned.
The service ignores redirect_uri for all other grant types.
refresh_token
String Optional. Refresh token issued to the client by the authentication server.
scope
String Optional. Specify the name of one or more scopes required by the client. Use a space to separate multiple scopes.
The scope variable is used when grant_type is refresh_token, password, or client_credentials. The service ignores the scope value when grant_type is authorization_code.
When using the pub.oauth:getToken service with the refresh_token grant type, the value for scope must match or be a subset of the value you provided for the pub.oauth:authorize and pub.oauth:getAccessToken services. That is, the scope of the refresh token can be smaller than the original request. It cannot contain any scopes that were not approved by the resource owner.
username
String Optional. The user name of the resource owner. A username is required when the grant_type is password. The service ignores username for all other grant types.
password
String Optional. The password of the resource owner. A username is required when the grant_type is password. The service ignores password for all other grant types.
Output Parameters
access_token
String The access token issued by the authorization server.
token_type
String The type of access token issued by the authorization server. The value is Bearer.
expires_in
String The number of seconds for which the access token is valid.
refresh_token
String Conditional. The refresh token issued by the authorization server. You can use this token to obtain new access tokens using the same authorization grant.
If the client is registered with a refresh limit of 0, no refresh token is issued.
scope
String Conditional. Set of scopes requested by the client.
Usage Notes
The pub.oauth:getToken service can be used for four different purposes:
*To create an access token as part of the authorization code grant. In this scenario, the client's redirection endpoint invokes the pub.oauth:getToken service. If the client is configured to receive refresh tokens, the service will also return a refresh token. To use the service in this scenario:
*grant_type must be set to authorization_code
*code is required
*client_id is required for Public clients
*redirect_uri is optional. If specified, redirect_uri must match the redirect_uriused with the call to pub.oauth:authorize.
*To create an access token as part of the resource owner password credentials grant. In this scenario, the confidential or public client invokes the pub.oauth:getToken service directly. To use the service in this scenario:
*The Authorization header in the request contains the credentials for the confidential client.
*client_id is required for Public clients.
*grant_type must be set to password
*scope is required.
*username is required.
*password is required.
*To create an access token as part of the client credentials grant. In this scenario, the confidential client invokes the pub.oauth:getToken service directly. To use the service in this scenario:
*The Authorization header in the request contains the credentials for the confidential client.
*grant_type must be set to client_credentials
*scope is required.
*If your access token has expired or is about to expire, and you have a refresh token, you can use pub.oauth:getToken to get a new access token. To use the service in this scenario:
*grant_type must be set to refresh_token
*refresh_token is required
*scope is optional
The pub.oauth:getToken service is the token endpoint for the Integration Server acting as the authorization server. The token endpoint URL is:
https://host:port/invoke/pub.oauth/getToken
The pub.oauth:getToken service must be invoked using HTTPS unless the Require HTTPS setting on the Security > OAuth > Edit OAuth Global Settings page is disabled.
Clients must invoke the pub.oauth:getToken service via an HTTP POST request unless the watt.server.oauth.requirePost server configuration parameter is set to false. When this parameter is set to false, clients can invoke this service using HTTP GET.
Confidential clients must authenticate requests by supplying their credentials in the HTTP Authorization header.
Authentication code is not persisted in the database. If Integration Server is restarted after the authorization code is issued but before the access token is requested, Integration Server will reject the request for the access token.
The token_type output parameter is always Bearer. The authorization server retains the information about the bearer tokens it issues, including the user information. When the client presents a bearer token to the resource server, the resource server checks with the authorization server to see whether the user is allowed to access the requested folders and services.
The tokens, authorization codes, and client information are stored in the authorization server's caches. By default, these caches maintain up to 1000 elements in memory and 20000 elements on disk. If the cache size is exceeded, OAuth performance can be affected on Integration Server and can lead to errors if the disk runs out of space. If you anticipate that your authorization server's cache will exceed the default size, you should increase the Maximum Elements In Memory, Maximum Elements On Disk, or Maximum Off-Heap settings for Integration Server. For information about changing these settings, see Working with Caches. If the cache is distributed, see the BigMemory Max product documentation for 4.1 at www.terracotta.org/documentation for additional considerations when sizing distributed caches.