3.4 Authorization

Access to the resources hosted in the resource server can be protected by verifying the access token available in the API request. A client application offering a service to the user (Resource Owner), that needs to act on the resource owned by the user, has to get an access token from Identity Server. The resource server verifies that this token is issued by a trusted issuer and contains necessary scopes to access the resource.

The client can get the access token from Identity Server by invoking one of the supported OAuth 2.0 authorization flows by using the client's credentials.

The client usually invokes one of the following flows or the grants explained in Other Grants:

  • Authorization Code Grant

  • Implicit Grant

  • Refresh Token

    • Resource Owner Credentials Grant

    • Client Credentials Grant

    • SAML2 Bearer Profile for Authorization Grant

3.4.1 Authorization Code Grant

This is same as getting the identity token explained in Section 3.3.1, Authorization Code Grant Flow.

3.4.2 Implicit Grant

This is same as getting the identity token explained in Section 3.3.2, Implicit Grant. To get an access token, the request must contain response_type value as token.

3.4.3 Refresh Token

The Authorization Code Grant requires that the user is available on the browser and has an active session with Identity Server. Therefore, it is called as the online flow.

Sometime, the client might need access to resources even if the user is not available online. For example, when a client wants to perform batch processing on resources owned by a user, it might need to have a longer lifetime of access token. Access tokens usually have shorter lifetime. The refresh tokens have longer lifetime. Using the refresh tokens, clients can ask for fresh access tokens. As the access tokens are issued offline when the user is not active, this flow is called as an offline flow.

A client can use this option if the access token is expired or going to expire.

Refresh Token Request URI Parameters

The refresh token request should be sent to the Token Endpoint. The request should have following parameters in query string of the request:

Parameter

Required/Optional

Description

grant_type

Required

Must be refresh_token.

client_id

Required

The client application ID that is obtained at the time of the client application registration process.

client_secret

Optional

The client secret that is obtained at the time of the client application registration process.

The client secret is optional for a native application, but mandatory for a web application.

refresh_token

Required

refresh_token that is obtained during authorization grant, resource owner credentials.

scope

Optional

The list of the scope names separated by space.

device_id

Optional

Specify the device ID that token to be associated with device.

resourceServer

Optional

The name of the registered resource server. If this parameter is available, the authorization server uses the respective configured way to encrypt the access token.

Refresh Token Response Values

A successful request to token endpoint with refresh token results in a response containing a JSON object with the following values:

Parameter

Required/Optional

Description

access_token

Required

Access token

refresh_token

Optional

Re-issue a refresh token

token_type

Optional

Token type that is supported by the authorization server

expires_in

Required

The validity time of an access token

token_scope

Optional

The scopes granted to a client

Sample Request

A sample request and response, with line breaks for better readability.

HTTP/1.1 POST /nidp/oauth/nam/token
User-Agent: Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like
Gecko) Chrome/41.0.2228.0 Safari/537.36
Host: www.idp.com:8443
'grant_type=refresh_token
&client_id=4e4ae330-1215-4fc8-9aa7-79df8325451c
&client_secret=Rxl5pvgL80DBzbIcLPVnH17FehZA8LLT-
7oZ9POFrEguEyB2JMzB6kBj3JH4BxpZTrnFSjmFgrCClQuCKt3MUg
&refresh_token=/wEBAAcHACAup9Kv@JZbLuBBaWeaYfkP/NT'
A Successful Response
HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, no-transform
Content-Length: 0
Date: Tue, 03 Mar 2015 18:12:55 GMT
{ "access_token":"/wEBAAYGACBgyZapAgMYk7oJYXFO9/LIblf9FAnqp@Y1/Y/voByU9Z2awkCbfp
LZTzpUqFspZ4xrJc/TcNAl3hktfRDJgOUEHUkdyO/FoWxmTn3NrHL0K8kNPQo7nm3kyUSyjpxxvjVw SOPtVmNl94AXOIxqObYpLoRgpqqeO8TUltvQlk9zMNkAmHscPTYFwMrzHE@B98kIrZ1b266eSbuAmL r4y1guAx0yYs1XhboFd97I6mabGXDqeAjjpx/DTZBTCptA/LlIJgN10jMwik7x9nZZ3wjv16/4hw8G UHaS09uHXqqtF3S0pJ6/aM/hsWAgkcZeOhliPGXV8T7tjMmc8V1t4mIzuOagzN0LbaclD1OBkndIKC OcqJiiMMRDZNEHBjwoOXc~",
"token_type":"bearer",
"expires_in":3599, "scope":"profile email"
}