This article was written for a public-facing knowledge base, targeting new administrators who need to set up integrations between business software solutions. The challenge was to explain a complex security protocol (OAuth) in a way that is both reassuring and technically accurate, without using excessive jargon. The writing adopts an encouraging tone and uses a simple, relatable analogy to make a potentially confusing topic feel safe and understandable.
This was written based on a developer portal page that explained the authorization flow, and includes a space reserved for a video discussion of the topic produced by their product team. The original company has been redacted to preserve their brand.
Product A lets you connect with third-party applications to enhance your workflows. For instance, you can launch sessions directly from your favorite CRM to streamline your work. To enable these integrations securely, we use a process called OAuth. OAuth allows these apps to access Product A without ever seeing your login credentials—keeping your account safe and secure.
What is OAuth?
OAuth allows secure and limited access to Product A while keeping your login credentials confidential. OAuth is a widely used security protocol — if you’ve used a social media or Google account to login to another service, you’ve likely used OAuth!
Grant temporary access with OAuth
When you’re ready to take advantage of an integration with Product A, you will typically need to select a Login with Product A button from the application you will integrate. To start the process:
- Select Login with Product A.
- If you are not logged into Product A, the system will prompt you to login with your username and password.
- Confirm that you would like to grant access to the application. This page lists the specific permissions granted to the application, be sure to review them carefully.
- The system will redirect you to the third-party application, which now has temporary, limited access to Product A. The integration may require additional configuration in your application, but the authorization is fully complete!
Note: Only enter your login credentials if the address for the login page reads: “
https://**[AppName].com**/oauth2/authorize?...”
How OAuth works
OAuth works a bit like a valet service: registered apps work like valets. When you want to give the valet access to your car, you make an agreement with the valet service that the valet can do certain things and provide your consent. Unlike an actual valet service, with OAuth you don’t have to provide the valet with your keys (username and password)! An OAuth service issues a temporary set of keys (an access token) instead. The app uses this access token to access your app data, and your actual username and password are never shared with the third-party app.
Here’s how this works in practice: When you use one of these apps, you’ll encounter a button that says Login with Product A. Selecting this will start a conversation between the app and Product A, redirecting your browser to Product A.
If Product A recognizes the third-party app, it will check whether you are already logged in with Product A. If not, you have the opportunity to securely log in. Once you are logged in, you have the final say in granting access permissions: you’ll see a page that asks you to confirm whether you’d like to grant access to this application.
To complete the process, confirm that you would like to provide access to the integration. Product A will issue temporary access tokens to the application and you’ll be returned to the application, ready to use all of the new exciting integrated features.
Typically, integrations provide you with a means of disconnecting your service, but your admins can enable and disable integrations through the Integrations page in Product A (link).
Promotional Video: Unlocking Your Workflow with Integrations
Is this secure?
Yes! By using OAuth, Product A protects your account through:
- Securing your credentials: By using OAuth, only Product A has access to your username and password.
- Defined permissions: Product A grants the third-party application limited, defined permissions. You have the opportunity to review the specific permissions on the confirmation page.
- Leaving you in control: Users and admins can revoke and control access from Product A.
- Keeping you informed: The confirmation page is transparent and leaves you in control of granting access.
- Limiting access: Access tokens are temporary. After a set period, the third-party application must request a new token, ensuring that even if a token is compromised, its use is limited in time.
Frequently asked questions
What happens to my data if I disable the integration?
- The application loses access to your Product A data. However, check their policies as they may retain previously accessed data.
Can I verify that an integration is official?
- The integrations page lists available integrations that can be enabled for your company. You may need to consult with your administrators to learn about a particular integration.