OAuthService

When the mini program requests access to specific scopes (resources or capabilities), IAPMiniProgram SDK calls the OAuthService SPI to request the Super App to generate authorization codes for the mini program.

getAuthCode

Method signature

Call the getAuthCode method to request the Super App to generate authorization codes for the mini program.

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.

Valid values are:

  • SCOPE_AUTH_BASE: The user ID.

Notes:

    • The Super app must support this scope because most mini programs might use it for basic user identification.
    • It is recommended that the super app grant this scope silently without requesting the user's agreement.
  • SCOPE_AUTH_USER: The basic user profile information, which can include the user ID, gender, avatar, and so on.

Notes:

    • The Super App must support this scope because most mini programs might require it.
    • When this scope is used, it's recommended that the user needs to manually click to agree the authorization.

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 (For details, see the following section)

The callback that is executed when request processing is completed.

Yes

Callback

Field

Data type

Description

Required

result

OAuthResult

The result of the getAuthCode request.

Yes

Response parameters

N/A

showAuthPage

Method signature

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.

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, which represent the resources or capabilities that are requested by the mini program.

Yes

name

String

Auth client name

Yes

logo

String

Auth client logo

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 (For details, see the following section)

The callback that is executed when request processing is complete.

Yes

Callback

Field

Data type

Description

Required

result

OAuthPageConfirmResult

The result of the showAuthPage request.

Yes

Response parameters

N/A

getAuthorizedScopes

Method signature

The Super App calls this method to retrieve a list of authorized scopes that are granted to the mini program.

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 (For details, see the following section)

The callback that is executed when request processing is complete.

Yes

Callback

Field

Data type

Description

Required

result

OAuthScopeQueryResult

The result of the getAuthorizedScopes request.

Yes

Response parameters

N/A

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 call the OAuthService SPI to generate authorization codes for the mini program:

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

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)
    }
}