(Quick Reference)

3 Example Flows - Reference Documentation

Authors:

Version: 2.0-SNAPSHOT

3.1Authorization Code Grant

3.2Implicit Grant

3.3Resource Owner Password Credentials Grant

3.4Client Credentials Grant

3.5Refresh Token Grant

3 Example Flows

The following examples assume you have followed the steps outlined in the Getting Started section for an application named oauth2-test and your grails-app/conf/BootStrap.groovy contains the following:

def init = { servletContext ->    Role roleUser = new Role(authority: 'ROLE_USER').save(flush: true)
    User user = new User(
         username: 'my-user',
         password: 'my-password',
         enabled: true,
         accountExpired: false,
         accountLocked: false,
         passwordExpired: false
    ).save(flush: true)
    UserRole.create(user, roleUser, true)
    new Client(
        clientId: 'my-client',
        authorizedGrantTypes: ['authorization_code', 'refresh_token', 'implicit', 'password', 'client_credentials'],
        authorities: ['ROLE_CLIENT'],
        scopes: ['read', 'write'],
        redirectUris: ['http://myredirect.com']
    ).save(flush: true)
}

After retrieving an access_token via one of the flows, you must include this in the Authorization header when accessing protected resources.

For example, if you receive 7b9a989e-3702-4621-a631-fbd1a996fc94 as the access_token, you will include this in the Authorization header as Bearer 7b9a989e-3702-4621-a631-fbd1a996fc94 when requesting a protected resource.

The examples below are given using CURL tool to make the requests. The plugin is compliant with RFC 6749 when configured properly. Therefore token requests should be made using an HTTP POST and authorization requests should be initiated by the User-Agent with an HTTP GET.

3.1 Authorization Code Grant

The authorization code grant flow is initiated by directing your browser to the authorization endpoint:

http://localhost:8080/oauth2-test/oauth/authorize?response_type=code&client_id=my-client&scope=read

You will be redirected to the login page. After signing in, you will be prompted to confirm the request. Doing so will redirect your browser to the following URL:

http://myredirect.com/?code=139R59

The authorization code included in the query can be exchanged for an access token via the token endpoint:

curl -X POST \
     -d "client_id=my-client" \
     -d "grant_type=authorization_code" \
     -d "code=139R59" http://localhost:8080/oauth2-test/oauth/token

Using HTTP Basic for client authentication:

curl -X POST -u my-client: \
     -d "grant_type=authorization_code" \
     -d "code=139R59" http://localhost:8080/oauth2-test/oauth/token

You'll receive the access_token in the response:

{
    "access_token": "a1ce2915-8d79-4961-8abb-2c6f0fdb4aba",
    "token_type": "bearer",
    "refresh_token": "6540222d-0fb9-4b01-8d45-7be2bdfb68f9",
    "expires_in": 43199,
    "scope": "read"
}

3.2 Implicit Grant

The implicit grant is similar to the authorization code grant and can be initiated by directing your browser to the authorization endpoint:

http://localhost:8080/oauth2-test/oauth/authorize?response_type=token&client_id=my-client&scope=read

Upon confirmation, your browser will be redirected to the following URL:

http://myredirect.com/#access_token=4e22ad4f-08ae-49dc-befb-2c9821af04d1&token_type=bearer&expires_in=43199

The access_token can be extracted from the URL fragment.

3.3 Resource Owner Password Credentials Grant

The resource owner password grant is performed by requesting an access token from the token endpoint:

curl -X POST \
     -d "client_id=my-client" \
     -d "grant_type=password" \
     -d "username=my-user" \
     -d "password=my-password" \
     -d "scope=read" http://localhost:8080/oauth2-test/oauth/token

Using HTTP Basic for client authentication:

curl -X POST -u my-client: \
     -d "grant_type=password" \
     -d "username=my-user" \
     -d "password=my-password" \
     -d "scope=read" http://localhost:8080/oauth2-test/oauth/token

The access_token is included in the response:

{
    "access_token": "1d49fc35-2af6-477e-8fd4-ab0353a4a76f",
    "token_type": "bearer",
    "refresh_token": "4996ba33-be3f-4555-b3e3-0b094a4e60c0",
    "expires_in": 43199,
    "scope": "read"
}

3.4 Client Credentials Grant

The client credentials grant is performed by authenticating the client via the token endpoint:

curl -X POST \
     -d "client_id=my-client" \
     -d "grant_type=client_credentials" \
     -d "scope=read" http://localhost:8080/oauth2-test/oauth/token

Using HTTP Basic for client authentication:

curl -X POST -u my-client: \
     -d "grant_type=client_credentials" \
     -d "scope=read" http://localhost:8080/oauth2-test/oauth/token

The access_token can be extracted from the response:

{
    "access_token": "7b9a989e-3702-4621-a631-fbd1a996fc94",
    "token_type": "bearer",
    "expires_in": 43199,
    "scope": "read"
}

3.5 Refresh Token Grant

The refresh token grant is performed by exchanging a refresh token received during a previous authorization request for an access token from the token endpoint:

curl -X POST \
     -d "client_id=my-client" \
     -d "grant_type=refresh_token" \
     -d "refresh_token=269afd46-0b41-45c2-a920-7d5af8a38d56" \
     -d "scope=read" http://localhost:8080/oauth2-test/oauth/token

Using HTTP Basic for client authentication:

curl -X POST -u my-client: \
     -d "grant_type=refresh_token" \
     -d "refresh_token=269afd46-0b41-45c2-a920-7d5af8a38d56" \
     -d "scope=read" http://localhost:8080/oauth2-test/oauth/token

The above assumes that 269afd46-0b41-45c2-a920-7d5af8a38d56 is the value of the refresh token the client had obtained prior to this request.

The access_token is included in the response:

{
    "access_token": "a3da52c7-4bd2-4d42-a58d-efa64b4de453",
    "token_type": "bearer",
    "refresh_token": "6396c283-47ff-41d2-b887-39bde6af5f1e",
    "expires_in": 43199,
    "scope": "read"
}

<< 2Getting Started

4Required Domain Classes >>

3 Example Flows - Reference Documentation

Table of Contents

3 Example Flows

3.1 Authorization Code Grant

3.2 Implicit Grant

3.3 Resource Owner Password Credentials Grant

3.4 Client Credentials Grant

3.5 Refresh Token Grant

Scripts