OAuthService

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

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

Method signature

copy
void getAuthCode(String clientId, Set<String> scopes, OAuthCodeFlowType oauthFlowType, Map<String, String> extendedInfo, APIContext apiContext, Callback<OAuthResult> callback);

Request parameters

Field

Data type

Description

Required

clientId

String

The unique ID that is assigned by Mini Program Platform to identify a mini program.

Yes

scopes

Set<String>

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.

Yes

oauthFlowType

String

The type of the mini program. Valid values are:

  • ALIPAY_CONNECT: The mini program is published from the Alipay Connect mini program workspace.
  • LOCAL_MINI_PROGRAM: The mini program is published to the local Super App workspace only.

Yes

extendedInfo

Map<String, String>

An extended attribute that is used to provide additional information if necessary.

No

apiContext

APIContext

A context object, which carries the mini program runtime metadata.

Yes

callback

Callback

The callback that is executed when request processing is completed. For details, see the following section.

Yes

Callback

Field

Data type

Description

Required

result

OAuthResult

The result of the getAuthCode request.

Yes

Response parameters

N/A

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
public void showAuthPage(String clientId, String name, String logo, Set<String> scopes, Map<String, String> extendedInfo, APIContext apiContext, Callback<OAuthPageConfirmResult> callback);

Request parameters

Field

Data type

Description

Required

clientId

String

The unique ID that is assigned by Mini Program Platform to identify a mini program.

Yes

scopes

Set<String>

The authorization scopes that require the user's agreement. The values fall within those specified in the scopes request parameter of getAuthCode.

Yes

name

String

The name of the mini program that requests the scopes.

Yes

logo

String

The logo URL of the mini program that requests the scopes.

No

extendedInfo

Map<String, String>

An extended attribute that is used to provide additional information if necessary.

No

apiContext

APIContext

A context object, carries the mini program runtime metadata.

Yes

callback

Callback

The callback that is executed when request processing is complete. For details, see the following section.

Yes

Callback

Field

Data type

Description

Required

result

OAuthPageConfirmResult

The result of the showAuthPage request.

Yes

Response parameters

N/A

getAuthorizedScopes

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

Method signature

copy
void getAuthorizedScopes(String clientId, Map<String, String> extendedInfo, APIContext apiContext, Callback<OAuthScopeQueryResult> callback);

Request parameters

Field

Data type

Description

Required

clientId

String

The unique ID that is assigned by Mini Program Platform to identify a mini program.

Yes

extendedInfo

Map<String, String>

An extended attribute that is used to provide additional information if necessary.

No

apiContext

APIContext

A context object, carries the mini program runtime metadata.

Yes

callback

Callback

The callback that is executed when request processing is complete. For details, see the following section.

Yes

Callback

Field

Data type

Description

Required

result

OAuthScopeQueryResult

The result of the getAuthorizedScopes request.

Yes

Response parameters

N/A

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:

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

Java

