As the name suggests this mechanism uses the basic technique to authenticate users. A user communicates with a web server by sending a request with a set of credentials. It requires your users to provide their actual username and password, it is not the recommended method of authorization. To study about Basic authentication type and how it works, read our guide.

We support Basic authorization type and two of its variations which are Basic with API-Key and Basic with URL. These types come under the same umbrella. Basic with URL requires user credentials along with a custom authorization URL whereas Basic with API-Key requires user credentials, API-Key, and a custom authorization URL at the time of user authentication. 

Using Basic authorization

This is a step-by-step guide on how to create Basic auth types through Integry. When you create your app, Integry configures API-Key by default with your app. If you want to create another auth type, you can delete this one. The authorization is created under the Authorizations tab in your app menu. Authorizations display all authorization types configured with your app. So let’s walk through the entire authorization creation process. 

Click the Create Authorization button. A drop-down menu will appear as shown below. The procedure is the same for these auth types. Select  Basic, Basic with URL or Basic with API-Key authorization type from the list.

Once you select the authorization type, additional fields will appear below. In case of Basic authorization type we need to configure two endpoints which are as follows:

User Information Endpoint: The endpoint that returns the details of the logged in user like username, first name, last name etc. This information is shown next to the authentication. To create a new user information endpoint select Create a new endpoint option from the drop-down menu. Read, how to create a new user information endpoint.

Token Endpoint:  The endpoint that requests the access token and optionally a refresh token. To create a new token endpoint select Create a new endpoint option from the drop-down menu. Read, how to create a new token endpoint. 

In the case of Basic with URL, you need to configure the User Information Endpoint only.

Once these endpoints are configured, click the Create Authorization button and the authorization will be created. 

How are they different?

When you create an app that uses Basic with URL/API-Key every user of that app is assigned a unique URL where they can access the app. When you create actions or triggers, you need to provide this URL that changes for every user. Let us take the example of an app that uses Basic with URL, JIRA.

We want to an action Create an Issue in JIRA. We need to execute the endpoint that will create an issue in JIRA on Integry’s behalf. The URL for the endpoint is different for every user in this case. Before we do that just a few things.

How to access the Custom Authorization URL

When an app uses Basic with URL/API-Key authorization, the custom URL entered by the user when they authenticate is available to your actions/triggers endpoints like authorization.token.extras.base_uri. This is a standard Integry syntax. We use Twig templating language and provides the value of the URL as a JSON object. It is available for all apps using Basic with URL/API-Key. As we want to create an issue and from the documentation, we know we need to provide the custom user URL. So our action endpoint URL will be 

POST {{authorization.token.extras.base_uri | raw}}/rest/api/2/issue/

“{{ }}” means that the value inside the authorization.token.extras.base_uri is outputted here. The rest of the URL part is appended at the end as specified in the documentation. 

| raw is a filter applied to the URL. We want to get the raw value of the URL, so we apply this filter to prevent escaping. 

How to access the Access Token value

When a user provides credentials when authenticating, the credentials are encoded. The encoded credentials are sent along the URL. We call them access token (within the scope of Integry). 

The value of the access token can be retrieved like authorization.token.access_token. This is a standard Integry syntax. It uses Twig templating language and provides the value of the URL as a JSON object. It is available for all apps using Basic or Basic with URL/API-Key. The value of this token can be passed as the header, depending upon the other app’s documentation. 

Authorization Screens

The user can view all integrations available in the Integry widget. When a user creates an integration, they are asked to authorize themselves to the third-party app and add their account as shown below

In the figure above, the user is asked to add the People HR account.

Different apps use different authentication methods. We will discuss three different scenarios where the user authenticates with apps using the following authorization types:

  • Basic
  • Basic with URL
  • Basic with API-Key

Authorizing with Basic

When the user adds an app that uses Basic auth type, they are directed to the authorization screen as shown below

The form shown above takes the name of authorization and user credentials. If your app uses Basic authentication type, your users can copy and paste the credentials here in the Username and Password fields. Once provided, the user is authenticated. 

Authorizing with Basic with URL

When a user adds an app that uses Basic with URL authentication, they are directed to the authorization screen shown below

The form shown above takes the name of authorization, user credentials and, custom authorization URL. If your app uses Basic ith URL authentication type, your users can copy and paste the credentials and the URL here in the fields above. Once provided, the user is authenticated.

Authorizing with Basic with API-Key

When a user adds an app that uses Basic with API-Key, they are directed to the authorization screen that takes user credentials, custom authorization URL and value of API-Key. If your app uses Basic with URL your users can provide with the information required and authenticate themselves and Integry. 

Did this answer your question?