OAuth 2.0 configuration: Securely storing access tokens

OAuth 2.0 (Open Authorization) is a widely adopted standard for authorization that allows users to grant access to their accounts on one service (like Google or GitHub) to another application (like your DevRev snap-in) without needing to share their passwords directly. This approach enhances security and user convenience.

For comprehensive information about the OAuth specification, refer to the official documentation: OAuth 2.0.

Using OAuth 2.0 keyrings

  1. Define the keyring: Within your snap-in manifest, define a keyring specifically for OAuth credentials. DevRev offers pre-defined keyring types for popular services like Slack or Jira, simplifying the process.

  2. Provide credentials: During development, you’ll provide your developer keyring of type oauth-secret which contains client ID and client secret for the chosen service within the keyring definition. These credentials are securely stored and not distributed with your published snap-in.

  3. OAuth 2.0 flow: When your snap-in needs to access user data from the external service, it initiates the OAuth flow. This typically involves redirecting the user to the service’s login page and then back to your snap-in after successful authorization.

  4. Access tokens: Upon successful authorization, the service provides your snap-in with an access token. This token is used to access user data on the service’s behalf without requiring the user’s password again.

  5. Refreshing tokens: A key benefit of using keyrings for OAuth is that they can handle refreshing access tokens automatically. Most OAuth implementations issue a refresh token alongside the access token. This refresh token can be used to obtain a new access token before the current one expires. If the token is not provided or is expired, the user will need to re-authorize the connection.

  6. Revoking tokens: For enhanced security, you can also configure your keyring to revoke access tokens when they are no longer needed. This ensures that even if a token is compromised, it can’t be used to access user data.

  7. Organization data: Optionally, you can configure your keyring to fetch additional information about the user’s organization within the service. This can be useful for snap-ins that need to access organization-wide data.

Keywords

The supported keywords that can be dynamically inserted into URLs, headers, and query parameters within your custom keyring type configuration.

  • [ACCESS_TOKEN]: The access token obtained during the OAuth flow.
  • [REFRESH_TOKEN]: The refresh token obtained during the OAuth flow.
  • [CLIENT_ID]: The client ID obtained from the OAuth client credentials.
  • [CLIENT_SECRET]: The client secret obtained from the OAuth client credentials.
  • [SCOPE]: The scope of the OAuth flow.
  • [API_KEY]: The API key obtained from the basic flow.

Syntax

1developer_keyrings:
2  - name: <keyring_name>
3    description: <keyring_description>
4    display_name: <keyring_display_name>
5
6keyrings:
7  organization:
8    - name: <keyring_name>
9      display_name: <keyring_display_name>
10      description: <keyring_description>
11      types:
12        - <id of keyring_type>
13
14keyring_types:
15  - id: <keyring_type_id>
16    name: <keyring_type_name>
17    description: <keyring_type_description>
18    kind: "oauth2"
19    is_subdomain: <true/false> # optional: whether the keyring is a subdomain keyring or not. Default is false. It is used to get the subdomain from the user during creation.
20    scopes: # Scopes that the connection can request, add more scopes if needed for your use case. Each scope should have a name, description and value.
21      - name: <scope_name>
22        description: <scope_description>
23        value: <scope_value>
24      - name: <scope_name>
25        description: <scope_description>
26        value: <scope_value>
27    scope_delimiter: <scope_delimiter> # The delimiter used to separate scopes in the request.
28    oauth_secret: <name of the developer keyring> # developer keyring that contains OAuth2 client ID and client secret. Shall be of type `oauth-secret`.
29    # Authorizing Connection: The authorize section is used to get the authorization code from the user and exchange it for an access token.
30    authorize: # The authorize section is used to get the authorization code from the user and exchange it for an access token.
31      type: "config"
32      auth_url: <auth_url> # The URL to which the user is redirected to authorize the connection.
33      token_url: <token_url> # The URL to which the authorization code is sent to get the access token.
34      grant_type: "authorization_code" 
35      auth_query_parameters:
36        <param_name>: <param_value>
37        ....
38      token_query_parameters:
39        <param_name>: <param_value>
40        ....
41    # Fetching Organization Data: (Optional) This allows you to retrieve additional information about the user's organization within the service.
42    organization_data: # Configuration for fetching organization data
43      type: "config"
44      url: <url> # The URL to which the request is sent to fetch organization data.
45      method: <method> # The HTTP method used to send the request.
46      headers:
47        <header_name>: <header_value>
48      query_parameters:
49        <param_name>: <param_value>
50      response_jq: <jq_filter> # The jq filter used to extract the organization data from the response.
51    # Refreshing Access Token: (Optional) Defines how to automatically obtain a new access token when the current one expires.
52    refresh: # The refresh section is used to refresh the access token using the refresh token.
53      type: "config"
54      url: <refresh_url> # The URL to which the refresh token is sent to get a new access token.
55      method: <refresh_method> # The HTTP method used to send the refresh token.
56      query_parameters:
57        <param_name>: <param_value>
58      headers:
59        <header_name>: <header_value>
60    # Revoking Access Token: (Optional) This allows you to revoke the access token after your snap-in no longer needs it, enhancing security.
61    revoke: # The revoke section is used to revoke the access token.
62      type: "config"
63      url: <revoke_url> # The URL to which the access token is sent to revoke it.
64      method: <revoke_method> # The HTTP method used to send the access token.
65      headers:
66        <header_name>: <header_value>
67      query_parameters:
68        <param_name>: <param_value>

Here, you can refer to the keyring type examples.