Authorization Code Grant
-
Authorization Request
-
The application first needs to decide which permissions it is
requesting, then send the user to a browser to get their permission.
To initiate this authorization flow, form a URL as below and redirect
the end user's browser to the URL:
GET http://<wp_base_url>/wp-json/moserver/authorize
?response_type=code
&client_id= <client_id_goes_here>
&redirect_uri= <callback_url>
&scope= <permissions_requesting>
&state= <security_token>
response_type=code : The type of response you are
expecting. To recieve authorization code it must have value
code. This tells authorization server that application is
initiating authorization flow.
client_id : The Client ID provided by the OAuth provider.
redirect_uri : Callback Url to which user will be
redirected once they allow or disallow the access to your app.
scope : One or more space seperated strings which
indicates the permission your application requesting.
state : The application generates a random string and
includes it in the request. It should then check that the same value
is returned after the user authorizes the app.
If the user allows access to your app, thier browser will be
redirected to the supplied redirect url and request will include
code and state parameters in the query string.
For example, the user can be redirected back to URL such as
https://example-app.com/redirect
?code=<authorization-code>
&state=<security_token>
The code is Authorization code which can be exchanged for
Access token. It is generated by the authorization server and is
relatively short lived.
The state is the same security token that the application
initially set in the request.
Token Request
-
If the end user granted your app access and you receive an
Authorization Code, you can exchange the Authorization Code for an
Access Token by making a POST request to the token endpoint.
- The following is an example for POST request:
POST http://<wp_base_url>/wp-json/moserver/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&
code=<authorization_code>&
client_id=<client_id>&
client_secret=<clientSecret>&
redirect_uri=<redirect_uri>
Here, is the description for each request parameter.
-
grant_type=authorization_code : The type of grant you
are providing. This tells that the application is using
authorization code grant type.
-
code : The authorization code recieved in previous
step, included here.
-
redirect_uri: The same uri that was provided earlier in
the authorization request.
-
client_id : The client ID provided by the OAuth
provider.
-
client_secret : The client secret provided by the OAuth
provider.
At the token endpoint all the parameters in the request will be
verified ensuring that the code hasn't expired and the client id and
secret matches. If the Request is successful, it will generate an
access token and return it in the response:
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
"access_token":"hkjher92u9eu2u3uihi2eh9293",
"token_type":"bearer",
"expires_in":3600,
"scope":"profile",
"id_token":""
}
Here, is the description for each parameter received in the response.
-
access_token : access token for the Userinfo endpoint.
-
token_type : OAuth 2.0 token type value. The value must
be Bearer.
-
expires_in : The expiry time for the access token.
-
scope: One or more space seperated strings which
indicates the permission your application requesting.
-
id_token: The ID Token is a security token that
contains Claims about the authentication of an End-User by an
Authorization Server when using a Client, and potentially other
requested Claims
If the request fails the response will have a status of
404 Bad Request and will have the following contents:
"error" : "invalid_request",
"error_description" : "A more detailed description of the error intended for the developer of your app."
Resource Request
-
If the token request is successful, you will get
access_token in the response which can be used to access
the protected resources via the API.
-
Userinfo Request: The following is a non-formative
example of Userinfo Request:
GET http://<wp_base_url>/wp-json/moserver/resource
Host: server.example.com
Authorization: Bearer <access_token>
The resource server validate and verify the access token and checks if
it has not expired. If the resource request is valid the resource
server returns the claims which are represented by a JSON object that
contains a collection of name and value pairs for the Claims.
Successful Userinfo Response:
The UserInfo Claims MUST be returned as the members of a JSON
object.
Below is the example:
{
"id": "1",
"username": "abc",
"first_name": "xyz",
"last_name": "example",
"picture": "https://example.com/-kwtzesU/photo.jpg",
"email": "abc@example.com",
"locale": "en",...
}
Implicit Code Grant
-
Authorization Request
-
The application first needs to decide which permissions it is
requesting, then send the user to a browser to get their permission.
To initiate this implicit flow, form a URL as below and redirect the
end user's browser to the URL:
Get http://<wp_base_url>/wp-json/moserver/authorize
?response_type=token
&client_id= <client_id_goes_here>
&redirect_uri= <callback_url>
&scope= <permissions_requesting>
&state= <security_token>
response_type=token : The type of response you are
expecting. This tells authorization server that application is
initiating implicit flow. Note the difference from the Authorization
Code flow where this value is set to code.
client_id : The Client ID provided by the OAuth provider.
redirect_uri : Callback Url to which user will be
redirected once they allow or disallow the access to your app.
scope : One or more space seperated strings which
indicates the permission your application requesting.
state : The application generates a random string and
includes it in the request. It should then check that the same value
is returned after the user authorizes the app.
If the user allows access to your app, thier browser will be
redirected to the supplied redirect url and request will include
token and state parameters in the query string.
For example, the user can be redirected back to callback URL such as
https://callback-url?
#access_token=<access_token>
&token_type=Bearer
&expires_in=3600
&scope=<permissions_requesting>
Note the two major differences between this and the Authorization Code
flow: the access token is returned instead of the authorization code
in the response.
The client can then use the access_token to access
protected resources from Resource server.
Here, is the
description for each parameter received in the response.
-
access_token : access token for the Userinfo endpoint.
-
token_type : OAuth 2.0 token type value. The value must
be Bearer.
-
expires_in : The expiry time for the access token.
-
scope: One or more space seperated strings which
indicates the permission your application requesting.
Resource Request
-
The UserInfo Endpoint is an OAuth 2.0 Protected Resource that returns
Claims about the authenticated End-User. The returned Claims are
represented by a JSON object that contains a collection of name and
value pairs for the Claims.
-
Userinfo Request: The following is a non-formative
example of Userinfo Request:
GET http://<wp_base_url>/wp-json/moserver/resource
Host: server.example.com
Authorization: Bearer <access_token>
Successful Userinfo Response:
The UserInfo Claims MUST be returned as the members of a JSON
object.
Below is the example:
{
"id": "1",
"username": "abc",
"first_name": "xyz",
"last_name": "example",
"picture": "https://example.com/-kwtzesU/photo.jpg",
"email": "abc@example.com",
"locale": "en",...
}
Password Grant
-
The resource owner password (or "password") grant type is mostly used in
cases where the app is highly trusted. In this configuration, the user
provides their resource server credentials (username/password) to the
client app, which sends them in an access token request.
-
Token Request
-
The Password grant is one of the simplest OAuth grants and involves
only one step: the application presents a traditional username and
password login form to collect the user’s credentials and makes a POST
request to the server to exchange the password for an access token.
The POST request that the application makes looks like the example
below.
POST http://<wp_base_url>/wp-json/moserver/token
Host: authorization-server.com
Content-type: application/x-www-form-urlencoded
grant_type=password
&username=exampleuser
&password=12345678
&client_id=xxxxxxxxxx
&client_secret=xxxxxxxxxx
The POST parameters in this request are explained below.
-
grant_type=password : This tells the server we’re using
the Password grant type
-
username= The user’s username that they entered in the
application
-
password= The user’s password that they entered in the
application
-
client_id= The public identifier of the application
that the developer obtained during registration
-
client_secret= The client secret provided by the OAuth provider.
At the token endpoint all the parameters in the request will be
verified ensuring that the code hasn't expired and the client id and
secret matches. If the Request is successful, it will generate an
access token and return it in the response:
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
"access_token":"hkjher92u9eu2u3uihi2eh9293",
"token_type":"bearer",
"expires_in":3600,
"scope":"profile",
"id_token":""
}
The client can then use the access_token to access
protected resources from Resource server.
Here, is the
description for each parameter received in the response.
-
access_token : access token for the Userinfo endpoint.
-
token_type : OAuth 2.0 token type value. The value must
be Bearer.
-
expires_in : The expiry time for the access token.
-
scope: One or more space seperated strings which
indicates the permission your application requesting.
Resource Request
-
The UserInfo Endpoint is an OAuth 2.0 Protected Resource that returns
Claims about the authenticated End-User. The returned Claims are
represented by a JSON object that contains a collection of name and
value pairs for the Claims.
-
Userinfo Request: The following is a non-formative
example of Userinfo Request:
GET http://<wp_base_url>/wp-json/moserver/resource
Host: server.example.com
Authorization: Bearer <access_token>
Successful Userinfo Response:
The UserInfo Claims MUST be returned as the members of a JSON
object.
Below is the example:
{
"id": "1",
"username": "abc",
"first_name": "xyz",
"last_name": "example",
"picture": "https://example.com/-kwtzesU/photo.jpg",
"email": "abc@example.com",
"locale": "en",...
}
Client Credentials Grant
-
Client Credentials grant can be used for machine to machine
authentication. In this grant a specific user is not authorized but
rather the credentials are verified and a generic access_token is
returned..
-
Token Request
-
To receive an access token, the client POSTs an API call with the
values for client ID and client secret obtained from a registered
developer app as follow.
POST http://<wp_base_url>/wp-json/moserver/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&
client_id=<client_id>&
client_secret=<clientSecret>&
redirect_uri=<redirect_uri>&
scope=<permisssions_requested>
Request Parameters:
- The POST request parameters are explained below.
-
grant_type=client_credentials : This tells the server
we’re using the client credentials grant type.
-
client_id= The public identifier of the application
that the developer obtained during registration.
-
client_secret: The client secret provided by the OAuth
provider.
-
redirect_uri : Callback Url to which user will be
redirected once they allow or disallow the access to your app.
-
scope : One or more space seperated strings which
indicates the permission your application requesting.
If the credentials are valid, the application will receive back a
signed JSON Web Token or access token, the token's type (which is
Bearer), and in how much time it expires in Unix time .
Sample Response
{
"access_token": <access_token>,
"expires_in": 600,
"token_type": "Bearer"
}
Response Elements:
-
access_token : access token for the Userinfo endpoint.
- expires_in The expiry time for the access token.
-
token_type: OAuth 2.0 token type value. The value must
be Bearer.
Resource Request
- The Client Credentials Grant does not support Resource Request.
Refresh Token Grant
-
A Refresh Token allows the application to issue a new Access Token or
ID Token without having to re-authenticate the user. This will work as
long as the Refresh Token has not been revoked.
-
Token Request
-
The response of token request should contain access token ans
refresh token.
{
"access_token": "etMv23....429hiU32Hri",
"refresh_token": "GEbRxBN...edjnXbL",
"token_type": "Bearer"
}
Use a Refresh Token:
To exchange the Refresh Token you received for a new Access Token,
make a POST request to the token endpoint, using
grant_type=refresh_token as follows.
POST http://<wp_base_url>/wp-json/moserver/token
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&
client_id=<client_id>&
client_secret=<client_secret>&
refresh_token=<refresh_token>
Here, is the description for each request parameter.
-
grant_type=refresh_token : This tells the server
we’re using the refresh token grant type.
-
client_id= The public identifier of the application
that the developer obtained during registration.
-
client_secret: The client secret provided by the
OAuth provider.
- refresh_token : The refresh token to use.
The response will include a new Access Token, its type, its lifetime
(in seconds), and the granted scopes. If the scope of the initial
token included openid, then a new ID Token will be in the response
as well.
Response will contain parameters as follows:
{
"access_token": "eyJ...MoQ",
"expires_in": 86400,
"scope": <scope>,
"id_token": "eyJ...0NE",
"token_type": "Bearer"
}
Revoke a Refresh Token
-
Since Refresh Tokens never expire, it is essential to be able to
revoke them in case they get compromised.
-
To revoke a Refresh Token, you can send a POST request to token
endpoint as follows.
POST http://<wp_base_url>/wp-json/moserver/token
Content-Type: application/x-www-form-urlencoded
client_id=<client_id>&
client_secret=<client_secret>&
refresh_token=<refresh_token>
Free Trial
If you don't find what you are looking for, please contact us at
info@miniorange.com
or call us at +1 978 658 9387 to find an answer to your
question about Wordpress OAuth Server.
Watch the videos to learn more
Watch Demo