This article addresses general questions about OAuth 2.0 and how it's used with SocketTools. It covers a large number of topics and has links to external resources for further reading. We recommend familiarizing yourself with the terminology and general concepts prior to beginning development. Support for OAuth 2.0 is available in all SocketTools 11 editions.
- What is OAuth 2.0 and how is it used?
- Which SocketTools components support OAuth 2.0?
- Do previous versions of SocketTools support OAuth 2.0?
- Does SocketTools support OAuth 1.0a?
- Is OAuth 2.0 required to access some services?
- What are the client ID and client secret?
- What is a bearer token?
- What is a refresh token?
- What are OAuth 2.0 permission scopes?
- What should I use as the redirect URL?
- How do I obtain the bearer and refresh tokens?
- Are there limits on how many tokens I can request?
- Should I store the bearer tokens?
- Can I manually refresh bearer tokens?
- What happens if a bearer token cannot be refreshed?
- Can I use the same token to access different services?
- What changes need to be made to support OAuth 2.0?
- Can I use an embedded browser for authorization?
- What is the difference between XOAUTH2 and OAUTHBEARER?
- Do I need to register my application with the service provider?
- Do I need to have my application verified?
- Are there any special considerations for end users?
- Can you help us get started with OAuth 2.0?
1. What is OAuth 2.0 and how is it used?
OAuth 2.0 is a method for authorizing access to a protected resource, such as a user’s mailbox, cloud storage or a web service. Unlike the traditional method of using a username and password, services which use OAuth 2.0 require a bearer token (also called an access token). These tokens are issued by the service provider and enable your application to access the resource without requiring the user provide you with their password.
For example, to access a user’s Gmail mailbox using POP3 or IMAP, what was typically done is you provide a configuration screen to the user where they enter their username (in this case, their Gmail address) and their password. The problem with this approach is that the user must trust your application will only perform the operations needed and won’t use their password for unauthorized purposes. They also need to trust that you are storing their password securely.
Using OAuth 2.0 eliminates this problem, because when they enter their credentials, they are providing them to Google, not your application. The user is informed exactly what your application intends to do with its access, and they have to approve of that access. When they do, Google will provide you with a token which allows you to access their mailbox. Your application will never know the user’s password, and the user can independently revoke your access to their account without requiring them to change their password.
2. Which SocketTools components support OAuth 2.0?
SocketTools provides support for OAuth 2.0 as an authentication method for the following protocols: HTTP, IMAP, POP3 and SMTP. For your application to use OAuth 2.0, you need to use a secure connection (OAuth 2.0 is not supported over standard, non-secure connections) and you must have the bearer token that grants access to the account.
For the .NET classes and ActiveX controls, a new property named BearerToken can be used to specify the bearer (access) token required to access the web service or mail account. Setting this property will automatically change the authentication method to use OAuth 2.0. For the email components, you will also need to set the UserName property to the account name, typically the email address of the user associated with the mail account.
For the native Windows libraries (DLLs), the APIs have been extended to support additional authentication types. For example, the SMTP API has the new SMTP_AUTH_XOAUTH2 constant which you can specify when calling the SmtpAuthenticate function. The HTTP API has a new function called HttpSetBearerToken which allows you to specify the token and the client will automatically use Bearer authorization.
3. Do previous versions of SocketTools support OAuth 2.0?
Support for OAuth 2.0 was added in SocketTools 10 Build 1245 and is included in SocketTools 11. If you have an earlier version of SocketTools, you will need to upgrade to the current version. Please note that standard support is no longer available for SocketTools 10 and there are no plans to backport these changes to previous versions.
4. Does SocketTools support OAuth 1.0a?
OAuth 1.0a is generally considered to be a deprecated protocol. The OAuth 2.0 technical standard encourages developers to stop using OAuth 1.x, and most services today exclusively use OAuth 2.0. There are currently no plans for SocketTools to support OAuth 1.0a.
5. Is OAuth 2.0 required to access some services?
While many services continue to support both password authorization and OAuth 2.0, some providers have explicitly stated they consider this to be a transition period and will eventually only allow access using OAuth 2.0. Microsoft announced they will be requiring OAuth 2.0 to access commercial Microsoft 365 mail accounts. Google requires the use of OAuth 2.0 to access GSuite accounts, and access to consumer Gmail accounts requires the user to enable “Less Secure Apps” in their settings if OAuth is not used.
Google has announced they will no longer support applications which use a username and password to access an account after May 30, 2022. In their documentation, a "less secure app" is one that uses a password, and a "more secure app" is one that uses an OAuth 2.0 bearer token. You can read their announcement at https://support.google.com/accounts/answer/6010255. To access a Gmail account using SocketTools, you will either need to implement support for OAuth 2.0, or you will need to enable two-factor authentication (2FA) for the account and create an app password.
6. What are the client ID and client secret?
When you register your application with the service provider (e.g.: Google or Microsoft), they will issue a client ID, which is the public identifier for your application. The format for these IDs are specific to the provider and will typically be a string of random letters and numbers. Google uses a format which looks like a fully qualified domain name and Microsoft uses UUIDs for their client IDs.
The client secret is a randomly generated string which is only known to your application and the authorization server. You can think of it as being similar to a password, and it should be handled in the same way. A client secret is not required by Microsoft for desktop applications and they will not issue one when you register your application. Google does require you to provide the client secret when requesting the bearer and refresh tokens, but it is not required when refreshing a bearer token.
You should not store the client secret as plaintext in a configuration file or embedded within the application. Instead, you should store it in an encrypted format. You can use the SocketTools FileEncoder component or API to encrypt the client secret using AES-256.
7. What is a bearer token??
A bearer token, also called an access token, is typically a long string of numbers, letters and symbols which is created by the service (e.g.: Microsoft or Google), associated with the user’s account and used by your application to access that service. These tokens are considered opaque, which means they contain no human readable information and do not contain any sensitive data associated with the user.
The standard does not define a maximum length for these tokens, but generally they can be anywhere from several hundred characters long, to over a thousand characters in length. For example, the bearer tokens used by Google are about 170 characters. The tokens used by Microsoft are encoded JSON web tokens and can be as large as 1,600 characters. The format and length of these tokens can change, so your application should not attempt to discern what type of token it is, or who it was issued by, based on its length or contents.
8. What is a refresh token?
A refresh token is a special token which is issued along with the initial request for the bearer token, when the user first authorizes your application to have access to their account. Because bearer tokens are short lived, it would be burdensome to require the user provide their credentials and re-authorize access to their account.
A refresh token enables your application to request a new bearer token and does not require additional authorization from, or interaction with, the user. Refresh tokens have a much longer validity period, and some services allow the same refresh token to be used indefinitely as long as it is being used regularly. Refresh tokens can be invalidated if they haven't been used for an extended period of time (typically months), or if the user revokes your application's access to their account.
The specifics for requesting a new bearer token using the refresh token is individual to each provider, but they all use a similar request in the form of a secure HTTP POST to their service.
9. What are OAuth 2.0 permission scopes?
Scopes are the mechanism by which a service can limit access to a specific resource. When you initially request authorization to access the user’s account, you must specify the scope of that access. In other words, how much of that user’s information do you need access to. These scopes are specific to the service being used.
A scope can be defined in any way, but conventionally they are URIs related to the service. Multiple scopes can be requested, with each scope separated by a space. When your application requests a bearer token for those scopes, that informs the user what information you want access to. For example, if you request access to use SMTP, the user will be prompted to confirm they wish to allow your application to send emails on their behalf.
Check the service provider’s OAuth 2.0 technical documentation for the list of available scopes for the service you wish to access, such as Gmail and Outlook.
An important consideration when using Gmail is that in most cases you will need to use the https://mail.google.com/ scope, which is the most expansive scope available and allows full access to the user’s mailbox. This is required for IMAP and SMTP access to the Gmail account.
Google does permit the https://www.googleapis.com/auth/gmail.readonly scope for read-only access to the mailbox using POP3, however you will be unable to delete messages. You cannot use the https://www.googleapis.com/auth/gmail.send scope to send email using SMTP. That scope is only valid for the Gmail web API.
For Outlook accounts, you should always include the scope offline_access which tells their service to provide your application with a refresh token.
10. What should I use as the redirect URL?
Part of the OAuth 2.0 authorization grant process on mobile and desktop systems requires you to specify a redirect URL. After the user authorizes your application to access their account, the browser will redirect the user back to the application with an authorization code as part of the URL. This code is subsequently used to request the bearer and refresh tokens. The authorization code contains sensitive information and is only valid for a brief period of time, so it should be used immediately and never stored by your application.
For desktop applications, we recommend you always use a URL which redirects the browser back to the local system using the loopback IP address. It would generally look like this:
http://127.0.0.1/myAppName/
Whatever specific URL you choose, you must use the same URL with the initial request for authorization and the request for the bearer token. It is recommended you use the IP address 127.0.0.1 and not the name localhost to avoid potential problems with misconfigured firewalls. The resource portion of the URL (which is myAppName in the above example) is something entirely defined by you. It must be a valid resource path, and we recommend you keep it as short and simple as possible, only using letters and numbers.
The path you specify in the redirect URL must be unique for every application you register with Microsoft. Once you have used myAppName in a redirect URL, you cannot use it for any other application. If you attempt to use the same redirect URL for another application, you'll get an error during the application registration process.
You can use the SocketTools HttpServer component or API to create a lightweight webserver which can listen for this redirect and capture the authorization code. Because you are only listening for a redirect on the local desktop system, there is no security risk to using a standard connection. If you are concerned there may be another application running that is already using port 80 on the local system, you can specify an alternate port number. For example, consider this redirect URL:
http://127.0.0.1:25895/myAppName/
This would require you have the server listening for HTTP connections on port 25895 instead of port 80. One important thing to keep in mind is you should never use the port number alone to distinguish between redirect URLs. For example:
http://127.0.0.1/myAppName/
http://127.0.0.1:25895/myAppName/
Those look like different redirect URLs because different ports are being used (port 80 in the first, port 25895 in the second). However, when it comes to matching those redirect URLs, they'll be considered the same because the only difference between them is the port number. You can use whatever valid port number you wish, but the resource paths should always be unique.
11. How do I obtain the bearer and refresh tokens?
There are several steps required to obtain the bearer and refresh tokens. These are required to access the user’s account, and the specific process is unique for each service provider. An overview of the general process for Google and Microsoft is outlined below, with links to relevant documentation on their websites.
First, you need to have an account with the service provider and request a client ID. For Gmail, this means using their API console, creating a new project and OAuth credentials. The individual steps you need to take are outlined on Google's website.
Configuring OAuth 2.0 with Google
You also need to enable the Gmail API for your project using their console. You will not be able to use the email related protocols if this is not enabled for the new project you’ve created.
For Outlook, the process begins by creating a Microsoft Azure account if necessary, registering your application with Azure Active Directory and then configuring your application. The steps you need to take are outlined in their Exchange server documentation.
Configuring OAuth 2.0 with Microsoft
After you’ve obtained your client ID (and in the case of Google, your client secret), you can use this to request authorization from the user. This is a secure HTTP request using GET, which provides the client ID, secret, and permission scopes as query parameters.
This query is the interactive part of requesting the bearer token. The user is presented with a form in their web browser, asking them to login to the service (Google or Microsoft in these examples). And then they are asked if they want to grant permission for your application to access their account. The URLs are different for each provider, and their technical documentation will detail what they are, and what query parameters are required.
Because your project hasn't been verified yet, the user will be warned that an unverified application is requesting access to their account. This is fine for testing purposes and when the application is only going to be used internally. However, for applications which are going to be used by the public, you will need to go through the verification process to prevent this warning from being displayed.
If the user accepts your application's request to authorize access, the service will respond with an authorization code. With that code, you send a request for the bearer and refresh tokens in a secure HTTP POST. The bearer token will be valid for a short period of time. The refresh token can be used to obtain a new bearer token without requiring the user go through the interactive authorization steps again.
You can use the SocketTools HTTP component to issue these requests, or you can do this manually using a tool like Postman, which will allow you to create and store the HTTP queries to the service provider.
We also have more detailed Quick Start guides available for Google and Microsoft which can help you register an application and get a better understanding of how the authorization process works.
12. Are there limits on how many tokens I can request?
Each service provider implements their own limitations on how their OAuth 2.0 service can be used. The limits placed on an application can also depend on whether it has been verified or not. These limits can apply to the rate at which your application can request authorization from a user and how frequently a refresh token may be used to obtain a new bearer token.
13. Should I store the bearer tokens?
Your application should not store the bearer token. These tokens are short lived and are typically only valid for a period of about an hour. They are designed to be used during the client session and then discarded.
You should store the refresh token. This is the token which will allow you to request a new bearer token, and they have a much longer validity period. In some cases, refresh tokens are valid indefinitely, if they continue to be used to request new bearer tokens. When a refresh token stops being used, it will eventually become invalid and you must go through the complete authorization process again.
14. Can I manually refresh bearer tokens?
You can perform the steps to refresh a bearer token manually using a tool like Postman, which enables you to compose HTTP queries and submit them. This can be useful for testing outside of your application to ensure the values are correct and accepted by the service. Google also allows you to verify a token is valid, however Microsoft does not.
For example, this is how you could setup Postman to refresh an OAuth 2.0 bearer token for Gmail. It uses a POST to https://accounts.google.com/o/oauth2/token and has four values which need to be specified: client_id, client_secret, refresh_token and grant_type.
The client ID and secret are the values that you obtained when you setup OAuth 2.0 and registered your application with Google. The refresh token is the token you obtained when you initially got authorization from the user which granted your application access to their account. And the grant type is refresh_token, telling Google that you want a new bearer token.
Eventually, you will want to perform this particular task within your application, which you can do using the SocketTools HTTP component. However, being able to perform these operations outside of your application can be useful for testing and debugging, and to get a sense of how the OAuth 2.0 grant flow works in practical terms.
15. What happens if a bearer token cannot be refreshed?
There are two general cases in which a bearer token cannot be refreshed. The first case is if it has been too long since the refresh token was last used. Refresh tokens are typically valid for a long period of time, but if they are not used, they will eventually expire. The exact amount of time depends on the service, but this is usually somewhere between one and three months of inactivity.
The second case is if the user has revoked access to your application. With OAuth 2.0, users have independent control over whether any application using OAuth can continue to access their account (in the case of Gmail, this means access to their mailbox). If they revoke this access, your request to refresh the bearer token will fail and you will have to go through the entire authorization process again. This would be like the user changing their account password.
16. Can I use the same token to access different services?
Bearer tokens are unique to each service, are limited by their scope and cannot be used interchangeably. For example, a bearer token for access to a user’s Gmail account will only work with Gmail and cannot be used with Outlook.
If the user has both a Gmail and Outlook account, and your application needs to use both services, then you must go through the process of creating projects for both services, registering your application with both services and requesting access for each individually.
17. What changes need to be made to support OAuth 2.0??
Applications which need to use OAuth must make several key changes, aside from the initial steps of registering your application and obtaining the client ID. If it is an interactive application, then you need to implement the code which requests the tokens and presents the user with the login form. If this is an application which works in the background and does not have a user interface, then you will need to manually obtain the initial bearer and refresh tokens.
Once you have the bearer token, you can use it with the SocketTools components by calling the appropriate authentication function if you are using the native libraries, or by setting the BearerToken property if you are using the .NET classes or ActiveX controls.
The other important step your application will need to perform is to refresh the bearer token after it expires. The exact URLs and values depend on the service being used, so you will need to consult their technical documentation to determine what those are. You can use the HTTP component to issue the POST request and the server will return a JSON result that contains the new bearer token you can use.
Your application should never store the bearer token in the registry, database or a configuration file. It has a short lifespan and cannot be used after it expires. However, you should store the refresh token which you will need to obtain a new bearer token the next time your application needs to access the user’s account. Keep in mind these tokens can be large, much larger than your typical password. If you are storing the refresh token in a database, make sure the field is large enough to contain it and you should store it in an encrypted format, just as you would the user’s password.
18. Can I use an embedded browser for authorization?
When you begin the process of requesting authorization, the user needs to login to the service provider and grant you permission to access their account. The type of access you have is defined by the permission scope(s) you've requested. If your application wants to access a user's Gmail account, they will need to login to Google. If you want to access their Outlook account, they will need to login to Microsoft.
The user login process occurs in a browser and you may wish to use an embedded browser within your application, rather than using the default browser for the user. For example, you could use the WebBrowser or WebView controls in .NET, the WebBrowser ActiveX control in Visual Basic 6.0, or the IWebBrowser2 interface to the Internet Explorer control.
One important consideration when using the WebBrowser control, or any component based on the Internet Explorer Trident engine, is that it will not work correctly with Google. At this time there is no problem using the WebBrowser control to login to a Microsoft account, but you'll get JavaScript errors if you attempt to login to a Google account. Google no longer supports Internet Explorer, so you'll either need to use an external browser (e.g.: Edge, Chrome or Firefox) or you'll need to use a different control.
One alternative for an embedded browser is the WebKitX ActiveX control. For .NET, another option would be the GeckoFX control, which is based on the engine used by Firefox. They can be used to display the login form, and the SocketTools HttpServer component can be used to listen for the connection back to your application with the authorization code.
If you have a Windows Forms project written in C# or Visual Basic and don't want to use the default browser, another alternative is the WebView2 control based on the Chromium version of Microsoft Edge. The older WebView control was based on the original version of Edge which required Windows 10. It is recommended that new applications use the WebView2 component and applications already using the WebView control should upgrade to using WebView2 when possible.
An advantage of using the WebView2 browser control is your application can handle internal navigation requests to check for the redirect URL and obtain the authorization code without needing a server component to listen for the connection. When you are notified it wants to navigate to the local host, you simply extract the code from the URL and cancel the navigation.
Although it can be convenient for your application to host its own browser, there are advantages to launching the user's default browser. They will be using their browser of preference, and users who are already signed in to Google or Microsoft will find it easier to sign in with your application. If you want to use their default browser, you'll need to use the SocketTools HttpServer component to listen for the connection and capture the authorization code when the browser redirects back to your application.
19. What is the difference between XOAUTH2 and OAUTHBEARER?
These are two similar methods for presenting an OAuth 2.0 bearer token to a service for authentication. They are used with the mail protocols and which method should be selected depends on the service provider. While both methods use the same bearer token provided by the service, the way the token is submitted to the server for authentication is different.
The XOAUTH2 method was the original extension created to support OAuth 2.0. The bearer token is combined with the username (typically the email address) and submitted to the server using an extension to the Simple Authentication and Security Layer (SASL) AUTH command.
The OAUTHBEARER method is the current standard, defined in RFC 7628. However, not all mail servers currently support OAUTHBEARER. Because XOAUTH2 was the first (unofficial) extension developed to support OAuth 2.0 bearer tokens, it remains in wide use.
Generally speaking, we recommend using XOAUTH2 for now. In our experience, if a server supports OAUTHBEARER, it will also support XOAUTH2. However, not all servers which support XOAUTH2 currently support the OAUTHBEARER standard.
20. Do I need to register my application with the service provider?
Yes, you will need to register your application with each service provider your application supports. If you want to allow users to access their Gmail accounts using OAuth 2.0, you will need to register your application with Google. If you want to allow users to access their Outlook 365 account, you will need to register your application with Microsoft. The registration process is how you obtain your client ID, which is required to begin the process of acquiring the bearer tokens used to access those accounts.
Registering your Application with Google
Registering your Application with Microsoft
21. Do I need to have my application verified?
It is not necessary to verify an application which is used internally or during the development and testing period. However, unverified applications will present a warning to the user and they will typically have to take several explicit steps indicating they are aware it is unverified and may present a security risk.
Applications which are being released to the public will need to go through the verification process. The details of verification depend on the scope of access your application is requesting and what services are being used.
Google OAuth Verification FAQ
Microsoft Publisher Verification
22. Are there any special considerations for end users?
The authorization process is designed to be fairly seamless for end users and from their perspective what will be new is logging into the service provider using a web browser, rather than just entering their username and password in your application. We recommend you explain these key points:
- The login form being shown is for the service provider (e.g.: Microsoft or Google) and when they enter their account information, you will not have access to their password. The form is opened in a browser window which always uses a secure connection and their credentials are encrypted. If your application currently stores their username and password, one approach would be to give the user the option to switch to using OAuth 2.0 and then store the refresh token in lieu of their password. Keep in mind the refresh tokens can be much larger than your typical password, so make sure you're allocating enough space to store the entire token.
- They will be asked to confirm your application has permission to access their account. It's recommended you include a screenshot of the confirmation process in your documentation so they know exactly what to expect. If your application has not been verified yet, they will also get a warning message and will be required to confirm they wish to allow access by an unverified application. You should explain what this means so it's clear why they are getting that warning. They will also get email notifications from the service provider when your application has gained access to their account, and they will be given instructions on how they can revoke that access.
- If their account uses two-factor authentication they will need their authentication device, which is typically their smartphone. As part of the initial login process, after they enter their account username and password, they will be prompted to enter the authentication code provided by their device. This can be the form of a text message with a numeric code or some other confirmation mechanism. If they are unable to complete the login process, the authorization attempt will fail.
23. Can you help us get started with OAuth 2.0?
We have two Quick Start guides available as PDF documents which provide step-by-step instructions for registering an application with Google and Microsoft. The guides also demonstrate how to use the Postman utility to submit queries to their servers to obtain authorization codes, bearer tokens and refresh tokens. You can download and view them here:
Google OAuth 2.0 Quick Start Guide
Microsoft OAuth 2.0 Quick Start Guide
You will need a PDF reader to view and print these Quick Start guides. Most modern browsers support viewing PDFs so it is likely they will simply open in a new browser window.