OAuthService

2024-11-08 01:35

When the mini program requests access to specific scopes (resources or capabilities), the IAPMiniProgram SDK calls the OAuthService SPI to request the super app to obtain user authorization and generate authorization codes for the mini program. For details on how the SPI functions, refer to the OAuthService workflow.

This SPI provides the following three methods:

getAuthCode
showAuthPage
getAuthorizedScopes

getAuthCode

IAPMiniProgram calls the getAuthCode method to request the super app to generate authorization codes for the mini program.

Method signature

copy
Future<OAuthResult> getAuthCode(
  String clientId,
  List<String> scopes,
  OAuthCodeFlowType oauthFlowType,
  Map<String, String> extendedInfo,
  APIContext apiContext);

Request parameters

Field	Data type	Required	Description
clientId	String	Yes	The unique ID that is assigned by Mini Program Platform to identify a mini program.
scopes	List<String>	Yes	The authorization scopes, which represent the resources or capabilities that are requested by the mini program. For more information about the valid values, refer to the Scopes section.
oauthFlowType	OAuthCodeFlowType	Yes	The type of the mini program. Valid values are: `ALIPAY_CONNECT`: The mini program is published from the Alipay Connect workspace. `LOCAL_MINI_PROGRAM`: The mini program is published to the local super app workspace only.
extendedInfo	Map<String, String>	No	An extended attribute that is used to provide additional information if necessary.
apiContext	APIContext	Yes	A context object, which carries the mini program runtime metadata.

Response parameters

Field	Data type	Required	Description
result	Future<OAuthResult>	Yes	The result of the `getAuthCode` request.

showAuthPage

The super app calls the showAuthPage method to display an authorization dialog to the user when the requested scopes require the user's agreement before being granted to mini programs.

Method signature

copy
Future<OAuthPageConfirmResult> showAuthPage(String clientId, String name,
      String logo, List<String> scopes, APIContext apiContext,
      {Map<String, String>? extendedInfo});

Request parameters

Field	Data type	Required	Description
clientId	String	Yes	The unique ID that is assigned by Mini Program Platform to identify a mini program.
scopes	List<String>	Yes	The authorization scopes that require the user's agreement. The values fall within those specified in the scopes request parameter of `getAuthCode`.
name	String	Yes	The name of the mini program that requests the scopes.
logo	String	No	The logo URL of the mini program that requests the scopes.
extendedInfo	Map<String, String>?	No	An extended attribute that is used to provide additional information if necessary.
apiContext	APIContext	Yes	A context object, which carries the mini program runtime metadata.

Response parameters

Field	Data type	Required	Description
result	Future<OAuthPageConfirmResult> (extends BaseServiceResult)	Yes	The result of the `showAuthPage` request.

getAuthorizedScopes

IAPMiniProgram calls this method to retrieve a list of scopes that the super app supports for granting to mini programs.

Method signature

copy
Future<OAuthScopeQueryResult> getAuthorizedScopes(
      String clientId, Map<String, String> extendedInfo, APIContext apiContext);

Request parameters

Field	Data type	Required	Description
clientId	String	Yes	The unique ID that is assigned by Mini Program Platform to identify a mini program.
extendedInfo	Map<String, String>	No	An extended attribute that is used to provide additional information if necessary.
apiContext	APIContext	Yes	A context object, which carries the mini program runtime metadata.

Response parameters

Field	Data type	Required	Description
result	Future<OAuthScopeQueryResult>	Yes	The result of the `getAuthorizedScopes` request.

Scopes

The following table lists the scopes that are defined by Mini Program Platform:

Scope

Description

auth_base

The unique ID that is assigned by the super app to identify a user.

Note:

The super app must support this scope because most mini programs might request it for basic user identification.
It is recommended that the super app grant this scope silently without requesting the user's agreement.

auth_user

The basic user profile information, including the user ID, avatar, etc.

Note:

The super app must support this scope because most mini programs might require it.
This scope is requested when IAPMiniProgram SDK calls the MemberInfoService SPI to obtain the basic user information.
It is recommended that the super app request the user's agreement before granting this scope.

Error codes

Error code		Error message
1000	ERROR_CODE_UNKNOWN_ERROR	Unknown error
1001	ERROR_CODE_USER_CANCEL	The user cancels the operation.
1002	ERROR_CODE_APP_SERVICE_ERROR	The app service is wrong.
1003	ERROR_CODE_TIMEOUT	Timeout
2001	ERROR_CODE_AUTH_PENDING_AGREEMENT	Authorization is not finished or is pending.
1005	ERROR_CODE_SYSTEM_ERROR	System error

Samples

The following samples show how to implement the OAuthService SPI to generate authorization codes for mini programs:

Create a class that implements the OAuthService interface.
Implement the getAuthorizedScopes method to provide a list of the supported scopes.
Implement the getAuthCode method to generate authorization codes for the mini program.
Implement the showAuthPage method to show the user authorization dialog.

The samples differ depending on whether to open a Flutter page during the SPI call:

Open a Flutter page

copy
class TestOAuthService implements OAuthService {
  @override
  Future<OAuthResult> getAuthCode(
    String clientId,
    List<String> scopes,
    OAuthCodeFlowType oauthFlowType,
    Map<String, String> extendedInfo,
    APIContext apiContext) async {
    OAuthResult result = OAuthResult();
    result.showFlutterPage = true;
    result.flutterPageRoute = "/XXX";// Here is the routing address of the Flutter page you are about to open.
    // result.error = BaseError(
    //     BaseServiceResult.ERROR_CODE_AUTH_PENDING_AGREEMENT.toString(),
    //     'ERROR_CODE_AUTH_PENDING_AGREEMENT');
    return result;
  }

  @override
  Future<OAuthScopeQueryResult> getAuthorizedScopes(
    String clientId,
    Map<String, String> extendedInfo,
    APIContext apiContext) async {
    OAuthScopeQueryResult result =
      OAuthScopeQueryResult();
    result.showFlutterPage = true;
    result.flutterPageRoute = "/XXX";// Here is the routing address of the Flutter page you are about to open.
    return result;
  }

  @override
  Future<OAuthPageConfirmResult> showAuthPage(String clientId,
                                              String name, String logo, List<String> scopes, APIContext apiContext,
                                              {Map<String, String>? extendedInfo}) async {
    OAuthPageConfirmResult result =
      OAuthPageConfirmResult("xxx");
    result.showFlutterPage = true;
    result.flutterPageRoute = "/XXX";// Here is the routing address of the Flutter page you are about to open.
    return result;
  }
}

Remain inside the mini program

copy
class TestOAuthService implements OAuthService {
  @override
  Future<OAuthResult> getAuthCode(
    String clientId,
    List<String> scopes,
    OAuthCodeFlowType oauthFlowType,
    Map<String, String> extendedInfo,
    APIContext apiContext) async {
    OAuthResult result = OAuthResult();
    result.authCode = "XXX"
      return result;
  }

  @override
  Future<OAuthScopeQueryResult> getAuthorizedScopes(
    String clientId,
    Map<String, String> extendedInfo,
    APIContext apiContext) async {
    OAuthScopeQueryResult result =
      OAuthScopeQueryResult(["auth_base", "auth_user"]);
    return result;
  }

  @override
  Future<OAuthPageConfirmResult> showAuthPage(String clientId,
                                              String name, String logo, List<String> scopes, APIContext apiContext,
                                              {Map<String, String>? extendedInfo}) async {
    OAuthPageConfirmResult result =
      OAuthPageConfirmResult("XXXX");
    return result;
  }
}