Documentation
DocumentationDeveloperAcademyCommunitySupportLogin
Start typing to searchā€¦

OAuth 2.0 - Authorization Code

OAuth 2.0 with Authorization Code Grant

šŸš§

Limited Preview Capability

This capability is currently in Limited Preview. You can learn more in our community.

The OAuth 2.0 Authorization Code Grant is a secure authentication method designed for applications that require delegated access to user resources. This flow is commonly used by web and mobile applications that need to authenticate users and obtain an access token to act on their behalf.

In this flow, the user is redirected to the authorization server (your application) to grant permissions. Once authorized, the server provides an authorization code, which the application exchanges for an access token.

After obtaining the access token, the application can use it to authenticate API requests on behalf of the user. If the access token expires, the application may use a refresh token (if provided) to obtain a new one, avoiding the need for re-authentication.

šŸ“˜

Helpful Information:

Callback URL: https://<org>.moveworks.com/auth/oauthCallback


Configuration Steps

  1. Within Moveworks, go to HTTP Connectors


  2. Create a new connector


  3. Enter the: Name, Display Name, and Display Description:

    1. Name: the internal name for this connector.
    2. Display Name: End user facing name for this integration. All end users will see this name so pick an appropriate name. We recommend the system name itself (i.e. Workday, Salesforce, etc.).
    3. Display Description: End user facing description for this integration. All end users will see this description so pick an appropriate description. We recommend being as clear as possible on what this integration unlocks.
      1. I.e.: "This integration allows Moveworks/ (or assistant name) to look up and edit data within Salesforce.

  4. Select Oauth2 from the **Auth Config ** dropdown list.

  5. Then select, Authorization Code Grantfrom the Oauth2 Grant Type drop down.


  6. Enter the following required fields:

    1. Authorization URL: The authorization endpoint for the third-party system. This is obtained from the third-party system's API documentation
    2. Client ID: The Client ID generated from the third-party OAuth application.
    3. Client Secret: The Client Secret generated from the third-party OAuth application.
    4. Authorization Code Grant Scope: The scopes that you wish this connector to have access to. This is obtained from the third-party system's API documentation.
    5. Oauth2 Token Url: The token endpoint for the third-party system. This is obtained from the third-party system's API documentation.

  7. Recommended Info:

    1. Revoke URL: The revocation endpoint for the third-party system. This will allow end-users to revoke their tokens. This is obtained from the third-party system's API documentation and is highly recommended.
    2. Instructions URL (Optional): This URL will be shown to end-users in the case of revocation failing. We recommend putting instructions for end-users to revoke tokens inside of the third-party itself here.
    3. Authorization Code Grant Revoke Access Token Options Revoke Access Token Authentication
    4. Revocation token key: The name of the key that the revocation endpoint would use when sending the access token. We use 'token' by default.
    5. If needed, you can leverage Oauth2 Custom Oauth Request Options Additional Request Data to send additional body data needed for the request. Data is sent in x-www-form-urlencoded format in the body like so: JSON

End User Experience

This auth type does require end users to give access to the 3rd party system. The end user experience is as follows:

  1. If they have previously given consent and they have a valid token: their plugin will proceed like any other plugin.
  2. If they have an invalid token (expired, wrong scopes, etc.) or have never given consent before: they will be asked to give consent with a message like (LLM may summarize differently):
    1. I do not have access to [System Display Name]. To proceed, please go to the connections page [hyperlinked] and give access to [System Display Name]. Once you have given access, please say ā€œretryā€ if to retry your use case.
  3. The user would then click on the link and be taken to the 3rd party authentication page:

  4. The user would then follow the steps to give access. Then they will return to the assistant and say "retry" to continue their use case.

Limited Preview Limitations

See the latest in our community post. As this is a limited preview product, we have the following limitations:

  1. User Consent Auth Actions in slot resolvers If you use a user consent auth action in a dynamic slot resolver within your plugin, the assistant will not prompt the user to give consent if they have not previously given consent.
    1. Mitigation: End users will have to proactively go to the /connections page to give consent or please do not use the user consent out to action within the slot resolver for now.
    2. This is a known bug which we plan to fix in the near future.
  2. End User Experience.
    1. Today, end users have to click on a link, and go through a few clicks to give consent. As we enter preview, we will mimize the number of clicks end users need to have and leverage buttons instead of links.
    2. There will also be an overhaul to the connections page so that end users have more clarity into why access is needed, what systems they have already given access to, etc.
  3. Developer Experience
    1. Today, developers do not have clear visibility into when a token expires and if they have a refreshed token. We will be adding more visibility into token expiry details and if a refreshed token is being sent directly in Agent Studio.
    2. Additionally, developers must create and save connectors in HTTP Connectors, they cannot create the connector inside of the Agent Studio HTTP Action Editor.
  4. Log Redaction Behavior. To maintain proper security standards, any customer in our limited preview program will have the following behavior by default.
    1. All plugins launched to more than 10 users will be enforced to have strict log reduction. If a developer wants to debug a plugin launched to more than 10 users, they would have to:
      1. Unlaunch the plugin and launch to only 10 users.
      2. Reproduce the error
      3. View the logs
      4. Fix the issue
    2. After doing so, they can republish the plugin to more than 10 users which will then enforce strict log reduction.
    3. We will soon release functionality for customers to control preferences directly.

Customers who wish to use this feature must add all their end users to the My Moveworks SSO. This step is essential because it grants end users access to the connections page, where they can provide consent to connect with third-party systems and subsequently utilize plugins. This setup is necessary to ensure a secure implementation of OAuth 2 using the Authorization Code grant type.

End users with access to My Moveworks SSO will not have visibility into developer or admin-facing products unless they have the appropriate roles or permissions. For detailed instructions on adding users to the MyMoveworks SSO, please refer to our SSO documentation: https://help.moveworks.com/docs/sso#/



Updated 7 days ago