---
title: "CreateSSOConfiguration"
method: POST
path: "/gitpod.v1.OrganizationService/CreateSSOConfiguration"
tags: ["gitpod.v1.OrganizationService"]
---

# CreateSSOConfiguration

`POST /gitpod.v1.OrganizationService/CreateSSOConfiguration`

Creates or updates SSO configuration for organizational authentication.

 Use this method to:
 - Configure OIDC-based SSO providers
 - Set up built-in providers (Google, GitHub, etc.)
 - Define custom identity providers
 - Manage authentication policies

 ### Examples

 - Configure built-in Google SSO:

   Sets up SSO using Google Workspace.

   ```yaml
   organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
   clientId: "012345678-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com"
   clientSecret: "GOCSPX-abcdefghijklmnopqrstuvwxyz123456"
   issuerUrl: "https://accounts.google.com"
   emailDomain: "acme-corp.com"
   ```

 - Configure custom OIDC provider:

   Sets up SSO with a custom identity provider.

   ```yaml
   organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
   clientId: "acme-corp-gitpod"
   clientSecret: "secret-token-value"
   issuerUrl: "https://sso.acme-corp.com"
   emailDomain: "acme-corp.com"
   ```

## Request body

- GitpodV1CreateSSOConfigurationRequest
  - `additionalScopes` string[] — additional_scopes are extra OIDC scopes to request from the identity provider during sign-in. These are appended to the default scopes (openid, email, profile).
  - `claimsExpression` string, nullable — claims_expression is an optional CEL expression evaluated against OIDC token claims during login. When set, the expression must evaluate to true for the login to succeed. Example: `claims.email_verified && claims.email.endsWith("@example.com")`
  - `clientId` string, required — client_id is the client ID of the OIDC application set on the IdP
  - `clientSecret` string, required — client_secret is the client secret of the OIDC application set on the IdP
  - `displayName` string
  - `emailDomain` string, nullable — email_domain is the domain that is allowed to sign in to the organization
  - `emailDomains` string[]
  - `issuerUrl` string, uri, required — issuer_url is the URL of the IdP issuer
  - `organizationId` string, uuid, required

## Response `200`

Success

- GitpodV1CreateSSOConfigurationResponse
  - `ssoConfiguration` GitpodV1SSOConfiguration, required
    - `additionalScopes` string[] — additional_scopes are extra OIDC scopes requested from the identity provider during sign-in.
    - `claims` object — claims are key/value pairs that defines a mapping of claims issued by the IdP.
    - `claimsExpression` string — claims_expression is a CEL (Common Expression Language) expression evaluated against the OIDC token claims during login. When set, the expression must evaluate to true for the login to succeed. The expression has access to a `claims` variable containing all token claims as a map. Example: `claims.email_verified && claims.email.endsWith("@example.com")`
    - `clientId` string — client_id is the client ID of the OIDC application set on the IdP
    - `displayName` string
    - `emailDomain` string
    - `emailDomains` string[]
    - `id` string, uuid, required — id is the unique identifier of the SSO configuration
    - `issuerUrl` string, required — issuer_url is the URL of the IdP issuer
    - `organizationId` string, uuid, required
    - `providerType` 'PROVIDER_TYPE_UNSPECIFIED' | 'PROVIDER_TYPE_BUILTIN' | 'PROVIDER_TYPE_CUSTOM', required
    - `state` 'SSO_CONFIGURATION_STATE_UNSPECIFIED' | 'SSO_CONFIGURATION_STATE_INACTIVE' | 'SSO_CONFIGURATION_STATE_ACTIVE', required

## Other responses

- `default` — Error

## Changes

- **2026-04-02** `dabc0ff98cd7` — 2 info
  - added the new optional request property `claimsExpression`
  - added the optional property `ssoConfiguration/claimsExpression` to the response with the `200` status
- **2026-02-11** `b97dcde84128` — 2 info
  - added the new optional request property `additionalScopes`
  - added the optional property `ssoConfiguration/additionalScopes` to the response with the `200` status
- **2025-12-15** `d62ef4b9187c` — 6 info
  - added the new optional request property `displayName`
  - added the new optional request property `emailDomains`
  - the request property `emailDomain` became nullable
  - the request property `emailDomain` became optional
  - …2 more
- **2025-02-21** `3655d5ad0ac3` — 1 breaking, 9 info
  - the `ssoConfiguration` response's property type/format changed from ``/`` to `object`/`` for status `200`
  - added the optional property `ssoConfiguration/claims` to the response with the `200` status
  - added the optional property `ssoConfiguration/clientId` to the response with the `200` status
  - added the optional property `ssoConfiguration/emailDomain` to the response with the `200` status
  - …6 more
- **2025-02-18** `cd6a05ae99d2` — 1 warning
  - removed the optional property `detail` from the response with the `default` status

[Full history](https://skmtc.dev/gitpod-io/apis/gitpod-v1/changes/gitpod.v1.OrganizationService/CreateSSOConfiguration/post.md)

---

[API](https://skmtc.dev/gitpod-io/apis/gitpod-v1.md) · [All operations](https://skmtc.dev/gitpod-io/apis/gitpod-v1/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/gitpod-io/gitpod-v1/revisions/44d50c2ac284/schema)