OAuth 2.0 Service

Access info

Usage

The OAuth Service provides means to programmatically authorize users with Google or Microsoft, for various business purposes that may be implemented in your application. For example, your application may allow users to send email managed by Google or Microsoft 365 providers directly from within the app.

Implementing OAuth 2.0 authorization with Google

To enable users of your app to connect their Google inbox to the app, the following prerequisites must be in place:

1. From the Google Cloud Console (https://console.cloud.google.com/), you must create or update your Google project (Google app) so that it has support for Gmail API and OAuth 2.0 client credentials. For details, see Obtain OAuth 2.0 credentials from Google.
2. Once you obtained your OAuth 2.0 credentials from Google, you must update the SBS app accordingly. For details, see Configure Google OAuth 2.0 secrets.

To authorize the user, you need to interact only with the SBS API (not directly with Google APIs). Note the following:

• The OAuth 2.0 access and refresh tokens obtained from Google as part of this process are stored by SBS and your app does not need to manage them at all.
• To perform the authorization, you will need to provide the internal user’s ID in your application (the so-called approver) as input to the generateAuthorizationRequest mutation. Once the authorization process is complete, you will receive in the response an Authorization object associated with that user ID. As long as the authorization exists, the user may perform the actions allowed by the authorization’s scope (such as sending email).
• To view any of the previous authorizations, run the authorizations query.
• To revoke an authorization, run the revokeAuthorization mutation.

The following diagram illustrates the OAuth 2.0 authorization process from the SBS perspective:

The process consists of the following steps:

1. Run the generateAuthorizationRequest mutation. The mandatory parameter approver must be set to the internal identifier (ID) of the user in the calling application. As a result, you will receive the url of the authorization request. This will be required in the next step.

mutation gen_auth_req($input: GenerateAuthorizationRequestInput!) {
  generateAuthorizationRequest(input: $input) {
    url
  }
}

{
  "input": {
    "approver": "YOUR_USER_ID",
    "provider": "GOOGLE",
    "scope": ["EMAIL_SEND","USER_INFO_EMAIL"]
  }
}

2. Redirect the user to the URL received in the previous step. The user will now see the consent screen, from where they can allow or deny access of your app to their Google account. If the user allows access, they are redirected to the redirectUrl specified in App settings. Note that the redirect URL contains an authorization code and state as query parameters, for example:

3. Now that you have the authorization code, you can run the finalizeAuthorization mutation, for example:

mutation final_auth($input: FinalizeAuthorizationInput) {
  finalizeAuthorization(input: $input) {
    id
    approver
    provider
    scope
    createdAt
    userInfo {
      email
    }
  }
}

Make sure to populate input variables with the authorization state and code received in the previous step.

{
  "input": {
    "state": "YOUR_STATE",
    "code": "YOUR_AUTHORIZATION_CODE"
  }
}

You can now use the approver value (ID of the authorized user) in calls that require OAuth 2.0 authorization (such as the sendMessage mutation of the Email Service). For example, in the sendMessage mutation of the Email Service, one of the sub-fields of the from parameter is oauthApprover. When running this mutation, fill in this parameter value with the approver value used previously. For more information, see Sending email from a Google or Microsoft 365® email address.

Implementing OAuth 2.0 authorization with Microsoft

To enable users of your app to connect their Microsoft 365 inbox to the app, the following prerequisites must be in place:

1. Your company must hold an Azure portal account (https://azure.microsoft.com) and be enrolled in the Microsoft Cloud Partner program (https://partner.microsoft.com). The latter ensures that users who give consent to your application to send email on their behalf will see a verified application publisher on the consent screen.
2. On the Azure portal, you must create a new app registration so as to obtain the OAuth 2.0 client credentials required for performing on demand OAuth 2.0 authorizations. Also, your Azure application must have permissions to send email through the Microsoft Graph API. For details, see Configure an Azure app.
3. The account that owns the Azure application must hold a Microsoft 365 Business Standard subscription.
4. Once your app is configured in Azure, you must enter its OAuth 2.0 credentials (that is, client secret, client ID, directory ID, and redirect URI) into SBS. For details, see Configure Azure OAuth 2.0 secrets.

Otherwise, the implementation itself is exactly the same one as described above for Google. Namely, there are two steps to the authorization process:

1. Run generateAuthorizationRequest, in which you indicate (a) the ID of the user for whom authorization is requested, (ii) the scopes of the authorization (currently, you can use any of EMAIL_READ, EMAIL_SEND, and USER_INFO_EMAIL). The user is then redirected to the consent screen where they can grant authorization to your app for the requested scopes. When the user completes the authorization process, they are redirected to the configured redirect URI, which includes the code and state query parameters in the response. There is also a third response parameter called session_state which is currently not in use.
2. Using the obtained authorization code and the state, run finalizeAuthorization to store the authorization for the given user. As long as the authorization exists, the respective user will be able to perform actions granted by the authorization scope.

To revoke existing authorizations, run revokeAuthorization.

Queries

authorizations

Lists previously created authorization records.

Arguments

AuthorizationsFilter input

Result

Authorization type

UserInfo type

version

Returns the API version.

Mutations

finalizeAuthorization

Finalizes an authorization request previously created through generateAuthorizationRequest. This is the second step towards obtaining the OAuth 2.0 access token from the third-party provider.

Arguments

FinalizeAuthorizationInput input

Result

See the Authorization type.

generateAuthorizationRequest

Generates an authorization request. This is the first step towards obtaining the OAuth 2.0 access token from the third-party provider.

Arguments

GenerateAuthorizationRequestInput input

Result

AuthorizationRequest type

revokeAuthorization

Deletes a previously created authorization. The outcome is that the user ID to which this authorization belongs will no longer be able to perform actions within the scope granted by the authorization.

Arguments

RevokeAuthorizationInput input

Result

See the Authorization type.