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
Notes
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
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" }
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
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%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
Notes
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
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=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" }