com.authlete.common.dto

Class TokenResponse

java.lang.Object

com.authlete.common.dto.ApiResponse

com.authlete.common.dto.TokenResponse

All Implemented Interfaces:

Serializable

public class TokenResponse
extends ApiResponse

Response from Authlete's /auth/token API.

Authlete's /auth/token API returns JSON which can be mapped to this class. The service implementation should retrieve the value of "action" from the response and take the following steps according to the value.

INVALID_CLIENT

When the value of "action" is "INVALID_CLIENT", it means that authentication of the client failed. In this case, the HTTP status of the response to the client application is either "400 Bad Request" or "401 Unauthorized". This requirement comes from RFC 6749, 5.2. Error Response. The description about "invalid_client" shown below is an excerpt from RFC 6749.

invalid_client

Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate via the "Authorization" request header field, the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the "WWW-Authenticate" response header field matching the authentication scheme used by the client.

In either case, the JSON string returned by getResponseContent() can be used as the entity body of the response to the client application.

The following illustrate the response which the service implementation should generate and return to the client application.

 HTTP/1.1 400 Bad Request
 Content-Type: application/json
 Cache-Control: no-store
 Pragma: no-cache

 (The value returned from getResponseContent())

 HTTP/1.1 401 Unauthorized
 WWW-Authenticate: (challenge)
 Content-Type: application/json
 Cache-Control: no-store
 Pragma: no-cache

 (The value returned from getResponseContent())

INTERNAL_SERVER_ERROR

When the value of "action" is "INTERNAL_SERVER_ERROR", it means that the request from the service implementation (AuthorizationIssueRequest) was wrong or that an error occurred in Authlete.

In either case, from the viewpoint of the client application, it is an error on the server side. Therefore, the service implementation should generate a response to the client application with the HTTP status of "500 Internal Server Error".

getResponseContent() returns a JSON string which describes the error, so it can be used as the entity body of the response.

The following illustrates the response which the service implementation should generate and return to the client application.

 HTTP/1.1 500 Internal Server Error
 Content-Type: application/json
 Cache-Control: no-store
 Pragma: no-cache

 (The value returned from getResponseContent())

BAD_REQUEST

When the value of "action" is "BAD_REQUEST", it means that the request from the client application is invalid.

The HTTP status of the response returned to the client application must be "400 Bad Request" and the content type must be "application/json".

getResponseContent() returns a JSON string which describes the error, so it can be used as the entity body of the response.

The following illustrates the response which the service implementation should generate and return to the client application.

 HTTP/1.1 400 Bad Request
 Content-Type: application/json
 Cache-Control: no-store
 Pragma: no-cache

 (The value returned from getResponseContent())

PASSWORD

When the value of "action" is "PASSWORD", it means that the request from the client application is valid and grant_type is "password". That is, the flow is "Resource Owner Password Credentials".

In this case, getUsername() returns the value of "username" request parameter and getPassword() returns the value of "password" request parameter which were contained in the token request from the client application. The service implementation must validate the credentials of the resource owner (= end-user) and take either of the actions below according to the validation result.

1. When the credentials are valid, call Authlete's /auth/token/issue API to generate an access token for the client application. The API requires "ticket" request parameter and "subject" request parameter. Use the value returned from getTicket() method as the value for "ticket" parameter.

   
   

   The response from /auth/token/issue API (TokenIssueResponse) contains data (an access token and others) which should be returned to the client application. Use the data to generate a response to the client application.

   
   

2. When the credentials are invalid, call Authlete's /auth/token/fail API with reason=INVALID_RESOURCE_OWNER_CREDENTIALS to generate an error response for the client application. The API requires "ticket" request parameter. Use the value returned from getTicket() method as the value for "ticket" parameter.

   
   

   The response from /auth/token/fail API (TokenFailResponse) contains error information which should be returned to the client application. Use it to generate a response to the client application.

OK

When the value of "action" is "OK", it means that the request from the client application is valid and an access token, and optionally an ID token, is ready to be issued.

The HTTP status of the response returned to the client application must be "200 OK" and the content type must be "application/json".

getResponseContent() returns a JSON string which contains an access token (and optionally an ID token), so it can be used as the entity body of the response.

The following illustrates the response which the service implementation should generate and return to the client application.

 HTTP/1.1 200 OK
 Content-Type: application/json
 Cache-Control: no-store
 Pragma: no-cache

 (The value returned from getResponseContent())

Author:

Takahiko Kawasaki

See Also:

RFC 6749, OAuth 2.0, Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	TokenResponse.Action The next action that the service implementation should take.

Constructor Summary

Constructors

Constructor and Description
TokenResponse()

Method Summary

Modifier and Type	Method and Description
TokenResponse.Action	getAction() Get the next action that the service implementation should take.
String	getPassword() Get the value of "password" request parameter.
String	getResponseContent() Get the response content which can be used as the entity body of the response returned to the client application.
String	getTicket() Get the ticket issued from Authlete's /auth/token endpoint.
String	getUsername() Get the value of "username" request parameter.
void	setAction(TokenResponse.Action action) Set the next action that the service implementation should take.
void	setPassword(String password) Set the value of "password" request parameter.
void	setResponseContent(String responseContent) Set the response content which can be used as the entity body of the response returned to the client application.
void	setTicket(String ticket) Set the ticket used for /aut/token/issue API or /auth/token/fail API.
void	setUsername(String username) Set the value of "username" request parameter.
String	summarize() Get the summary of this instance.

Methods inherited from class com.authlete.common.dto.ApiResponse

getResultCode, getResultMessage, setResultCode, setResultMessage

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TokenResponse

public TokenResponse()

Method Detail

getAction

public TokenResponse.Action getAction()

Get the next action that the service implementation should take.

setAction

public void setAction(TokenResponse.Action action)

Set the next action that the service implementation should take.

getResponseContent

public String getResponseContent()

Get the response content which can be used as the entity body of the response returned to the client application.

setResponseContent

public void setResponseContent(String responseContent)

Set the response content which can be used as the entity body of the response returned to the client application.

getUsername

public String getUsername()

Get the value of "username" request parameter.

This method returns a non-null value only when the value of "grant_type" request parameter in the token request is "password".

getSubject() method was renamed to getUsername() on version 1.13.

Since:

1.13

See Also:

RFC 6749, 4.3.2. Access Token Request

setUsername

public void setUsername(String username)

Set the value of "username" request parameter.

setSubject(String} was renamed to setUsername(String) on version 1.13.

Since:

1.13

getPassword

public String getPassword()

Get the value of "password" request parameter.

This method returns a non-null value only when the value of "grant_type" request parameter in the token request is "password".

See Also:

RFC 6749, 4.3.2. Access Token Request

setPassword

public void setPassword(String password)

Set the value of "password" request parameter.

getTicket

public String getTicket()

Get the ticket issued from Authlete's /auth/token endpoint. The value is to be used as the value of "ticket" request parameter for /auth/token/issue API or /auth/token/fail API.

This method returns a non-null value only when "action" is PASSWORD.

setTicket

public void setTicket(String ticket)

Set the ticket used for /aut/token/issue API or /auth/token/fail API.

summarize

public String summarize()

Get the summary of this instance.