Copilot Extensions - OIDC (#54427)

Co-authored-by: Copilot <[email protected]>
Co-authored-by: Jules <[email protected]>
Co-authored-by: Kevin Heis <[email protected]>

Author: 4 people

content/copilot/building-copilot-extensions/index.md

@@ -13,6 +13,7 @@ children:
   - /building-a-copilot-agent-for-your-copilot-extension
   - /building-a-copilot-skillset-for-your-copilot-extension
   - /creating-a-copilot-extension
+  - /using-oidc-with-github-copilot-extensions
   - /debugging-your-github-copilot-extension
   - /managing-the-availability-of-your-copilot-extension
   - /copilot-extensions-glossary

content/copilot/building-copilot-extensions/using-oidc-with-github-copilot-extensions.md

@@ -0,0 +1,176 @@
+---
+title: Using OIDC with GitHub Copilot Extensions
+intro: >-
+  Learn how to use OpenID Connect (OIDC) with your {% data
+  variables.product.prodname_copilot_extension_short %} to enhance security.
+versions:
+  feature: copilot-extensions
+topics:
+  - Copilot
+shortTitle: Using OIDC
+type: how_to
+redirect_from:
+  - /copilot/building-copilot-extensions/using-oidc-with-copilot-extensions
+---
+
+## About OpenID Connect (OIDC) for {% data variables.product.prodname_copilot_extensions_short %}
+
+OpenID Connect (OIDC) allows {% data variables.product.prodname_copilot_extensions_short %} to exchange short-lived tokens directly from their cloud provider instead of storing long-lived {% data variables.product.github %} credentials. This feature enables both Copilot agents and skillsets to more securely authenticate users and access cloud resources.
+
+## Overview of OIDC
+
+{% data variables.product.prodname_copilot_extensions_short %} often need to access third-party resources or APIs on behalf of users. Traditionally, this required storing {% data variables.product.github %} tokens as secrets and making additional API calls to map these tokens to user identities in your system. With OIDC, your extension can request short-lived access tokens directly from your authentication service by exchanging {% data variables.product.github %} identity information.
+
+When enabled, {% data variables.product.github %}'s OIDC provider automatically generates a token containing claims about the user and the request context. Your authentication service can validate these claims and exchange them for an access token scoped specifically for your service.
+
+Using OIDC is especially valuable for {% data variables.product.prodname_copilot_short %} skillsets development because it allows you to leverage your existing API endpoints without maintaining separate {% data variables.product.github %}-specific endpoints. Instead of duplicating endpoints to accept {% data variables.product.github %} tokens, you can use OIDC to translate {% data variables.product.github %} identities into your service’s native authentication tokens.
+
+## Benefits of using OIDC
+
+By implementing OIDC token exchange in your {% data variables.product.prodname_copilot_extension_short %}, you can:
+
+* Avoid storing long-lived {% data variables.product.github %} tokens or maintain a mapping between {% data variables.product.github %} and your service's identities.
+* Use short-lived tokens that automatically expire and can be scoped specifically to your service's needs.
+* Avoid making additional calls to {% data variables.product.github %}'s API to validate tokens and fetch user information.
+* Enable direct integration for {% data variables.product.prodname_copilot_short %} Skills with your existing APIs without maintaining separate endpoints for {% data variables.product.github %}.
+* Reuse existing API endpoints by translating {% data variables.product.github %} authentication into your service's native tokens.
+
+## Token exchange flow
+
+The following outlines how the {% data variables.product.prodname_copilot_extensibility_platform_short %} exchanges an OIDC token for an access token to authenticate requests to your extension.
+
+### Initial request
+
+1. The user sends a message to your {% data variables.product.prodname_copilot_extension_short %}.
+1. GitHub generates an OIDC token containing user identity information.
+1. GitHub calls your token exchange endpoint with the OIDC token.
+1. Your service validates the token and returns an access token.
+1. GitHub includes your access token in the request to your extension.
+
+```http request
+# HTTP header
+Authorization: Bearer <your-service-token>
+X-GitHub-Token: <github-token>
+```
+
+### Subsequent requests
+
+1. {% data variables.product.github %} caches your access token for up to 10 minutes.
+1. The cached token is reused for subsequent requests.
+1. If the token expires or becomes invalid, {% data variables.product.github %} requests a new one.
+
+## Understanding OIDC tokens
+
+The OIDC token from {% data variables.product.github %} is a JWT containing claims about the user and request context:
+
+```json
+{
+  "jti": "<unique-token-id>",
+  "sub": "<github-user-id>",
+  "aud": "<your-client-id>",
+  "iss": "https://github.com/login/oauth",
+  "nbf": 1632492967,
+  "exp": 1632493867,
+  "iat": 1632493567,
+  "act": {
+    "sub": "api.copilotchat.com"
+  }
+}
+```
+
+## Setting up OIDC for your extension
+
+There are three steps to setting up OIDC for your extension.
+1. [Configure your token exchange endpoint](#configure-your-token-exchange-endpoint).
+1. [Enable OIDC in your Copilot extensions settings](#enable-oidc-in-your-copilot-extensions-settings).
+1. [Validate OIDC tokens](#validate-oidc-tokens).
+
+### Configure your token exchange endpoint
+
+Create an endpoint in your service that conforms to the [RFC 8693 OAuth 2.0 Token Exchange](https://www.rfc-editor.org/rfc/rfc8693.html).
+This endpoint should:
+* Accept `POST` requests with the following form-encoded parameters:
+
+  ```http request
+  grant_type=urn:ietf:params:oauth:grant-type:token-exchange
+  &resource=<https://your-service.com/resource>
+  &subject_token=<github-jwt-token>
+  &subject_token_type=urn:ietf:params:oauth:token-type:id_token
+  ```
+
+* Return a JSON response with your service's access token:
+
+  ```json
+  {
+    "access_token": <"your-service-token">,
+    "Issued_token_type":"urn:ietf:params:oauth:token-type:access_token",
+    "token_type": "Bearer",
+    "expires_in": 3600
+  }
+  ```
+
+* Return an error response when validation fails:
+
+  ```json
+  {
+    "error": "invalid_request"
+  }
+  ```
+
+### Enable OIDC in your {% data variables.product.prodname_copilot_extension_short %}'s settings
+
+In your {% data variables.product.prodname_copilot_extension_short %}'s configuration, enable OIDC:
+
+{% data reusables.apps.settings-step %}
+{% data reusables.apps.enterprise-apps-steps %}
+1. To the right of the {% data variables.product.prodname_github_app %} you want to configure for your {% data variables.product.prodname_copilot_extension_short %}, click **Edit**.
+1. In the left sidebar, click **{% data variables.product.prodname_copilot_short %}**.
+1. Under **OpenID Connect Token Exchange**, check **Enabled**.
+1. In the **Token exchange endpoint** field, input your token exchange URL.
+1. In the **Request header key** field, input the header key for your service's token. The default is `Authorization`.
+1. In the **Request header value** field, input the header value format. The default is `Bearer ${token}`.
+
+### Validate OIDC tokens
+
+Your token exchange endpoint should validate the {% data variables.product.github %} OIDC token by following the steps below:
+1. Fetch the JSON Web Key Set (JWKS) from https://github.com/login/oauth/.well-known/openid-configuration.
+1. Verify  the token signature.
+1. Validate required claims.
+   * `aud`: Audience. Your {% data variables.product.prodname_copilot_extension_short %}'s client ID.
+   * `sub`: Subject. The {% data variables.product.github %} user ID making the request. The response is limited to data that the user has permissions to access. If the user has no permissions `400 Bad Request` is shown.
+   * `iat`: Issued At. The timestamp when the token was issued. It is typically a timestamp in the past but represents the exact moment the token was created.
+   * `nbf`: Not Before. The timestamp before which the token is not valid. This should be a timestamp in the past.
+   * `exp`: Expiration Time. The timestamp when the token expires. This should be a timestamp in the future.
+   * `act`: Actor. The acting entity in delegated access. This should be a constant string.
+
+## Troubleshooting
+
+The following sections outline common problems and best practices for implementing OIDC for your {% data variables.product.prodname_copilot_extension_short %}.
+
+### Token validation errors
+
+* Ensure you're using the correct JWKS endpoint.
+* Verify that all the required claims are present and valid.
+* Check that timestamps (`iat`, `nbf`, and `exp`) are within valid ranges.
+
+### Token exchange failures
+
+* Return `HTTP 400` for invalid tokens.
+* Return `HTTP 403` if the user lacks the necessary permissions.
+* If {% data variables.product.github %} receives a 403 response, it will retry the request with a new token.
+
+### Performance issues
+
+* Implement efficient token validation to minimize latency.
+* Use appropriate token expiration times (recommended: 10 minutes or less).
+* Consider caching implications for high-traffic extensions.
+
+### Best practices
+
+* Scope tokens to the minimum required permissions.
+* Implement proper error handling and logging.
+* Monitor token exchange patterns for security anomalies.
+* Keep tokens short-lived to minimize security risks.
+* Validate all claims before issuing access tokens.
+* Consider implementing rate limiting on your token exchange endpoint.
+* Use HTTPS for all token exchange communications.