Skip to content

Commit

Permalink
updating keyring_type docs (#38)
Browse files Browse the repository at this point in the history 
* update keyring type

* update

* updated with comments

* nit

* nit

* updated

* fix styling

* format

* Update keyrings.mdx

---------

Co-authored-by: Karuna Tata <[email protected]>
  • Loading branch information
@SathishKumarHS @starlightknown
SathishKumarHS and starlightknown authored May 2, 2024
1 parent 1be7aec commit 4953b37
Showing 1 changed file with 177 additions and 135 deletions.
312 changes: 177 additions & 135 deletions fern/docs/pages/references/keyrings.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
Keyrings are a DevRev-specific mechanism for managing authentication with external services. Keyrings are called **Connections** in the DevRev app.

Keyrings provide 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.
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.

Keyrings are defined in the snap-in manifest under the `keyrings` section. They can be categorized into two main types:
For more information, refer to [Keyrings](/snapin-development/references/manifest#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.
- **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.

<Callout intent="note">
During installation, the user will be prompted to provide credentials for each keyring.
Expand Down Expand Up @@ -39,7 +39,7 @@ Breakdown:
- **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.
All user-scoped keyrings are optional in the snap-in, and developers must handle the case where a user-scoped keyring isn't found.
<Callout intent="note">
If you are using version 1 of the manifest, you can omit the organization key in the keyring definition and directly provide the keyring definition as a list. All keyring defined in manifest version 1 are organization-scoped.
Expand All @@ -48,12 +48,12 @@ Additionally, the keyword `connections` is used instead of `keyrings` in manifes

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

```yaml
developer_keyrings:
- name: my-secret-developer
description: A secret for the developer to use during development
display_name: Developer secret token
```
```yaml
developer_keyrings:
- name: my-secret-developer
description: A secret for the developer to use during development
display_name: Developer secret token
```
Breakdown:

- **name**: A unique identifier for the keyring in the snap-in.
Expand All @@ -62,38 +62,45 @@ Breakdown:

- **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.

```text
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.

```text
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.

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

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

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

```text
scopes: repo admin:repo_hook admin:org notifications user write:discussion
```
- **devrev-zendesk-oauth**: Facilitates OAuth connections for integrating with Microsoft.

```text
scopes: read tickets:write
```

Manifest Declaration:

```yaml
keyrings:
organization:
Expand All @@ -109,135 +116,170 @@ While DevRev offers pre-defined keyring types for common services, you can lever
- devrev-google-calendar-oauth
display_name: Your secret token
```

### Reuse pre-defined keyring types:
While DevRev offers pre-defined keyring types for common services, these types provide further customization options for specific use cases. This section explores how you can leverage these predefined types and tailor them to your needs:

- **Client credentials**: These are credentials associated with your application, typically obtained from the service provider's developer console.
- **Scopes**: These define the specific permissions your application requests from the service.

1. Creating a developer keyring

- 1.1 **CLI command**:
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`:

```yaml
developer_keyrings:
- name: custom-oauth-credentials
description: A secret for the developer to use during development
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.

```bash
echo $CLIENT_CREDENTIALS | devrev keyring create `oauth-secret`
```
Replace `$CLIENT_CREDENTIALS` with your actual OAuth client credentials.

- 1.2 **Manifest declaration**:
```yaml
developer_keyrings:
- name: my-oauth-secret
description: A secret for the developer to use during development
display_name: Developer secret token
echo $CLIENT_CREDENTIALS | devrev developer_keyring create oauth-secret <name of the keyring>
```
2. Customize predefined keyring type in manifest
``` yaml
keyring_types:
- id: reference-oauth-example-connection
name: Example OAuth Connection
description: A custom keyring type for Example OAuth connections.
kind: OAuth2
scopes:
- name: read
description: Read access to Example resources
value: read
- name: write
description: Write access to Example resources
value: write
is_optional: true
oauth_secret: my-oauth-secret
reference_keyring: devrev-example-oauth
```
**Breakdown** :
- **id**: A unique identifier for your custom type.
- **name**: A human-readable name for users.
- **description**: A clear explanation of the type's purpose.
- **kind**: Specifies the authentication method (here, OAuth2). Currently, only OAuth2 is supported.
- **scopes**: Adjust scopes as needed based on your requirements.
- **oauth_secret**: References the developer keyring where your credentials are stored.
- **reference_keyring**: Utilizes pre-defined Example OAuth logic for handling the OAuth flow.

3. Keyring usage in manifest

<Callout intent="note">
The keyring will be passed while `snap_in_version` is being created.
</Callout>

Keyring usage in manifest:

```yaml
keyrings:
organization:
- name: my-secret-org-token
description: Enables access to organization-wide resources (e.g., Slack workspace)
types:
- reference-oauth-example-connection
display_name: Organization secret token
keyrings:
organization:
- name: example connection
description: Enables access to organization-wide resources (e.g., Slack workspace)
types:
- custom-example-connection
display_name: Organization secret token
user:
- name: example connection
description: Enables access to organization-wide resources (e.g., Slack workspace)
types:
- custom-example-connection
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.

```yaml
keyring_types:
- id: custom-example-connection
name: Example OAuth Connection
description: A custom keyring type for Example OAuth connections.
kind: OAuth2
oauth_secret: custom-oauth-credentials # Developer keyring that contains OAuth2 client ID and client secret. Shall be of keyring type `oauth-secret`.
reference_keyring: devrev-example-oauth # Predefined keyring type to be used as a reference for the custom keyring type
scopes:
- name: read
description: Read access to Example resources
value: read
- name: write
description: Write access to Example resources
value: write
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.
```yaml
keyring_types:
- id: custom-example-connection // Unique identifier for your custom type, used in the `keyring` section of the manifest.
name: "Example Connection"
description: "Example connection"
kind: "Oauth2"
scopes: # Configuration for the scopes required by the external service for authorization
- name: "read"
description: "Read access to Example resources"
value: "read"
- name: "write"
description: "Write access to Example resources"
value: "write"
is_optional: true
scope_delimiter: "," # Delimiter used to separate scopes in the authorization request
oauth_secret: custom-oauth-credentials # Developer keyring that contains OAuth2 client ID and client secret. Shall be of keyring type `oauth-secret`.
authorize: # Configuration for the authorization request
type: "config"
grant_type: "authorization_code"
auth_url: "https://example.com/oauth/authorize"
token_url: "https://example.com/oauth/token"
organization_data: # Configuration for fetching organization data
type: "config"
url: "https://example.com/oauth/organization"
method: "POST"
headers:
"Content-type": "application/x-www-form-urlencoded"
"Authorization": "Bearer [ACCESS_TOKEN]"
response_jq: "{id:.team_id, name:.team}"
refresh: # Configuration for the refresh token request
type: "config"
url: "https://example.com/oauth/token"
method: "POST"
revoke: # Configuration for the token revocation of the token
type: "config"
url: "https://example.com/oauth/revoke"
method: "GET"
headers:
"Content-type": "application/x-www-form-urlencoded"
"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:
### Custom keyring type definition:
```yaml
keyring_types:
- id: custom-example-connection
name: Basic Auth Connection
description: A custom keyring type for Basic Auth connections.
kind: secret
secret_config: # Configuration for the secret fields required for Basic Auth
- secret_transform: .token | base64 # Base64 encoding for the token
fields:
- id: token
name: token
description: Token for Basic Auth
token_verfication: # Configuration for verifying the token given by the user
- url: "https://example.com/verify"
method: "POST"
headers:
"Content-type": "application/x-www-form-urlencoded"
"Authorization": "Bearer [API_KEY]"
```
This document details the complete configuration of a custom keyring type for establishing secure OAuth connections within your DevRev snap-in.
In this example, we'll create a custom keyring type for an OAuth2 connection.
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:
```yaml
```yaml
keyring_types:
- id: "custom-oauth-example-connection" // Unique identifier for your custom type, used in the `keyring` section of the manifest.
name: "Example Connection"
description: "Example connection"
kind: "Oauth2"
scopes:
- name: "read"
description: "Read access to Example resources"
value: "read"
- name: "write"
description: "Write access to Example resources"
value: "write"
is_optional: true
oauth_secret: "example-oauth-secret" // Developer keyring reference
authorize:
type: "config"
auth_url: "https://example.com/oauth/authorize"
token_url: "https://example.com/oauth/token"
grant_type: "authorization_code"
organization_data:
type: "config"
url: "https://example.com/oauth/organization"
method: "POST"
headers:
"Content-type": "application/x-www-form-urlencoded"
"Authorization": "Bearer [ACCESS_TOKEN]"
response_jq: "{id:.team_id, name:.team}"
refresh:
type: "config"
url: "https://example.com/oauth/token"
method: "POST"
revoke:
type: "config"
url: "https://example.com/oauth/revoke"
method: "GET"
headers:
"Content-type": "application/x-www-form-urlencoded"
"Authorization": "Bearer [ACCESS_TOKEN]"
```
- id: custom-example-connection
name: Multi-field Connection
description: A custom keyring type for connections with multiple fields.
kind: secret
secret_config: # Configuration for the secret fields required for the connection
fields:
- id: token
name: token
description: Token for connection
- id: username
name: username
description: Username for connection
- id: password
name: password
description: Password for connection
```
<Callout intent="note">
Breakdown:
**Supported keywords in keyring_type configuration**:
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.
</Callout>
- **id**: A unique identifier for your custom type.
- **name**: User-friendly name displayed in the manifest.
- **description**: Clear explanation of the type's purpose.
- **kind**: Specifies the authentication method (OAuth2).
- **scopes**: Permissions requested from Example (adjust based on your needs).
- **oauth_secret**: References the developer keyring containing your credentials.
Additional configuration:
- **authorize**: Defines the OAuth authorization flow.
- **type**: Set to "config" as configuration details are provided. Currently, only "config" is supported.
- **auth_url**: URL for user authorization.
- **token_url**: URL to obtain access and refresh tokens.
- **grant_type**: Grant type used in the authorization request. Currently, only "authorization_code" is supported.
- **organization_data**: Retrieves organization information after successful authorization.
- **refresh**: Defines how to refresh access tokens when they expire.
- **revoke**: Defines how to revoke access tokens when necessary.
- **url**: Endpoint for fetching organization data.
- **method**: HTTP method for the request.
- **headers**: Required headers for the request.
- **query_parameters**: Optional query parameters for the request.
- **response_jq**: JQ expression to extract relevant data from the response.
For examples of how to use keyrings in your snap-in, refer to the [Keyring API documentation](https://github.com/devrev/snap-in-examples/tree/main/13-keyring-type).

0 comments on commit 4953b37

Please sign in to comment.