Configuring OAuth

This page provides a brief introduction to the OAuth protocol and Atlassian's implementation of this protocol. It also shows you how to use your Atlassian application's 'OAuth Administration' page.

On this page:

Introduction to OAuth

OAuth is a protocol that allows one application to share a finite set of its private resources and data (through gadgets, for example) with another application. These applications could be a Confluence or JIRA site. They could even include a desktop application or a mobile device application, all of which are accessible via a network or the Internet. However, all applications involved must be OAuth-compliant.

Using OAuth, you can access data within an Atlassian application installation externally, via a gadget published on a Confluence site's page, another JIRA site's dashboard, or a website like iGoogle. While some data in an Atlassian application may be accessible anonymously from the external application, other data may be restricted to a specific user account within that Atlassian application's installation. OAuth provides the facility to access this restricted data.

The key security advantage of OAuth is that the Atlassian application's user-restricted resources, can be shared without the application having to hand out user authentication details. Instead, access to these private resources is handled via an 'access token'. Access tokens define what Atlassian application resources (which are typically based on access privileges) can be accessed by another application and the duration of this access. However, access tokens are dissociated from a user's authentication details, since authentication to gain access to these resources is handled separately.

In OAuth terminology, an application that shares its resources is known as a service provider and an application that accesses a service provider's resources is known as a consumer.

The OAuth Protocol Workflow

The OAuth protocol has the following typical workflow:

1. Establish an OAuth relationship between a consumer and a service provider. A relationship is typically 'unidirectional', in which one application is the consumer and the other is the service provider. However, depending on the applications involved, this relationship could be established on either the consumer's or service provider's OAuth configuration areas. This step only needs to be performed once, although it must be conducted so that your consumer and service provider can communicate via OAuth.
2. When the consumer needs to access the service provider's resources, the consumer asks the service provider for a 'request token', which is the initial step in the consumer's request to access the service provider's resources. Like access tokens, request tokens are also dissociated from a user's authentication details.
3. The service provider first validates that this request came from one of its registered consumers (established in step 1), then creates a request token and gives it to the consumer.
4. Once the consumer receives the request token, the consumer asks the user to approve the request token by sending the user to the service provider. If the user is required to log in to the service provider, they will be prompted to do so.
5. The user is then prompted to either approve or deny the consumer's access to the request token.
6. Once the user approves access, the service provider exchanges the consumer's approved request token for an access token.
7. The consumer then uses the access token to access the service provider's permitted resources. The consumer can continue to access the service provider's resources until either the access token expires, or the user revokes the access token on the service provider. If the consumer needs to access the service provider's resources after either of these events occurs, then the OAuth workflow would start again from step 2 (above).
   Access tokens issued by Atlassian applications expire after seven days.

Atlassian applications establish OAuth consumer and service provider relationships (step 1 of the workflow above) via their OAuth Administration page, which is described below. These relationships can be established using two approaches:

1. A service provider application that adds another application as a consumer of its resources — Atlassian applications fit this category and allow other applications to be registered as a consumers of their resources. Hence, if you are the administrator of an 'external' application and wish to access an Atlassian application's resources, you can request the administrator of that Atlassian application to add your external application as a consumer. The administrator of that Atlassian application can do this via the OAuth consumers configuration page.
   The 'external' application can be either an Atlassian or non-Atlassian one.
2. A consumer application that initiates the OAuth relationship with the service provider — Unlike Atlassian's applications, many 3rd-party applications may not provide the ability to add your application (either an Atlassian or non-Atlassian one), as a consumer of their application's resources. Instead, you must obtain a 'consumer key' and 'shared secret' from the service provider, with which you can configure the OAuth relationship with that service provider. If you administer an Atlassian application and want it to consume the resources of such a 3rd-party application, you can establish this relationship via your Atlassian application's OAuth Service Providers configuration page.

Using Your Atlassian Application's OAuth Administration Page

An Atlassian application's OAuth administration page is available from within the application's administration area.