Identity Provider Requirements

Cofide Connect does not manage user accounts or passwords itself. Instead it delegates user authentication to an external OAuth 2.0 / OpenID Connect (OIDC) Identity Provider (IdP), sometimes called the OAuth Authorization Server (AS), that you provide and operate. Most operators will use their existing identity provider and configure it for Connect rather than deploying a new one. This page describes what that identity provider must support, and what you need to configure on it, so that operators, users and CI can authenticate to Connect.

Protocol support

The identity provider must:

Be a conformant OAuth 2.0 / OpenID Connect provider.
Expose an OIDC Discovery document at <issuer>/.well-known/openid-configuration.
Publish a JWKS endpoint so that Connect can retrieve the public keys used to verify token signatures.
Support the Authorization Code flow with PKCE, which is used by both the CLI and the UI as public clients.
Issue access tokens in JWT format rather than opaque tokens, since the Connect API validates them directly.

Connect does not require refresh tokens. Both clients request the offline_access scope by default so that sessions can persist without the user having to log in again when their cached access token expires, and the provider issues refresh tokens when it honours that scope.

Clients

You need to register two public clients (clients with no secret) with your identity provider, both under the same issuer: one for the Connect UI and one for the cofidectl CLI.

Connect UI client

Configure:

Client type. A browser-based public client with no client secret. Providers that register clients against a platform type call this a Single-page application (Microsoft Entra ID, Okta), Single Page Application (Auth0) or Single Page App (PingOne).
Token endpoint authentication method. none. As a public client the UI holds no secret and relies on PKCE instead.
Grant types. Authorization Code with PKCE (using the S256 code challenge method), and optionally the Refresh Token grant so that the provider honours the offline_access scope.
Response types. code (Authorization Code).
Redirect URIs. The UI redirects back to its own root (for example https://app.example.cofide.dev/). Register this same URL as both the redirect_uri and the post_logout_redirect_uri.
Allowed web origins. The UI performs the PKCE token exchange from its own origin in the browser, so that origin (for example https://app.example.cofide.dev) must be allowlisted for CORS at the provider. This setting is called Allowed Web Origins (Auth0), Web Origins (Keycloak) or Trusted Origins (Okta).
Audience. Tokens issued to the client must include the Connect API audience (for example https://connect.example.cofide.dev) in the aud claim. The UI requests this through the ui.oauth.audience Helm value.
Scopes. openid, offline_access (so the provider grants refresh tokens for silent renewal) and email (which the UI uses to identify the signed-in user). The UI requests these through the ui.oauth.scopes Helm value.

cofidectl CLI client

The CLI defaults to a client ID of cofidectl, which you can override with cofidectl connect init --oauth-client-id <client-id>.

Configure:

Client type. A native public client with no client secret, so that the loopback redirect is permitted. Providers that register clients against a platform type call this Mobile and desktop applications (Microsoft Entra ID), a Native Application (Okta, Auth0) or a Native App (PingOne). This differs from the UI client, which is registered as a single-page application.
Token endpoint authentication method. none. As a public client the CLI holds no secret and relies on PKCE instead. Some providers gate this behind a toggle, for example Microsoft Entra ID’s Allow public client flows.
Grant types. Authorization Code with PKCE (using the S256 code challenge method), and optionally the Refresh Token grant so that the provider honours the offline_access scope.
Response types. code (Authorization Code).
Redirect URIs. For the Authorization Code flow the CLI uses a loopback redirect (http://127.0.0.1:4446/callback) following the OAuth 2.0 for Native Apps pattern.

Audience. Tokens issued to the client must include the Connect API audience (for example https://connect.example.cofide.dev) in the aud claim. The CLI requests this with --connect-audience.
Scopes. By default openid, profile, email and offline_access (for refresh tokens), configurable with --oauth-scope.

Token claims

The access token presented to the Connect API must contain:

sub: the subject that identifies the user. This is the value used as a user subject when creating role bindings.
aud: must match one of the audiences configured in the cofide-connect Helm chart’s envoy.auth.audiences (for example https://connect.example.cofide.dev).
iss and exp: standard issuer and expiry claims, validated by Connect.

The audience must be present on the OAuth access token (the bearer credential the Connect API validates), not on the OIDC ID token, whose aud is always the client ID. How the audience lands on the access token is provider-specific. The CLI and UI request it with an audience parameter, which some providers honour (for example Ory and Auth0). Others derive it from a scope the client requests (for example Microsoft Entra ID’s <resource>/.default), and others (for example Okta and Keycloak) require the audience to be configured on the authorization server or through an audience mapper. The clients do not send the RFC 8707 resource parameter, so a provider that only accepts resource to set the audience needs the audience configuring on the authorization server instead.

The provider must also issue access tokens in JWT format, so providers that only issue opaque access tokens (for example Google) are not supported directly. An intermediary such as Dex can be used in such cases.

Group membership is optional. When used, it must be carried in a claim named groups. This claim name is not currently configurable on the Connect side.

How that claim is added to the access token is provider-specific, and in most cases it is part of the client or authorization server configuration rather than something the client requests. Microsoft Entra ID emits it when the app registration opts into a groups claim, and Okta and Keycloak use a claim or protocol mapper. A few providers (for example Ory and Auth0) instead add the claim when the client requests a non-standard groups scope. If yours behaves that way, add groups to the ui.oauth.scopes Helm value for the UI and to --oauth-scope for the CLI.

See Access Control: Concepts for how the subject and group claims map to role bindings.

How Connect uses the identity provider

The identity provider details are configured in three places, all of which must refer to the same issuer:

The Connect API Helm values (Deploy Connect API) set envoy.auth.issuer, envoy.auth.jwksUri and envoy.auth.audiences. The Connect API, fronted by Envoy, is the resource server. It validates the JWT access token’s signature against the JWKS, along with the issuer and audience.
The Connect UI Helm values (Deploy Connect UI) set ui.oauth.clientId, ui.oauth.audience, ui.oauth.scopes and ui.oauth.issuer.
The CLI (Installing and configuring cofidectl) sets --oauth-client-id, --connect-audience and --oauth-scope at cofidectl connect init time, then drives the browser login flow with cofidectl connect login. It discovers the issuer from the Connect API’s OAuth protected resource metadata, or you can set it explicitly with --oauth-issuer.