How to Authenticate with 0Auth

OAuth 2.0 Implementation Guide

OAuth 2.0 is the industry-standard protocol for authorization. OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for applications such as Ideanote.

Ideanote supports an OAuth 2.0 based Authorization Code Flow. This is the most common of the OAuth 2.0 grant types, and in relation to Ideanote, the flow goes roughly like this:

  1. Ideanote sends your user to a login screen you control (or integrate with), and that the user is already familiar with.
  2. The user enters their credentials and attempts to authenticate.
  3. If the credentials are valid, the user will be redirected back to Ideanote with an authorization code as a query parameter in the URL.
  4. Ideanote then exchanges this authorization code for an access token by communicating with your API.
  5. Using this access token as Authorization, Ideanote fetches some user info from your API, such as email address, id (or sub), avatar, prefered locale, and name.

If you want to dive into this in greater detail, this is a great resource on the topic.

Advantages

  • An easy way to ensure strong authentication.
  • Your users sign in through a system that they already trust, and they never share their credentials directly with Ideanote.
  • As your users authenticate directly through your system (or a system you control), you'll maintain full control over who has access to your Ideanote workspace.
  • OAuth 2.0 is an industry standard that you can use for authenticating with not just Ideanote, but thousands of software solutions.

Prerequisites

You will need to either:

  • Already use a sign-in provider for your own system that has OAuth 2.0 support, such as Okta, Facebook, Google, Github, and many others. Or,
  • Run an OAuth 2 authentication server yourself that conforms to the OAuth 2.0 specification

First Steps

To get started with OAuth 2.0 based authentication, you will need to first consult the documentation of the sign-in provider you use for your system in order to create an OAuth integration or application through their interface. You will need to copy a few things from there into the configuration on your Ideanote Workspace, and vice versa. We'll get to the specifics in a moment.

For your convenience, we've prepared a little list of direct links to the relevant documentation for some popular sign-in providers with OAuth 2.0 support below:

Google

Slack

Discord

Dropbox

Github

Facebook

The way these typically work is some variation of the following: You create an OAuth application or integration. In there, you will see a Client ID and a Client Secret, as well as a list of OAuth scopes it supports. You will also be able to type in one or more Redirect URLs. Finally, you should see a list of relevant API endpoints such as the Authorization Endpoint and Token Endpoint.

These images are examples of OAuth 2.0 integrations. The first one is from Github, and the second one is from Facebook/Meta.

When you have created an OAuth application/integration, or if you host your own OAuth 2.0 authorization server, you're now ready to move on to setting it up on your Ideanote workspace.

Configuring your Ideanote Workspace

To add support for your OAuth 2.0 application/integration on your Ideanote Workspace, first head to the Settings page on your Ideanote Workspace. From here, please follow the steps as seen in Figure 1 and described in greater detail below.

Fig. 1: Security Settings

  1. Click on the Security menu option.
  2. In the list of sign-in options associated with your Workspace, click the Add button. 3. In the list of available options, choose OAuth 2.0.

You will be presented with a dialog window as seen in Figure 2.

Fig. 2: OAuth Settings dialog

  1. In the vertical side navigation, click on Basics.

Basics is where you can control some of the most general settings, as seen in Figure 3. These have helpful descriptions embedded directly below the text fields, but we will expand on them in detail below.

Fig. 3: Basic settings

The text that will be displayed on the sign-in button. Directly below it you can also upload a custom icon that will be displayed next to the text.

  1. Which IP-addresses to allow. For example, you may have one or more static IP-addresses associated with a VPN on which your users must be connected in order to connect to your Workspace.
  2. Which email adresses to allow. For example, you may have a sign-in portal where your users from multiple locations and/work areas sign in, some of which you may not want to grant access to your Ideanote Workspace.

When you are satisfied with the Basic configuration, click on Copy Redirect URL as seen on (4) in Figure 3.

Fig. 4: Copy Redirect URL

Now would be a good time to revisit the high level functionality of an OAuth 2.0 Authorization Code Flow.

When a user signs in via the login screen of your sign-in application, they will be redirected to some URL with an authorization code as a query parameter in the URL. That somewhere needs to be Ideanote's OAuth Redirect URL.

As described in the First Steps section, you will need to copy our Redirect URL that can be seen in (1) in Figure 4 into the OAuth 2.0 configuration of your application/integration.

