DOC: Authorization Code Grant flow

See also OAUTH2-26

Portal Admin

... Authorization screen details here ...

Developer Implementation Details

The original implementation is using CXF OAuth2 AuthorizationCodeGrantService and AccessTokenService, please see http://cxf.apache.org/docs/jax-rs-oauth2.html

Authorization Code part

In case Authorization Code grant is enabled com.liferay.oauth2.provider.rest.internal.endpoint.authorize.AuthorizationCodeGrantServiceRegistrator
publishes org.apache.cxf.rs.security.oauth2.services.AuthorizationCodeGrantService

Authorization endpoint details:

• HTTP Method: GET
• URL: /o/oauth2/authorize
• Parameters:
  • response_type must be set to code
  • client_id ... required parameter, corresponds to OAuth2 Application clientId
  • redirect_uri ... optional, corresponds to OAuth2 Application redirect/callback URI, mandatory when multiple redirects are set
• Returns:
  • Redirects browser to the "Authorization Screen" for user to approve/decline the request
  • When user approves - returns back to the redirect_uri with code=... parameter
  • When user rejects - returns back to the redirect_uri with parameter error=access_denied

Access Token part

Access token endpoint details:

• HTTP Method: POST
• URL: /o/oauth2/token
• Parameters:
  • grant_type must be set to authorization_code
  • client_id ... required parameter, corresponds to OAuth2 Application clientId
  • redirect_uri ... must contain the same value sent in previous authorization request
  • code ... the actual code value returned from the authorization service
• Returns access token with refresh token (if enabled) and other attributes

Example

Let's suppose there is "Test OAuth2 Application" created in portal with

• Client ID: 12345
• Client secret: secret-65deadc5-8c18-08ba-1ec2-895ad923ae2
• Callback / Redirect URI: https://mysite/myapp
• Allowed Grants:
  • Authorization Code
  • Refresh Token

First part - redirect browser to authorize user:

1. Remote web application redirects browser to http://localhost:8080/o/oauth2/authorize?response_type=code&client_id=12345&redirect_uri=https://mysite/myapp
2. Browser should redirect to Authorization screen
3. User manually approves the application
4. Browser redirects back to the client application https://mysite/myapp?code=e88a3499139414ce3fd78f755557432a

Second part - exchange code for access token

1. Remote web application requests token with the authorized code using internal HTTP POST call to http://localhost:8080/o/oauth2/token with parameters

   grant_type=authorization_code&client_id=12345&client_secret=secret-65deadc5-8c18-08ba-1ec2-895ad923ae2&redirect_uri=https://mysite/myapp&code=e88a3499139414ce3fd78f755557432a

1. For example usign curl:

   curl http://localhost:8080/o/oauth2/token --data 'grant_type=authorization_code&client_id=12345&client_secret=secret-65deadc5-8c18-08ba-1ec2-895ad923ae2&redirect_uri=https://mysite/myapp&code=e88a3499139414ce3fd78f755557432a'

1. Server returns JSON with the tokens content:

   {"access_token":"4fcadd4e23b5e31c38198ffff912c7b2240f0ebf9279e301afdf08cae8f332","token_type":"Bearer","expires_in":600,"scope":"","refresh_token":"d2171c2a74e86e6e5619562a04c442728b1411f8468902b75ec431a56235f4a"}