docs/content/copilot/how-tos/use-copilot-extensions/set-up-oidc.md

title, intro, versions, topics, shortTitle, allowTitleToDifferFromFilename, redirect_from, contentType, category

title	intro	versions	topics	shortTitle	allowTitleToDifferFromFilename	redirect_from	contentType	category
Setting up OIDC for your GitHub Copilot extension	Learn how to set up OpenID Connect (OIDC) with your {% data variables.copilot.copilot_extension_short %} to enhance security.	feature copilot-extensions	Copilot	Set up OIDC	true	/copilot/building-copilot-extensions/using-oidc-with-copilot-extensions /copilot/building-copilot-extensions/using-oidc-with-github-copilot-extensions /copilot/how-tos/build-copilot-extensions/using-oidc-with-github-copilot-extensions /copilot/how-tos/build-copilot-extensions/set-up-oidc	how-tos	Integrate Copilot with your tools

Introduction

You can set up OIDC so that {% data variables.product.prodname_copilot_short %} agents and skillsets can more securely authenticate users and access cloud resources. For more information on OIDC, see AUTOTITLE.

There are three steps to setting up OIDC for your extension.

• Configure your token exchange endpoint.
• Enable OIDC in your Copilot extensions settings.
• 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. This endpoint should:

• Accept POST requests with the following form-encoded parameters:

  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:

  {
    "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:

  {
    "error": "invalid_request"
  }
  

Enable OIDC in your {% data variables.copilot.copilot_extension_short %}'s settings

In your {% data variables.copilot.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.copilot.copilot_extension_short %}, click Edit.
2. In the left sidebar, click {% data variables.product.prodname_copilot_short %}.
3. Under OpenID Connect Token Exchange, check Enabled.
4. In the Token exchange endpoint field, input your token exchange URL.
5. In the Request header key field, input the header key for your service's token. The default is Authorization.
6. 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.
2. Verify the token signature.
3. Validate required claims.
   • aud: Audience. Your {% data variables.copilot.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.copilot.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.

Further reading

• AUTOTITLE