Setting up OIDC for your GitHub Copilot extension

Introduction

You can set up OIDC so that Copilot agents and skillsets can more securely authenticate users and access cloud resources. For more information on OIDC, see OpenID Connect (OIDC) for Copilot Extensions.

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 Copilot Extension's settings

In your Copilot Extension's configuration, enable OIDC:

In the upper-right corner of any page on GitHub, click your profile picture.
Navigate to your account settings.
- For an app owned by a personal account, click Settings.
- For an app owned by an organization:
  1. Click Your organizations.
  2. To the right of the organization, click Settings.
In the left sidebar, click Developer settings.
In the left sidebar, click GitHub Apps.
To the right of the GitHub App you want to configure for your Copilot Extension, click Edit.
In the left sidebar, click Copilot.
Under OpenID Connect Token Exchange, check Enabled.
In the Token exchange endpoint field, input your token exchange URL.
In the Request header key field, input the header key for your service's token. The default is Authorization.
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 GitHub OIDC token by following the steps below:

Fetch the JSON Web Key Set (JWKS) from https://github.com/login/oauth/.well-known/openid-configuration.
Verify the token signature.
Validate required claims.
- aud: Audience. Your Copilot Extension's client ID.
- sub: Subject. The 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.