OAuth2 module, provides support of OAuth 2.0 protocol (server side) according to RFC 6749 and 6750 (and some extended features)

Server authorization:

  1. 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
  2. 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
  3. 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:

  1. 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):

  1. 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):

  1. 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):

  1. 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):

  1. Every request should contain header:

    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