Keyrings

Keyrings are a DevRev-specific mechanism for managing authentication with external services. Keyrings are called Connections in the DevRev app.

Keyrings provides a secure way to store and manage credentials for external services within your DevRev snap-in. This eliminates the need to expose sensitive information like passwords or access tokens directly within your code or configuration files, enhancing overall security.

For more information, refer to Keyrings in the snap-in manifest. They can be categorized into two main types:

1. Default keyrings:

• Organization scoped keyrings: These are secrets used by the entire organization, for example, a Slack token for a workspace.
• User scoped keyrings: These are secrets for a single user, for example, the token to interact with a single person’s Google Calendar.

1
keyrings:
2
  organization:
3
    - name: my-secret-org-token
4
      description: Enables access to organization-wide resources (e.g., Slack workspace)
5
      types:
6
        - devrev-keyring-type
7
      display_name: Organization secret token
8
9
  user:
10
    - name: my-secret-user-token
11
      description: Allows access to individual user resources (e.g., personal Google Calendar)
12
      types:
13
        - devrev-keyring-type
14
      display_name: Your secret token

Breakdown:

• name: A unique identifier for the keyring in the snap-in.

• description: A human-readable description of the keyring shown to the user at the time of snap-in installation.

• types: The list of possible keyring types that the user can provide.

• display_name: The name that’s shown to the user when they’re asked to provide a keyring.

All user-scoped keyrings are optional in the snap-in, and developers must handle the case where a user-scoped keyring isn’t found.

2. Developer scoped keyrings: These are secrets accessible and usable only by the developer creating the snap-in, typically used for personal development workflows.

   1
   developer_keyrings:
   2
     - name: my-secret-developer
   3
       description: A secret for the developer to use during development
   4
       display_name: Developer secret token

Breakdown:

• name: A unique identifier for the keyring in the snap-in.

• description: A human-readable description of the keyring shown to the user at the time of snap-in installation.

• display_name: The name that’s shown to the user when they’re asked to provide a keyring.

Enable external service connections with keyring types

While DevRev offers pre-defined keyring types for common services, you can leverage this mechanism further to create custom types for specific service integrations.

Pre-defined keyring types:

• devrev-snap-in-secret: Stores simple string tokens utilized by the snap-in itself.

• devrev-atlassian-jira-oauth: Facilitates OAuth connections for integrating with Jira.

  scopes: offline_access read:me read:application-role:jira read:audit-log:jira read:issue-security-level:jira read:issue-security-scheme:jira read:project-role:jira read:avatar:jira read:project-category:jira read:project:jira read:permission-scheme:jira read:user:jira read:field:jira read:permission:jira read:group:jira read:project.component:jira read:issue-details:jira read:issue-meta:jira read:field-configuration:jira read:attachment:jira read:issue-link-type:jira read:issue-type-hierarchy:jira read:issue-type:jira read:label:jira read:priority:jira read:project.property:jira read:project-version:jira read:resolution:jira read:status:jira read:issue.changelog:jira read:issue:jira read:issue.vote:jira write:jira-work read:jira-work write:issue:jira write:issue.property:jira read:issue.transition:jira manage:jira-project manage:jira-configuration

• devrev-slack-oauth: Facilitates OAuth connections for integrating with Slack.

  scopes: app_mentions:read,channels:history,channels:read,channels:write.invites,channels:manage,chat:write,chat:write.customize,chat:write.public,commands,groups:history,groups:read,im:read,im:write,links:read,links:write,metadata.message:read,mpim:read,mpim:write,team:read,users.profile:read,users:read,users:read.email,im:history,mpim:history,files:read,files:write,pins:read,pins:write

• devrev-google-oauth: Facilitates OAuth connections for integrating with Google.

  scopes: https://www.googleapis.com/auth/gmail.send

• devrev-github-oauth: Facilitates OAuth connections for integrating with GitHub.

  scopes: repo admin:repo_hook admin:org notifications user write:discussion

• devrev-zendesk-oauth: Facilitates OAuth connections for integrating with Microsoft.

  scopes: read tickets:write

  Manifest Declaration:

  1
  keyrings:
  2
      organization:
  3
        - name: my-secret-org-token
  4
          description: Enables access to organization-wide resources (e.g., Slack workspace)
  5
          types:
  6
              - devrev-slack-oauth
  7
          display_name: Organization secret token
  8
      user:
  9
        -  name: my-secret-user-token
  10
           description: Allows access to individual user resources (e.g., personal Google Calendar)
  11
           types:
  12
              - devrev-google-calendar-oauth
  13
           display_name: Your secret token

