OAuth Request Scenarios

The following scenarios examine OAuth 2.0 client requests for an access_token.
otk41
The following scenarios examine OAuth 2.0 client requests for an access_token.
Response Type
The client request includes a response_type. 
 
response_type
 
 
Notes
 
token
Only use the 
token
 response_type if an exposed access_token is not an issue. Clients using this response_type are considered to be public clients and do not receive a refresh_token. This type of client may be implemented in JavaScript.
token id_token
Only use the 
token id_token
 response type in conjunction with scope=openid. This response_type is used with OpenID Connect.
code
The 
code
 response_type is the most secure with regards to visibility of issued tokens. The flow involves multiple steps that are required between sending the initial request to receiving an access_token.
If the user grants the client access, the client receives an authorization code attached to the redirect_uri. The client can then exchange the authorization_code for an access_token using grant_type=authorization_code.
Details:
response_type=token
The 'token' response_type can be used when the client should not have access to user credentials. It includes a redirect that involves a browser or a web view on a mobile device. Using the token response_type is not secure. It should be used only if an exposed access_token is not an issue. Clients using this response_type are considered to be 'public' clients and do not receive a refresh_token. This type of client may be implemented in JavaScript.
 
 
Request
 
Notes
 
Method:
 
GET
 
Endpoint:
 
/auth/oauth/v2/authorize
 
Parameters:
 
response_type=token&client_id=a-client_id&redirect_uri=a-redirect_uri&scope=a-list-of-scope-values&state=a-state-value
 
Optional:
 
 
redirect_uri: 
If provided only requests using a registered redirect_uri of this client will be granted by the OAuth server. If the parameter is not included the OAuth server will use the registered redirect_uri. If multiple redirect_uris have been registered the request will fail. At least one redirect_uri MUST have been registered!
 
Optional:
 
 
scope: 
Only SCOPE values that have been registered for the client will be granted by the OAuth server
 
Optional:
 
 
state: 
This value is opaque to the OAuth server and will be passed back unmodified to the client
 
 
 
 
Response
 
Notes
 
Header:
 
status: 200
 
Header:
 
content-type: text/html
 
Body:
 
The user-agent will receive a login page. This page will request user credentials and the consent of the user. If the user denies the request the client will receive an error. If the user grants the client it will receive the access_token attached to the redirect_uri
 
Next:
 
The OAuth server will redirect the user-agent back to the client:
 
Header:
 
302
 
Header:
 
Location: the-redirect-uri?state=the-given-state#access_token=an-access_token&expires_in=lifetime-in-seconds&token_type=Bearer&scope=granted-scope
The receiving user-agent (browser, JavaScript client) can now extract the parameters from the redirect_uri fragment portion. The fragment value will only be available in the browser.
response_type=token id_token
The 'token id_token' response_type can be used when the client should not have access to user credentials. It includes a redirect that involves a browser or a web view on a mobile device. Using the token response_type is not secure. It should be used only if an exposed access_token is not an issue. Clients using this response_type are considered to be 'public' clients and do not receive a refresh_token. This type of client may be implemented in JavaScript.
 
 
Request
 
 
Notes
 
Method:
 
GET
 
Endpoint:
 
/auth/oauth/v2/authorize
 
Parameters:
 
response_type=token%20id_token&client_id=a-client_id&redirect_uri=a-redirect_uri&state=a-state-value&scope=a-list-of-scope-values (SCOPE MUST be included and it MUST include 'openid')
 
Optional:
 
 
redirect_uri: 
If provided only requests using a registered redirect_uri of this client will be granted by the OAuth server. If the parameter is not included the OAuth server will use the registered redirect_uri. If multiple redirect_uris have been registered the request will fail. At least one redirect_uri MUST have been registered!
 
Optional:
 
 
state: 
This value is opaque to the OAuth server and will be passed back unmodified to the client
 
 
 
 Response
 
Notes
 
Header:
 
status: 200
 
Header:
 
content-type: text/html
 
Body:
 
The user-agent will receive a login page. This page will request user credentials and the consent of the user. If the user denies the request the client will receive an error. If the user grants the client it will receive the access_token attached to the redirect_uri
 
Next:
 
The OAuth server will redirect the user-agent back to the client:
 
Header:
 
302
 
Header:
 
Location: the-redirect-uri?state=the-given-state#access_token=an-access_token&expires_in=lifetime-in-seconds&token_type=Bearer&scope=granted-scope&id_token=an-id-token-represented-as-jwt&id_token_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
The receiving user-agent (browser, JavaScript client) can now extract the parameters from the redirect_uri fragment portion. The fragment value will only be available in the browser.
response_type=code
This is the safer response_type to use because it is the most secure with regards to visibility of issued tokens. The flow involves multiple steps that are required between sending the initial request to receiving an access_token
A client is requesting an access_token using response_type=code. This response_type can be used if the client should not have access to user credentials. This response_type includes a redirect that involves a browser or a web view on a mobile device.
 
 
Request
Notes
 
