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
This is same as getting the identity token explained in Authorization Code Grant Flow.
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.
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.
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. |
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 |
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'
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"
}