3. Custom keyring types for OAuth:

   Developer Keyring:

   • The developer_keyrings type allows the creation of keyrings that hold sensitive information like client IDs and client secrets required for OAuth authorization with external services. These keyrings are intended for development environments and should not be used in production due to security concerns. Here’s an example configuration snippet demonstrating a developer_keyring named custom-oauth-credentials:

     1
     developer_keyrings:
     2
       - name: custom-oauth-credentials
     3
         description: A secret for the developer to use during development
     4
         display_name: Developer secret token

   To create a developer keyring, follow these steps:

   • Replace $CLIENT_CREDENTIALS in the following command with your actual OAuth client ID and client secret combined into a JSON string.

   • Execute Command: Run the following command, replacing <name of the keyring> with your desired keyring name.

     $
     echo $CLIENT_CREDENTIALS | devrev developer_keyring create oauth-secret <name of the keyring>

   The keyring will be passed while snap_in_version is being created.

   Keyring usage in manifest:

   1
       keyrings:
   2
           organization:
   3
            - name: example connection
   4
              description: Enables access to organization-wide resources (e.g., Slack workspace)
   5
              types:
   6
                - custom-example-connection
   7
              display_name: Organization secret token
   8
           user:
   9
             - name: example connection
   10
               description: Enables access to organization-wide resources (e.g., Slack workspace)
   11
               types:
   12
                 - custom-example-connection
   13
               display_name: Organization secret token

   3.1. Reusing Predefined keyring_type with Custom Scopes: Here’s an example of a custom keyring type for an existing OAuth2 keyring type while customizing the required scopes for your specific external service.

   1
   keyring_types:
   2
     - id: custom-example-connection
   3
       name: Example OAuth Connection
   4
       description: A custom keyring type for Example OAuth connections.
   5
       kind: OAuth2
   6
       oauth_secret: custom-oauth-credentials # Developer keyring that contains OAuth2 client ID and client secret. Shall be of keyring type `oauth-secret`.
   7
       reference_keyring: devrev-example-oauth # Predefined keyring type to be used as a reference for the custom keyring type
   8
       scopes:
   9
         - name: read
   10
           description: Read access to Example resources
   11
           value: read
   12
         - name: write
   13
           description: Write access to Example resources
   14
           value: write
   15
           is_optional: true

   3.2. Custom keyring type definition: This approach defines a new, entirely custom keyring type with complete control over the OAuth flow configuration.

   1
   keyring_types:
   2
     - id: custom-example-connection // Unique identifier for your custom type, used in the `keyring` section of the manifest.
   3
       name: "Example Connection"
   4
       description: "Example connection"
   5
       kind: "Oauth2"
   6
       scopes: # Configuration for the scopes required by the external service for authorization
   7
         - name: "read"
   8
           description: "Read access to Example resources"
   9
           value: "read"
   10
         - name: "write"
   11
           description: "Write access to Example resources"
   12
           value: "write"
   13
           is_optional: true
   14
       scope_delimiter: "," # Delimiter used to separate scopes in the authorization request
   15
       oauth_secret: custom-oauth-credentials  # Developer keyring that contains OAuth2 client ID and client secret. Shall be of keyring type `oauth-secret`.
   16
       authorize: # Configuration for the authorization request
   17
           type: "config"
   18
           grant_type: "authorization_code"
   19
           auth_url: "https://example.com/oauth/authorize"
   20
           token_url: "https://example.com/oauth/token"
   21
       organization_data: # Configuration for fetching organization data
   22
           type: "config"
   23
           url: "https://example.com/oauth/organization"
   24
           method: "POST"
   25
           headers:
   26
           "Content-type": "application/x-www-form-urlencoded"
   27
           "Authorization": "Bearer [ACCESS_TOKEN]"
   28
           response_jq: "{id:.team_id, name:.team}"
   29
       refresh: # Configuration for the refresh token request
   30
           type: "config"
   31
           url: "https://example.com/oauth/token"
   32
           method: "POST"
   33
       revoke: # Configuration for the token revocation of the token
   34
           type: "config"
   35
           url: "https://example.com/oauth/revoke"
   36
           method: "GET"
   37
           headers:
   38
           "Content-type": "application/x-www-form-urlencoded"
   39
           "Authorization": "Bearer [ACCESS_TOKEN]"

4. Define Basic keyring type: Here’s an example of a custom keyring type for establishing secure Basic Auth connections within your snap-in:

   1
   keyring_types:
   2
     - id: custom-example-connection
   3
       name: Basic Auth Connection
   4
       description: A custom keyring type for Basic Auth connections.
   5
       kind: secret
   6
       secret_config: # Configuration for the secret fields required for Basic Auth
   7
         - secret_transform: .token | base64 # Base64 encoding for the token
   8
           fields:
   9
             - id: token
   10
               name: token
   11
               description: Token for Basic Auth
   12
           token_verfication: # Configuration for verifying the token given by the user
   13
           - url: "https://example.com/verify"
   14
             method: "POST"
   15
             headers:
   16
               "Content-type": "application/x-www-form-urlencoded"
   17
               "Authorization": "Bearer [API_KEY]"

5. Define Multi-filed keyring: Here’s an example of a custom keyring type for establishing secure connections with multiple fields within your snap-in:

   1
   keyring_types:
   2
   - id: custom-example-connection
   3
     name: Multi-field Connection
   4
     description: A custom keyring type for connections with multiple fields.
   5
     kind: secret
   6
     secret_config: # Configuration for the secret fields required for the connection
   7
         fields:
   8
           - id: token
   9
             name: token
   10
             description: Token for connection
   11
           - id: username
   12
             name: username
   13
             description: Username for connection
   14
           - id: password
   15
             name: password
   16
             description: Password for connection

For examples of how to use keyrings in your snap-in, refer to the Keyring API documentation.