copy
public void OAuthServiceImpl implements OAuthService {
    @Override
    public void getAuthCode(
        String appId, Set < String > scopes,
        OAuthCodeFlowType oAuthCodeFlowType,
        Map < String, String > extendedInfo,
        APIContext apiContext,
        Callback < OAuthResult > callback) {
    
        //The logic to be executed if the requested scopes require the user's consent
        if (userConsentNeeded) {
            OAuthResult oAuthResult = new OAuthResult();
            oAuthResult.setResultError(new ResultError(ResultError.ERROR_CODE_AUTH_PENDING_AGREEMENT, ""));
            callback.result(oAuthResult);
    
            return;
        }
    
        //The logic to be executed if OAuth is successful 
        if (oAuthSuccessful) {
            OAuthResult oAuthResult = new OAuthResult();
            oAuthResult.authCode = "AUTH_CODE";
            oAuthResult.authErrorScopes = new HashMap < > ();
            oAuthResult.authSuccessScopes = new String[];
            callback.result(oAuthResult);
            return;
        }
    
        //The logic to be executed if Oauth fails
        if (oAuthUnsuccessful) {
            OAuthResult oAuthResult = new OAuthResult();
            oAuthResult.setResultError(
                new ResultError(ResultError.ERROR_CODE_UNKNOWN_ERROR, "error_description"));
            callback.result(oAuthResult);
            return;
        }
    }

    @Override
    public void showAuthPage(
        String appId, String name, String logo,
        Set<String> scopes,
        Map<String, String> extendedInfo,
        APIContext apiContext,                          
        Callback<OAuthPageConfirmResult> callback) {
        
        //Show user authorization dialog
        showAuthorizationPage(appId, name, logo, scopes, new AuthorizationCallback(){
            public void callback(boolean userAgrees) {
                //The logic to be executed if the user agrees
                if (userAgrees) {
                    //Cache scopes
                    String authClientId = extendedInfo.get("authClientId");
                    cacheScopes(appId, authClientId, scopes);
                    callback.result(new OAuthPageConfirmResult(null));
                } else {
                    //The logic to be executed if the user declines or cancels the permission request
                    OAuthPageConfirmResult oAuthResult = new OAuthPageConfirmResult(null);
                    oAuthResult.setResultError(new ResultError(ResultError.ERROR_CODE_USER_CANCEL, ""));
                    callback.result(oAuthResult);
                }
            }
        });
    }

    @Override
    public void getAuthorizedScopes(String appId, Map<String, String> extendedInfo,APIContext apiContext,
                                    Callback<OAuthScopeQueryResult> callback) {
        //The logic to retrieve a list of the authorized scopes
        String [] scopes = getScopesForId(appId);
        OAuthScopeQueryResult result = new OAuthScopeQueryResult();
        result.setAuthorizedScopes(scopes);
        callback.result(result);
    }
}

Kotlin

copy
class OAuthServiceImpl : OAuthService {
    override fun getAuthCode(
        appId: String?, scopes: Set<String>?,
        oAuthCodeFlowType: OAuthCodeFlowType?,
        extendedInfo: Map<String, String>?,
        apiContext: APIContext?,
        callback: Callback<OAuthResult>?) {
    
         //The logic to be executed if the requested scopes require the user's consent
        if (userConsentNeeded) {
            val oAuthResult = OAuthResult()
            oAuthResult.setResultError(ResultError(ResultError.ERROR_CODE_AUTH_PENDING_AGREEMENT, ""))
            callback?.result(oAuthResult)
            return
        }
    
        //The logic to be executed if OAuth is successful
        if (oAuthSuccessful) {
            val oAuthResult = OAuthResult()
            oAuthResult.setAuthCode("AUTH_CODE")
            oAuthResult.setAuthErrorScopes(HashMap())
            oAuthResult.setAuthSuccessScopes(arrayOf))
            callback?.result(oAuthResult)
            return
        }
    
        //The logic to be executed if Oauth fails
        if (oAuthUnsuccessful) {
            val oAuthResult = OAuthResult()
            oAuthResult.resultError = 
                ResultError(ResultError.ERROR_CODE_UNKNOWN_ERROR, "error_description")
            callback?.result(oAuthResult)
            return
        }
    }

    override fun showAuthPage(
        appId: String?, name: String?, logo: String?,
        scopes: Set<String>?,
        extendedInfo: Map<String, String>?,
        apiContext: APIContext?,
        callback: Callback<OAuthPageConfirmResult>?){
    
        //Show user authorization dialog
        showAuthorizationPage(appId, name, lopo, scopes,
                object : AuthorizationCallback() {
                    fun callback(userAgrees: Boolean) {
                        //The logic to be executed if the user agrees
                        if (userAgrees) {
                            //Cache scopes
                            val authClientId = extendedInfo!!["authClientId"]
                            cacheScopes(appId, authClientId, scopes)
                            callback?.result(OAuthPageConfirmResult(null))
                        } else {
                            //The logic to be executed if the user declines or cancels the permission request
                            val oAuthResult = OAuthPageConfirmResult(null)
                            oAuthResult.resultError =
                                ResultError(ResultError.ERROR_CODE_USER_CANCEL, "")
                            callback?.result(oAuthResult)
                        }
                    }
                })
    }

    override fun getAuthorizedScopes(appId: String?, extendedInfo: Map<String?, String?>?, apiContext: APIContext?,callback: Callback<OAuthScopeQueryResult?>) {
        //The logic to retrieve a list of the authorized scopes
        val scopes: Array<String> = getScopesForId(appId)
        val result = OAuthScopeQueryResult()
        result.authorizedScopes = scopes
        callback?.result(result)
    }
}