Skip to main content

OAuth2.0 Authorization Code Grant API Doc

1. Integration Instructions

Guandata BI system supports OAuth2.0 integration using the authorization code grant. This document is for integrating or evaluating whether the authentication/authorization center's interface meets the requirements. The interface design complies with the OAuth2.0 standard protocol.

1.1. Flow Diagram

1.png

2. Obtain Authorization Code

Request

Method: GET
API URL: Configurable in BI
Content-Type: application/x-www-form-urlencoded
ParameterRequiredDescription
response_typeYesAuthorization type, here is "code".
client_idYesYour application's client ID.
redirect_uriNoThe URI to which the authorization server will redirect the user. Only present if "callback address" is configured in BI. Whether this parameter is needed depends on the authorization system, usually set as BI domain + /standard-oauth2/authenticate.
stateYesRandom string to prevent CSRF.
GET /{authorize_url}?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&state={state}
  • If there are other fixed parameters, they can be configured in the URL.

Response

If the user agrees to authorize, the authorization server will redirect to redirect_uri and append the authorization code (code) and the state you passed in the URL query parameters.

{redirect_uri}?code={authorization_code}&state={state}
  • Note: state must be returned as is. Many OAuth2.0 systems do not have this parameter or do not return the original value.

3. Obtain Access Token via Authorization Code

Method: POST
API URL: Configurable in BI
Content-Type: application/x-www-form-urlencoded

Request

ParameterRequiredDescription
grant_typeYesAuthorization type, here is "authorization_code".
codeYesThe obtained authorization code.
redirect_uriNoThe URI to which the authorization server will redirect the user. Only present if "callback address" is configured in BI. Whether this parameter is needed depends on the authorization system, usually set as BI domain + /standard-oauth2/authenticate.
client_idYesApplication's client ID.
client_secretYesApplication's client secret.
grant_type=authorization_code&code={authorization_code}&redirect_uri={redirect_uri}&client_id={client_id}&client_secret={client_secret}
  • If there are other fixed parameters, please contact Guandata for configuration.

Response

Content-Type: application/json;charset=UTF-8

ParameterRequiredDescription
access_tokenYesAccess token for accessing protected resources.
token_typeNoToken type.
expires_inNoValidity period of the access token (seconds).
refresh_tokenNoRefresh token for obtaining a new access token after the current one expires.
{
  "access_token": "{access_token}",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "{refresh_token}"
}

4. Obtain User Info

  • Not part of the standard protocol
  • BI supports flexible configuration of request method, URL, headers, body, etc.
  • Supports parsing the unique user identifier field from the response data

5. Single Sign-Out

  • Logout redirect can be configured

6. FAQ

6.1. Common Interface Mismatches

  • The request method, Content-Type, and parameter names for the authorization code and access token interfaces do not match. Pay special attention to:
    • Whether the callback interface for obtaining the authorization code has the state parameter
    • Whether the access token interface response format has access_token at the first level of JSON
    • The Content-Type for the access token request should be application/x-www-form-urlencoded, not application/json

7. Reference