The authentication process

The authentication process seen from a user's viewpoint

OAUTH 2.0 provides a method for clients to access a protected resource/eZ Publish content on behalf of an eZ Publish user. Before an end user can access a protected resource/eZ Publish content, he/she must first obtain authorization from the eZ Publish OAUTH 2.0 module, then exchange the access grant for an access token (representing the grant's scope, duration, and other attributes) and a refresh token that is used when the access token expires. The client accesses the protected resource the first time by presenting the access token to the resource server.

The use cases below have a starting-point with a user who is:

• Use case 1: Starting up to get authorization to the client application you have developed
• Use case 2: Authorized with an access token and needs to exchange it with a refresh token
• Use case 3: Authorized with both an access token and a refresh token and is good to go!

Getting authorization to your client application

The flow illustrated in the figure below includes what goes on when a user (a registered eZ Publish user) wishes to access your newly developed REST API application:

• The end user requests access to your client application.
• The client application requests user authorization via the eZ Publish OAUTH 2.0 module that acts as the authentication filter.
• A consistency check is carried out towards the eZ Publish user accounts.
• Then the eZ Publish back-end displays an authentication form to the user.
• The user logs in and authorizes the application.
• An HTTP 302 message is sent to the client application with a "code" and "expires in" as GET parameters
• The client application requests an access token via an HTTP POST to the eZ Publish back-end
• The eZ Publish back-end now returns a temporary access token (1 hour), a refresh token and an expiry limit in JSON format.
• The client application sends a REST request with an OAUTH header to the eZ Publish OAUTH 2.0 module, which in turn sends a request to the eZ Publish server to check that the access token is valid
• The eZ Publish back-end returns the requested REST service data to the client application which in turn gives the temporary access token to the user.

Refreshing the expired access token with a refresh token

The access token is for accessing the back-end, and the refresh token is for refreshing the access token when it is expired. You request a new access token with your refresh token. Then eZ Publish OAuth module will return a new access token, with a new refresh token. Follow the flow in the diagram below:

• The end user requests the client application to refresh his temporary access token with a new access token and a refresh token.
• The client application sends a REST request with the access token in the header to eZ Publish OAUTH 2.0 module, which in turn returns an "expired token" with a www-Authenticate header in an HTTP 401 format to the client application.
• The client application requests a refresh token via an HTTP POST to the eZ Publish back-end
• The eZ Publish back-end now returns a refresh token and an expiry limit in JSON format.
• The client application sends a REST request with an OAUTH header to the ez Publish OAUTH 2.0 module, which in turn sends a request to the eZ Publish server to check that the access token is valid
• The eZ Publish back-end returns the requested REST service data to the client application which in turn gives the refresh token to the user.

Authorization is ok and the user is ready to go

Follow the flow in the diagram below:

• The end user wishes to access the new REST API application
• The client application sends a REST request with the refresh token in the header to eZ Publish OAUTH 2.0 module, which in turn sends a request to the eZ Publish server to check that the access token is valid.
• The eZ Publish back-end returns the requested REST service data to the client application which in turn gives access to the client application to the user.

Note that all use cases above are either fully or partially automated, so in each case the whole process only takes a second or two.