|
| 1 | +--- |
| 2 | +title: OpenID Connect (OIDC) for Copilot Extensions |
| 3 | +intro: 'Learn how OpenID Connect (OIDC) enables {% data variables.copilot.copilot_extensions_short %} to securely authenticate users and access cloud resources without storing long-lived credentials.' |
| 4 | +versions: |
| 5 | + feature: copilot-extensions |
| 6 | +topics: |
| 7 | + - Copilot |
| 8 | +shortTitle: OpenID Connect |
| 9 | +allowTitleToDifferFromFilename: true |
| 10 | +type: overview |
| 11 | +--- |
| 12 | + |
| 13 | +## About OpenID Connect (OIDC) for {% data variables.copilot.copilot_extensions_short %} |
| 14 | + |
| 15 | +OpenID Connect (OIDC) allows {% data variables.copilot.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. |
| 16 | + |
| 17 | +### Overview of OIDC |
| 18 | + |
| 19 | +{% data variables.copilot.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. |
| 20 | + |
| 21 | +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. |
| 22 | + |
| 23 | +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. |
| 24 | + |
| 25 | +### Benefits of using OIDC |
| 26 | + |
| 27 | +By implementing OIDC token exchange in your {% data variables.copilot.copilot_extension_short %}, you can: |
| 28 | + |
| 29 | +* Avoid storing long-lived {% data variables.product.github %} tokens or maintain a mapping between {% data variables.product.github %} and your service's identities. |
| 30 | +* Use short-lived tokens that automatically expire and can be scoped specifically to your service's needs. |
| 31 | +* Avoid making additional calls to {% data variables.product.github %}'s API to validate tokens and fetch user information. |
| 32 | +* Enable direct integration for {% data variables.product.prodname_copilot_short %} Skills with your existing APIs without maintaining separate endpoints for {% data variables.product.github %}. |
| 33 | +* Reuse existing API endpoints by translating {% data variables.product.github %} authentication into your service's native tokens. |
| 34 | + |
| 35 | +## About token exchange flow |
| 36 | + |
| 37 | +The following outlines how the {% data variables.copilot.copilot_extensibility_platform_short %} exchanges an OIDC token for an access token to authenticate requests to your extension. |
| 38 | + |
| 39 | +### Initial request |
| 40 | + |
| 41 | +1. The user sends a message to your {% data variables.copilot.copilot_extension_short %}. |
| 42 | +1. GitHub generates an OIDC token containing user identity information. |
| 43 | +1. GitHub calls your token exchange endpoint with the OIDC token. |
| 44 | +1. Your service validates the token and returns an access token. |
| 45 | +1. GitHub includes your access token in the request to your extension. |
| 46 | + |
| 47 | +```http request |
| 48 | +# HTTP header |
| 49 | +Authorization: Bearer <your-service-token> |
| 50 | +X-GitHub-Token: <github-token> |
| 51 | +``` |
| 52 | + |
| 53 | +### Subsequent requests |
| 54 | + |
| 55 | +1. {% data variables.product.github %} caches your access token for up to 10 minutes. |
| 56 | +1. The cached token is reused for subsequent requests. |
| 57 | +1. If the token expires or becomes invalid, {% data variables.product.github %} requests a new one. |
| 58 | + |
| 59 | +## Understanding OIDC tokens |
| 60 | + |
| 61 | +The OIDC token from {% data variables.product.github %} is a JWT containing claims about the user and request context: |
| 62 | + |
| 63 | +```json |
| 64 | +{ |
| 65 | + "jti": "<unique-token-id>", |
| 66 | + "sub": "<github-user-id>", |
| 67 | + "aud": "<your-client-id>", |
| 68 | + "iss": "https://github.com/login/oauth", |
| 69 | + "nbf": 1632492967, |
| 70 | + "exp": 1632493867, |
| 71 | + "iat": 1632493567, |
| 72 | + "act": { |
| 73 | + "sub": "api.copilotchat.com" |
| 74 | + } |
| 75 | +} |
| 76 | +``` |
| 77 | + |
| 78 | +## Best practices |
| 79 | + |
| 80 | +* Scope tokens to the minimum required permissions. |
| 81 | +* Implement proper error handling and logging. |
| 82 | +* Monitor token exchange patterns for security anomalies. |
| 83 | +* Keep tokens short-lived to minimize security risks. |
| 84 | +* Validate all claims before issuing access tokens. |
| 85 | +* Consider implementing rate limiting on your token exchange endpoint. |
| 86 | +* Use HTTPS for all token exchange communications. |
| 87 | + |
| 88 | +## Next steps |
| 89 | + |
| 90 | +* [AUTOTITLE](/copilot/how-tos/build-copilot-extensions/set-up-oidc) |
0 commit comments