https://projects.spring.io/spring-security-oauth/docs/oauth2.html
Now we will describe the authorization code flow:
POST /oauth/oauth20/token
Returns an OAuth 2.0 token using HTTP POST.
To request an access token using this grant type, the client must have already obtained the Authorization Code from the authorization server. An Authorization Code is a short-lived token issued to the client application by the authorization server upon successful authentication/authorization of an end-user (resource owner). The client application then uses the authorization code to request an access token from the authorization server.
For detailed examples about the types of access tokens supported, with example for each type of access token, refer to OAuth: Client Authentication with the Platform’s OAuth Provider.
Note: there is a corresponding operation that performs the same action using HTTP GET: GET /oauth/oauth20/token. For information on why you might choose one or the other, see OAuth Operations: GET or POST?
Authorization Roles/Permissions: Anyone can run this operation.
This topic includes the following sections:
HTTP Method
POST
URL
https://{oauth-provider-url}/oauth/oauth20/token
Sample Request
The examples below shows token requests in an LDAP scenario, with several different grant types.
Request URL
https://{oauth-provider-url}/oauth/oauth20/token
Sample request headers
Note: In the sample request headers below, the Authorization header consist of the clientâs Basic authentication header, as explained in HTTP Basic Authentication. This is one way of sending the authorization credentials. As an alternative, you can send this information in the POST body or, if you are using the GET operation, in the request parameters. For more information, see OAuth: Client Authentication with the Platform’s OAuth Provider.
POST /oauth/oauth20/token HTTP/1.1 Host: http://{oauth-provider-hostname} Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Content-Type: application/x-www-form-urlencoded Accept: application/json
Sample request body: authorization_code grant type
In the sample request body shown below, the client ID and client secret are included. When the Authorization header is included with the request message, as shown above, you don’t need to send the client ID and client secret in the parameters. Send them either in the header or in the parameters. The below is an example of sending these values in the POST request body if the Authorization header was not sent. Line breaks have been added for display purposes.
client_id=acmepaymentscorp-3rCEQzwEHMT9PPvuXcClpe3v &client_secret=e5868ebb4445fc2ad9f949956c1cb9ddefa0d421 &code=T8Y2h7zvp-tviqe2gQQ_VGQKMizn8jRgxZ74hA &redirect_uri=http%3A%2F%2Facmepaymentscorp.com%3A9900%2Fui%2Fapps%2Facmepaymentscorp%2F_VWQJeFH76RyfD6M6FRO5Svg%2Fresources%2Fconsole%2Fglobal%2Foauthclientredirect.html%3Fdynamic%3Dtrue &grant_type=authorization_code &scope=Scope1
Sample request body: client_credentials grant type (2-legged)
client_id=acmepaymentscorp-3rCEQzwEHMT9PPvuXcClpe3v &client_secret=e5868ebb4445fc2ad9f949956c1cb9ddefa0d421 &grant_type=client_credentials &scope=Scope1
Sample request body: Resource Owner Credentials grant type
client_id=atmosphere-3rCEQzwEHMT9PPvuXcClpe3v &client_secret=e5868ebb4445fc2ad9f949956c1cb9ddefa0d421 &grant_type=password &scope=Scope1 &username=eng100 &password=password
Request Headers
For general information on request header values, refer to HTTP Request Headers.
HEADER | DESCRIPTION |
---|---|
Accept | application/json |
Content-Type | application/x-www-form-urlencoded |
Authorization | Optional. The Authorization request header authenticates the client with the server. |
Request Parameters
Note: the parameters below are all standard parameters defined in the OAuth 2.0, OpenID Connect, or JSON Web Token (JWT) specifications.
PARAMETER | PARM TYPE | DATA TYPE | REQUIRED | DESCRIPTION |
---|---|---|---|---|
grant_type | Form | String | Required | The OAuth grant type.
If the request is a request for a refresh token, the value must be set to refresh_token. |
client_id | Form | String | Optional | Unique identifier of the client application.
Must be sent; but can be sent as Authorization header. |
client_secret | Form | String | Optional | The client secret value; this value identifies the client with the provider.
Can be sent as Authorization header. Also, not needed for public client, even if Authorization header is not sent. |
refresh_token | Form | String | Optional | Refresh Token grant type only: The refresh token. |
scope | Form | String | Optional | OAuth 2.0: standard scope parameter. One or more scopes configured in the OAuth provider. Space separator for multiple scopes.
The scope of the access request. |
code | Form | String | Optional | Authorization Code grant type only: The authorization code that was previously received by the client application. |
redirect_uri | Form | String | Optional | Authorization Code grant type only: The redirect URI of the client application, where it received the authorization code. |
username | Form | String | Optional | Resource Owner Password Credentials only: The resource owner’s username. |
password | Form | String | Optional | Resource Owner Password Credentials only: The resource owner’s password. |
client_assertion_type | Form | String | Optional | JWT Bearer Assertion grant type only:
The format of the assertion as identified by the Authorization Server. The value must be set to urn:ietf:params:oauth:client-assertion-type:jwt-bearer. |
client_assertion | Form | String | Optional | JWT Bearer Assertion grant type only: The assertion being used to authenticate the client. Only JWT compact serialization is allowed. |
assertion | Form | String | Optional | JWT Bearer Assertion grant type only: The JWT Bearer Assertion. |
Response
If successful, this operation returns HTTP status code 200, with the access token.
Sample Response
The sample response below shows successful completion of this operation.
Sample response headers: application/json
HTTP/1.1 200 OK Content-Type: application/json Sample response body: application/json
Sample response body #1
{ "access_token": "SlAV32hkKG", "token_type": "Bearer", "refresh_token": "8xLOxBtZp8", "expires_in": 3600, "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzc yI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5 NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZ fV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5Nz AKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6q Jp6IcmD3HP99Obi1PRs-cwh3LO-p146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJ NqeGpe-gccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7Tpd QyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoS K5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4 XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg" }
Sample response body: authorization_code grant type
{ "access_token" : "d50d9fd00acf797ac409d5890fcc76669b727e63", "token_type" : "Bearer", "expires_in" : 1295998, "refresh_token" : "TZzj2yvtWlNP6BvG6UC5UKHXY2Ey6eEo80FSYax6Yv8" }
Sample response body: Client Credentials grant type (2-legged)
{ "access_token" : "4484e52dc4744374aced826a4543cd28948816ff", "token_type" : "Bearer", "expires_in" : 1295999 }
Sample response body: Resource Owner Credentials grant type
{ "access_token" : "49fad390491a5b547d0f782309b6a5b33f7ac087", "token_type" : "Bearer", "expires_in" : 1295999, "refresh_token" : "USrAgmSf5MJ8N_RLQODa7rZ3zNs1Sj1GkSIsTsb4n-Y" }
Sample response body: Error scenario
Note: in the example below, the state parameter is included in the error response. This would be the case in any scenario where it was included in the request.
{ error=invalid_request, error_description=Unsupported%20response_type%20value, state=af0ifjsldkj }
Response Headers
For general information on response header values, refer to HTTP Response Headers.
HEADER | DESCRIPTION |
---|---|
Content-Type | application/json |
Response Body: Success
NAME | TYPE | DESCRIPTION |
---|---|---|
AccessTokenResponse | AccessTokenResponse | Contains information about the response to a request for an OAuth Access Token. Used by the token endpoint. |
Response Body: Error Scenario
NAME | TYPE | DESCRIPTION |
---|---|---|
AccessTokenErrorResponse | AccessTokenErrorResponse | Contains information about an error response returned by the OAuth Token Endpoint in response to a request for an OAuth 2.0 access token. |
Error Codes/Messages
If the call is unsuccessful an error code/message is returned. One or more examples of possible errors for this operation are shown below.
ITEM | VALUE |
---|---|
500 | An error occurred processing the call. |
More information about Enterprise API Platform API error messages.