Method:
 
GET
 
Endpoint:
 
/auth/oauth/v2/authorize
 
Parameters:
 
response_type=code&client_id=a-client_id&redirect_uri=a-redirect_uri&scope=a-list-of-scope-values&state=a-state-value
 
Optional:
 
 
redirect_uri: 
If provided only requests using a registered redirect_uri of this client will be granted by the OAuth server. If the parameter is not included the OAuth server will use the registered redirect_uri. If multiple redirect_uris have been registered the request will fail. If a redirect_uri is included and none was registered the OAuth server will use the one included in the request
 
Optional:
 
 
scope: 
Only SCOPE values that have been registered for the client will be granted by the OAuth server
 
Optional:
 
 
state: 
This value is opaque to the OAuth server and will be passed back unmodified to the client
 
 
Response
Notes
 
Header:
 
status: 200
 
Header:
 
content-type: text/html
 
Body:
 
The user-agent will receive a login page. This page will request user credentials and the consent of the user. If the user denies the request the client will receive an error. If the user grants the client it will receive an authorization code attached to the redirect_uri
 
Next:
 
The OAuth server will redirect the user-agent back to the client:
 
Header:
 
302
 
Header:
 
Location: the-redirect-uri?code=an-authorization-code&state=the-given-state
The receiving client can now extract the code (authorization_code) from the redirect_uri and exchange it for an access_token (using grant_type=authorization_code).
 
Grant Types 
The following scenarios describe the different grant types used to request an access_token.
grant_type
Notes
password
Used if the client was built by the enterprise that also implements the OAuth token server. 
authorization_code
Exchange the authorization_code for an access_token. A client has received the authorization_code attached to a redirect URI. The client now exchanges the authorization_code for an access_token by using grant_type 'authorization_code'. 
If the client included 'openid' as SCOPE in his request, additional keys are included in the response:
..."id_token":"eyJ0eXAiO1v8 ... JZu_LsN851VtfC5pcIqJc", "id_token_type":"urn:ietf:params:oauth:grant-type:jwt-bearer" ...
The id_token (JWT) can be used with grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer.
urn:ietf:params:oauth:grant-type:jwt-bearer
Used if the client has an id_token (represented as JWT) of an authenticated user. Only id_tokens issued by the OAuth server are accepted.
 
urn:ietf:params:oauth:grant-type:saml2-bearer
This grant_type can be used if the client is in possession of a SAML 2.0 token of an authenticated user. This scenario is useful in cases of federation where the SAML 2.0 token was signed by a trusted party.
refresh_token
This grant_type can be used if the client is in possession of a refresh_token. The request will only be successful if the refresh_token has not expired. The parameter 'SCOPE' can only include the same or a subset of values that were originally requested.
By default a refresh_token can be used only once.
Details:
grant_type=password 
This grant_type can be used if the client was built by the enterprise that also implements the OAuth token server.
Request
Notes
 
Method:
 
POST
 
Header:
 
content-type: application/x-www-form-urlencoded
 
Header:
 
authorization: Basic base64(client_id:client_secret) (This header can only be used if 'client_id' and 'client_secret' are 
NOT
 found within the message body and vice versa!)
 
Endpoint:
 
/auth/oauth/v2/token
 
Parameters:
 
grant_type=password&username=a-username&password=a-users-password&client_id=a-client_id&client_secret=a-client_secret&scope=a-list-of-scope-values
 
Optional:
 
 
scope: 
Only SCOPE values that have been registered for the client will be granted by the OAuth server
 
 
Response
Notes
 
Header:
 
status: 200
 
Header:
 
content-type: application/json
 
Body:
 
Example: { "access_token":"115b8c ... 11a5", "token_type":"Bearer", "expires_in":3600, "refresh_token":"74b29d19-8b ... 7bb6bd1", "scope":"openid email" }
grant_type=client_credentials 
This grant_type can be used if the client is acting on its own behalf. No user consent is required.
Request
Notes
 
Method:
 
POST
 
Header:
 
content-type: application/x-www-form-urlencoded
 
Header:
 
authorization: Basic base64(client_id:client_secret) (This header can only be used if 'client_id' and 'client_secret' are 
NOT
 found within the message body and vice versa!)
 
Endpoint:
 
/auth/oauth/v2/token
 
Parameters:
 
Parameters: grant_type=client_credentials&client_id=a-client_id&client_secret=a-client_secret&scope=a-list-of-scope-values
 
Optional:
 
 
scope: 
Only SCOPE values that have been registered for the client will be granted by the OAuth server
 
 
Response
 
Header:
 
status: 200
 
Header:
 
content-type: application/json
 
Body:
 