When you feel confident that our Redirect URL has been added correctly, please click on Add Configuration in the vertical side menu as seen in (2) in Figure 4.

Now would be a good time to revisit the high level functionality of an OAuth 2.0 Authorization Code Flow.

When a user signs in via the login screen of your sign-in application, they will be redirected to some URL with an authorization code as a query parameter in the URL. That somewhere needs to be Ideanote's OAuth Redirect URL.

As described in the First Steps section, you will need to copy our Redirect URL that can be seen in (1) in Figure 4 into the OAuth 2.0 configuration of your application/integration.

When you feel confident that our Redirect URL has been added correctly, please click on Add Configuration in the vertical side menu as seen in (2) in Figure 4.

Add Configuration is where you can paste the relevant information from your OAuth 2 application/integration as described in First Steps. The following list will describe each of the red bubbles from Figure 5 in greater detail:

  1. This is where the Client ID must be entered. This is typically easily found somewhere in your OAuth 2.0 application/integration and is typically called Client ID or App ID.
  2. This is where the Client Secret must be entered. This is typically easily found somewhere in your OAuth 2.0 application/integration and is typically called Client Secret or App Secret. Note: If you're hosting your own OAuth 2.0 authorization server, you must ensure that it is sufficiently random to not be guessable. One way to do so is by using a cryptographically-secure library to generate a 256-bit value and then convert it to a hexadecimal representation.
  3. The Authorization Endpoint is the one Ideanote will send your users to such that they can authenticate with you before being redirected to us with an Authorization Code, - if everything goes well, that is. If you're not hosting your own OAuth 2.0 authorization server, you will be able to find this in the documentation of your OAuth 2.0 application/integration.
  4. The Token Endpoint is the one Ideanote will send the Authorization Code to we received from the Authorization Endpoint with the intent of exchanging it to an Access Token. If we get an access token back, we've successfully authenticated with your application/integration on behalf of the user. We'll use that access token one single time to retrieve some relevant user information, such as their id, email address, name, avatar, and potentially other information granted to us by the OAuth 2.0 scopes you'll enter (See Figure 6).

Fig. 5: Add Configuration (part 2)

This is the second half of the available configuration options in Add Configuration. Like the previous half, the red bubbles will be described in greater detail below:

  1. This is the API-endpoint Ideanote will invoke with the Access Token retrieved from the Token Endpoint as Authorization to retrieve relevant user information. This allows us to retrieve some of the required, as well as optional user information, including the id (or sub) and email address of the user (both of which are required), as well as optional data such as the name, avatar, preferred locale, and preferred alias. This endpoint can be found in the API documentation of your OAuth 2.0 application or integration.
  2. This is where you can enter the OAuth 2.0 scope(s) that should be requested. You must ensure that you enter at least one scope, and that the scope provides Ideanote with the two required data properties, which are email and id (or sub). Please consult the documentation of your OAuth 2.0 application/integration to read about the scopes they support and to ensure that Ideanote will request the correct scopes for getting access to user information, ideally including name and avatar as well.
  3. Ideanote expects the response from the User Info Endpoint you configured to be a JSON object. By default, Ideanote will attempt to parse and map its key-value pairs to user information based on guesses and heuristics. By expanding the USER INFO ATTRIBUTES accordion menu, you can help us out by specifying the exact path into the User Info JSON response we should look up for the individual user info attributes.
  4. When you have filled out all required fields and are satisfied with the configuration, you can click the Save button to save the OAuth 2.0 sign-in provider on your Ideanote workspace. Going forward, your users will see a new sign-in option on the Login page. If configured correctly, clicking it will take them to the login page they already use to sign in to your own system, and upon authenticating successfully, they will be redirected into your Ideanote workspace. Depending on the requested and accepted scopes, as well as what type of data your OAuth application/integration supports, Ideanote will already know some details about the user immediately, such as their name, avatar, preferred locale, and so on.

More information

OAuth 2.0 is a well-documented and popular industry-standard protocol for authorization. As such, there are many great resources available online, including in-depth guides and services that makes it easy to integrate OAuth 2.0-based authentication with your own API.

Here are a few resources we can recommend:

The OAuth 2.0 Authorization Framework

What is the OAuth 2.0 Authorization Code Grant Type?

OAuth 2 Authorization Code Flow Playground

OAuth 2 Simplified

If you have additional questions, feel free to reach out to us at hello@ideanote.io.


How did we do?


Powered by HelpDocs (opens in a new tab)