OAuth2 module, provides support of OAuth 2.0 protocol (server side) according to RFC 6749 and 6750 (and some extended features)
Server authorization:
-
Open authentication dialog at:
GET /OAuth2/authorize?
response_type=code&
client_id=client_id&
redirect_uri=redirect_uri&
state=state
- client_id
- Id of client in administration of OAuth2 module [REQUIRED]
- redirect_uri
- URL to redirect to after the user allows or denies access. URL should be from the domain in client settings, supports custom uri schemes. [REQUIRED]
- state
- Random string, usually session id, which is used in order to protect against CSRF [OPTIONAL]
Successful request
Browser will redirect to:
redirect_uri?
code=code&
state=state
- redirect_uri
- Parameter, given in request
- state
- Parameter, given in request
- code
- Code, generated by system, is used to obtain token
Error request
Browser will redirect to URL like:
redirect_uri?
error=error&
error_description=error_description&
state=state
- redirect_uri
- Parameter, given in request
- error
- Error code according to RFC 6749
- error_description
- Simple description, explaining error reason
- state
- Parameter, given in request
-
Obtaining access_token:
POST /OAuth2/token
grant_type=authorization_code&
client_id=client_id&
client_secret=client_secret&
code=code&
redirect_uri=redirect_uri
- client_id
- Id of client in administration of OAuth2 module [REQUIRED]
- client_secret
- Secret from client settings [REQUIRED]
- code
- Code from previous step [REQUIRED]
- redirect_uri
- redirect_uri from previous step, should be identical [REQUIRED]
Successful request
Browser will return JSON data with header "Content-Type: application/json" and status code HTTP 200 (OK):
{
"access_token":"access_token",
"refresh_token":"refresh_token",
"expires_in":expires_in,
"token_type":"bearer",
"user_id":"user_id"
}
- access_token
- Token, that will be used in API request
- refresh_token
- Token, that will be used to obtain new access_token, when old expires
- expires_in
- Number of seconds, remained to access_token expiration
- user_id
- Internal system id of user
Error request
Browser will return JSON data with header "Content-Type: application/json" and status code HTTP 400 (Bad Request) or HTTP 500 (Internal Server Error) or HTTP 403 (403 Forbidden):
{
"error":"error",
"error_description":"error_description"
}
- error
- Error code according to RFC 6749
- error_description
- Simple description, explaining error reason
-
Obtaining new access_token (when old expired) using refresh_token:
POST /OAuth2/token
grant_type=refresh_token&
client_id=client_id&
client_secret=client_secret&
refresh_token=refresh_token
- client_id
- Id of client in administration of OAuth2 module [REQUIRED]
- client_secret
- Secret from client settings [REQUIRED]
- refresh_token
- refresh_token from previous step [REQUIRED]
Successful request
Browser will return JSON data with header "Content-Type: application/json" and status code HTTP 200 (OK):
{
"access_token":"access_token",
"refresh_token":"refresh_token",
"expires_in":expires_in,
"token_type":"bearer",
"user_id":"user_id"
}
- access_token
- Token, that will be used in API request
- refresh_token
- Token, that will be used to obtain new access_token, when old expires
- expires_in
- Number of seconds, remained to access_token expiration
- user_id
- Internal system id of user
Error request
Browser will return JSON data with header "Content-Type: application/json" and status code HTTP 400 (Bad Request) or HTTP 500 (Internal Server Error) or HTTP 403 (403 Forbidden):
{
"error":"error",
"error_description":"error_description"
}
- error
- Error code according to RFC 6749
- error_description
- Simple description, explaining error reason
Client authorization:
-
Open authentication dialog at:
GET /OAuth2/authorize?
response_type=token&
client_id=client_id&
redirect_uri=redirect_uri&
state=state
- client_id
- Id of client in administration of OAuth2 module [REQUIRED]
- redirect_uri
- URL to redirect to after the user allows or denies access. URL should be from the domain in client settings, supports custom uri schemes. [REQUIRED]
- state
- Random string, usually session id, which is used in order to protect against CSRF [OPTIONAL]
Successful request
Browser will redirect to:
redirect_uri#
access_token=access_token&
expires_in=expires_in&
user_id=user_id&
token_type=bearer&
state=state
- redirect_uri
- Parameter, given in request
- access_token
- Token, that will be used in API request
- expires_in
- Number of seconds, remained to access_token expiration
- user_id
- Internal system id of user
- state
- Parameter, given in request
Error request
Browser will redirect to URL like:
redirect_uri#
error=error&
error_description=error_description&
state=state
- redirect_uri
- Parameter, given in request
- error
- Error code according to RFC 6749
- error_description
- Simple description, explaining error reason
- state
- Parameter, given in request
Guest access (server authorization) (beyond RFC 6749 specification, may be disabled by administrator):
-
Obtaining access_token:
POST /OAuth2/token
grant_type=guest_token&
client_id=client_id&
client_secret=client_secret
- client_id
- Id of client in administration of OAuth2 module [REQUIRED]
- client_secret
- Secret from client settings [REQUIRED]
Successful request
Browser will return JSON data with header "Content-Type: application/json" and status code HTTP 200 (OK):
{
"access_token":"access_token",
"refresh_token":"refresh_token",
"expires_in":expires_in,
"token_type":"bearer",
"user_id":"user_id"
}
- access_token
- Token, that will be used in API request
- refresh_token
- Token, that will be used to obtain new access_token, when old expires
- expires_in
- Number of seconds, remained to access_token expiration
- user_id
- Internal system id of user, for guest always 1
Error request
Browser will return JSON data with header "Content-Type: application/json" and status code HTTP 400 (Bad Request) or HTTP 500 (Internal Server Error) or HTTP 403 (403 Forbidden):
{
"error":"error",
"error_description":"error_description"
}
- error
- Error code according to RFC 6749
- error_description
- Simple description, explaining error reason
Guest access (client authorization) (beyond RFC 6749 specification, may be disabled by administrator):
-
Obtaining access_token:
GET /OAuth2/authorize?
response_type=guest_token&
client_id=client_id
- client_id
- Id of client in administration of OAuth2 module [REQUIRED]
Successful request
Browser will return JSON data with header "Content-Type: application/json" and status code HTTP 200 (OK):
{
"access_token":"access_token",
"expires_in":expires_in,
"token_type":"bearer",
"user_id":"user_id"
}
- access_token
- Token, that will be used in API request
- expires_in
- Number of seconds, remained to access_token expiration
- user_id
- Internal system id of user, for guest always 1
Error request
Browser will return JSON data with header "Content-Type: application/json" and status code HTTP 400 (Bad Request) or HTTP 500 (Internal Server Error) or HTTP 403 (403 Forbidden):
{
"error":"error",
"error_description":"error_description"
}
- error
- Error code according to RFC 6749
- error_description
- Simple description, explaining error reason
Token invalidation (both server and client) (beyond RFC 6749 specification, used for proper sign out for API clients):
-
Invalidating access_token:
POST /OAuth2/invalidate_token
access_token=access_token
- access_token
- Token, that will was used in API request [REQUIRED]
Successful request
Browser will return empty body and status code HTTP 200 (OK)
Error request
Browser will return JSON data with header "Content-Type: application/json" and status code HTTP 400 (Bad Request) or HTTP 500 (Internal Server Error) or HTTP 403 (403 Forbidden):
{
"error":"error",
"error_description":"error_description"
}
- error
- Error code according to RFC 6749
- error_description
- Simple description, explaining error reason
API requests (using Bearer token, RFC 6750):
-
Every request should contain header:
- Authorization: Bearer access_token
Successful request
Browser will return data according to format, provided by module.
Error request
Browser will return JSON data with header "Content-Type: application/json" and status code HTTP 400 (Bad Request) or HTTP 500 (Internal Server Error) or HTTP 403 (403 Forbidden):
{
"error":"error",
"error_description":"error_description"
}
- error
- Error code according to RFC 6749
- error_description
- Simple description, explaining error reason