{ "access_token":"115b8c ... 11a5", "token_type":"Bearer", "expires_in":3600, "scope":"openid email" }
grant_type=authorization code
Exchange the authorization_code for an access_token. A client has received the authorization_code attached to a redirect URI. The client now exchanges the authorization_code for an access_token by using grant_type 'authorization_code'. 
Request
Notes
 
Method:
 
POST
 
Header:
 
content-type: application/x-www-form-urlencoded
 
Header:
 
authorization: Basic base64(client_id:client_secret) (This header can only be used if 'client_id' and 'client_secret' are 
NOT
 found within the message body and vice versa!)
 
Endpoint:
 
/auth/oauth/v2/token
 
Parameters:
 
grant_type=authorization_code&code=the-received-authorization-code&client_id=a-client_id&client_secret=a-client_secret&redirect_uri
 
Optional:
 
 
redirect_uri: 
The value has to be included if it has been used in the initial request. It also has to match the original value
Response
 
Header:
 
status: 200
 
Header:
 
content-type: application/json
 
Body:
 
{ "access_token":"115b8c ... 11a5", "token_type":"Bearer", "expires_in":3600, "refresh_token":"74b29d19-8b ... 7bb6bd1", "scope":"openid email" }
If the client included 'openid' as SCOPE in his request, additional keys are included in the response:
..."id_token":"eyJ0eXAiO1v8 ... JZu_LsN851VtfC5pcIqJc", "id_token_type":"urn:ietf:params:oauth:grant-type:jwt-bearer" ...
The id_token (JWT) can be used with grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer.
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
This grant_type can be used if the client is in possession of an id_token (represented as JWT) of an authenticated user. Only id_token (JWT) that were issued by the OAuth server are accepted.
Request
Notes
 
Method:
 
POST
 
Header:
 
content-type: application/x-www-form-urlencoded
 
Header:
 
authorization: Basic base64(client_id:client_secret) (This header can only be used if 'client_id' and 'client_secret' are 
NOT
 found within the message body and vice versa!)
 
Endpoint:
 
/auth/oauth/v2/token
 
Parameters:
 
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=a-jwt&client_id=a-client_id&client_secret=a-client_secret&scope=a-list-of-scope-values
 
Optional:
 
 
scope: 
Only SCOPE values that have been registered for the client will be granted by the OAuth server
 
 
Response
Notes
 
Header:
 
status: 200
 
Header:
 
content-type: application/json
 
Body:
 
{ "access_token":"115b8c ... 11a5", "token_type":"Bearer", "expires_in":3600, "refresh_token":"74b29d19-8b ... 7bb6bd1", "scope":"openid email" }
grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer
This grant_type can be used if the client is in possession of a SAML 2.0 token of an authenticated user. This scenario is useful in cases of federation where the SAML 2.0 token was signed by a trusted party.
Request
 
Method:
 
POST
 
Header:
 
content-type: application/x-www-form-urlencoded
 
Header:
 
authorization: Basic base64(client_id:client_secret) (This header can only be used if 'client_id' and 'client_secret' are 
NOT
 found within the message body and vice versa!)
 
Endpoint:
 
/auth/oauth/v2/token
 
Parameters:
 
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer&assertion=a-base64-encoded-saml-token&client_id=a-client_id&client_secret=a-client_secret&scope=a-list-of-scope-values
 
Optional:
 
 
scope: 
Only SCOPE values that have been registered for the client will be granted by the OAuth server
 
 
Response
 
Header:
 
status: 200
 
Header:
 
content-type: application/json
 
Body:
 
{ "access_token":"115b8c ... 11a5", "token_type":"Bearer", "expires_in":3600, "scope":"openid email" }
grant_type=refresh_token
This grant_type can be used if the client is in possession of a refresh_token. The request will only be successful if the refresh_token has not expired. The parameter 'SCOPE' can only include the same or a subset of values that were originally requested. The refresh_token can only be use once.
Request
 
Method:
 
POST
 
Header:
 
content-type: application/x-www-form-urlencoded
 
Header:
 
authorization: Basic base64(client_id:client_secret) (This header can only be used if 'client_id' and 'client_secret' are 
NOT
 found within the message body and vice versa!)
 
Endpoint:
 
/auth/oauth/v2/token
 
Parameters:
 
Parameters: grant_type=refresh_token&refresh_token=a-refresh-token&client_id=a-client_id&client_secret=a-client_secret&scope=a-list-of-scope-values
 
Optional:
 
 
scope: 
Only SCOPE values that have been registered for the client will be granted by the OAuth server
 
 
Response
Notes
 
Header:
 
status: 200
 
Header:
 
content-type: application/json
 
Body:
 
{ "access_token":"115b8c ... 11a5", "token_type":"Bearer", "expires_in":3600, "refresh_token":"74b29d19-8b ... 7bb6bd1", "scope":"openid email" }