# SSO Configurations

## 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"
  ```

### Body Parameters

- `clientId: string`

  client_id is the client ID of the OIDC application set on the IdP

- `clientSecret: string`

  client_secret is the client secret of the OIDC application set on the IdP

- `issuerUrl: string`

  issuer_url is the URL of the IdP issuer

- `organizationId: string`

- `additionalScopes: optional array of 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: optional string`

  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")`

- `displayName: optional string`

- `emailDomain: optional string`

  email_domain is the domain that is allowed to sign in to the organization

- `emailDomains: optional array of string`

### Returns

- `ssoConfiguration: SSOConfiguration`

  sso_configuration is the created SSO configuration

  - `id: string`

    id is the unique identifier of the SSO configuration

  - `issuerUrl: string`

    issuer_url is the URL of the IdP issuer

  - `organizationId: string`

  - `providerType: ProviderType`

    provider_type defines the type of the SSO configuration

    - `"PROVIDER_TYPE_UNSPECIFIED"`

    - `"PROVIDER_TYPE_BUILTIN"`

    - `"PROVIDER_TYPE_CUSTOM"`

  - `state: SSOConfigurationState`

    state is the state of the SSO configuration

    - `"SSO_CONFIGURATION_STATE_UNSPECIFIED"`

    - `"SSO_CONFIGURATION_STATE_INACTIVE"`

    - `"SSO_CONFIGURATION_STATE_ACTIVE"`

  - `additionalScopes: optional array of string`

    additional_scopes are extra OIDC scopes requested from the identity provider during sign-in.

  - `claims: optional map[string]`

    claims are key/value pairs that defines a mapping of claims issued by the IdP.

  - `claimsExpression: optional 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: optional string`

    client_id is the client ID of the OIDC application set on the IdP

  - `displayName: optional string`

  - `emailDomain: optional string`

  - `emailDomains: optional array of string`

### Example

```http
curl https://app.gitpod.io/api/gitpod.v1.OrganizationService/CreateSSOConfiguration \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{
          "clientId": "012345678-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com",
          "clientSecret": "GOCSPX-abcdefghijklmnopqrstuvwxyz123456",
          "issuerUrl": "https://accounts.google.com",
          "organizationId": "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
        }'
```

#### Response

```json
{
  "ssoConfiguration": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "issuerUrl": "issuerUrl",
    "organizationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "providerType": "PROVIDER_TYPE_UNSPECIFIED",
    "state": "SSO_CONFIGURATION_STATE_UNSPECIFIED",
    "additionalScopes": [
      "string"
    ],
    "claims": {
      "foo": "string"
    },
    "claimsExpression": "claimsExpression",
    "clientId": "clientId",
    "displayName": "displayName",
    "emailDomain": "emailDomain",
    "emailDomains": [
      "sfN2.l.iJR-BU.u9JV9.a.m.o2D-4b-Jd.0Z-kX.L.n.S.f.UKbxB"
    ]
  }
}
```

## DeleteSSOConfiguration

**post** `/gitpod.v1.OrganizationService/DeleteSSOConfiguration`

Removes an SSO configuration from an organization.

Use this method to:

- Disable SSO authentication
- Remove outdated providers
- Clean up unused configurations

### Examples

- Delete SSO configuration:

  Removes a specific SSO configuration.

  ```yaml
  ssoConfigurationId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  ```

### Body Parameters

- `ssoConfigurationId: string`

### Example

```http
curl https://app.gitpod.io/api/gitpod.v1.OrganizationService/DeleteSSOConfiguration \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{
          "ssoConfigurationId": "d2c94c27-3b76-4a42-b88c-95a85e392c68"
        }'
```

#### Response

```json
{}
```

## ListSSOConfigurations

**post** `/gitpod.v1.OrganizationService/ListSSOConfigurations`

Lists and filters SSO configurations for an organization.

Use this method to:

- View all SSO providers
- Monitor authentication status
- Audit security settings
- Manage provider configurations

### Examples

- List active configurations:

  Shows all active SSO providers.

  ```yaml
  organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
  pagination:
    pageSize: 20
  ```

- List by provider type:

  Shows custom SSO configurations.

  ```yaml
  organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
  pagination:
    pageSize: 20
    token: "next-page-token-from-previous-response"
  ```

### Query Parameters

- `token: optional string`

- `pageSize: optional number`

### Body Parameters

- `organizationId: string`

  organization_id is the ID of the organization to list SSO configurations for.

- `pagination: optional object { token, pageSize }`

  - `token: optional string`

    Token for the next set of results that was returned as next_token of a
    PaginationResponse

  - `pageSize: optional number`

    Page size is the maximum number of results to retrieve per page.
    Defaults to 25. Maximum 100.

### Returns

- `pagination: object { nextToken }`

  - `nextToken: optional string`

    Token passed for retrieving the next set of results. Empty if there are no
    more results

- `ssoConfigurations: optional array of SSOConfiguration`

  sso_configurations are the SSO configurations for the organization

  - `id: string`

    id is the unique identifier of the SSO configuration

  - `issuerUrl: string`

    issuer_url is the URL of the IdP issuer

  - `organizationId: string`

  - `providerType: ProviderType`

    provider_type defines the type of the SSO configuration

    - `"PROVIDER_TYPE_UNSPECIFIED"`

    - `"PROVIDER_TYPE_BUILTIN"`

    - `"PROVIDER_TYPE_CUSTOM"`

  - `state: SSOConfigurationState`

    state is the state of the SSO configuration

    - `"SSO_CONFIGURATION_STATE_UNSPECIFIED"`

    - `"SSO_CONFIGURATION_STATE_INACTIVE"`

    - `"SSO_CONFIGURATION_STATE_ACTIVE"`

  - `additionalScopes: optional array of string`

    additional_scopes are extra OIDC scopes requested from the identity provider during sign-in.

  - `claims: optional map[string]`

    claims are key/value pairs that defines a mapping of claims issued by the IdP.

  - `claimsExpression: optional 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: optional string`

    client_id is the client ID of the OIDC application set on the IdP

  - `displayName: optional string`

  - `emailDomain: optional string`

  - `emailDomains: optional array of string`

### Example

```http
curl https://app.gitpod.io/api/gitpod.v1.OrganizationService/ListSSOConfigurations \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{
          "organizationId": "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
        }'
```

#### Response

```json
{
  "pagination": {
    "nextToken": "nextToken"
  },
  "ssoConfigurations": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "issuerUrl": "issuerUrl",
      "organizationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "providerType": "PROVIDER_TYPE_UNSPECIFIED",
      "state": "SSO_CONFIGURATION_STATE_UNSPECIFIED",
      "additionalScopes": [
        "string"
      ],
      "claims": {
        "foo": "string"
      },
      "claimsExpression": "claimsExpression",
      "clientId": "clientId",
      "displayName": "displayName",
      "emailDomain": "emailDomain",
      "emailDomains": [
        "sfN2.l.iJR-BU.u9JV9.a.m.o2D-4b-Jd.0Z-kX.L.n.S.f.UKbxB"
      ]
    }
  ]
}
```

## GetSSOConfiguration

**post** `/gitpod.v1.OrganizationService/GetSSOConfiguration`

Retrieves a specific SSO configuration.

Use this method to:

- View SSO provider details
- Check configuration status
- Verify SSO settings

### Examples

- Get SSO configuration:

  Retrieves details of a specific SSO configuration.

  ```yaml
  ssoConfigurationId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  ```

### Body Parameters

- `ssoConfigurationId: string`

  sso_configuration_id is the ID of the SSO configuration to get

### Returns

- `ssoConfiguration: SSOConfiguration`

  sso_configuration is the SSO configuration identified by the ID

  - `id: string`

    id is the unique identifier of the SSO configuration

  - `issuerUrl: string`

    issuer_url is the URL of the IdP issuer

  - `organizationId: string`

  - `providerType: ProviderType`

    provider_type defines the type of the SSO configuration

    - `"PROVIDER_TYPE_UNSPECIFIED"`

    - `"PROVIDER_TYPE_BUILTIN"`

    - `"PROVIDER_TYPE_CUSTOM"`

  - `state: SSOConfigurationState`

    state is the state of the SSO configuration

    - `"SSO_CONFIGURATION_STATE_UNSPECIFIED"`

    - `"SSO_CONFIGURATION_STATE_INACTIVE"`

    - `"SSO_CONFIGURATION_STATE_ACTIVE"`

  - `additionalScopes: optional array of string`

    additional_scopes are extra OIDC scopes requested from the identity provider during sign-in.

  - `claims: optional map[string]`

    claims are key/value pairs that defines a mapping of claims issued by the IdP.

  - `claimsExpression: optional 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: optional string`

    client_id is the client ID of the OIDC application set on the IdP

  - `displayName: optional string`

  - `emailDomain: optional string`

  - `emailDomains: optional array of string`

### Example

```http
curl https://app.gitpod.io/api/gitpod.v1.OrganizationService/GetSSOConfiguration \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{
          "ssoConfigurationId": "d2c94c27-3b76-4a42-b88c-95a85e392c68"
        }'
```

#### Response

```json
{
  "ssoConfiguration": {
    "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "issuerUrl": "issuerUrl",
    "organizationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "providerType": "PROVIDER_TYPE_UNSPECIFIED",
    "state": "SSO_CONFIGURATION_STATE_UNSPECIFIED",
    "additionalScopes": [
      "string"
    ],
    "claims": {
      "foo": "string"
    },
    "claimsExpression": "claimsExpression",
    "clientId": "clientId",
    "displayName": "displayName",
    "emailDomain": "emailDomain",
    "emailDomains": [
      "sfN2.l.iJR-BU.u9JV9.a.m.o2D-4b-Jd.0Z-kX.L.n.S.f.UKbxB"
    ]
  }
}
```

## UpdateSSOConfiguration

**post** `/gitpod.v1.OrganizationService/UpdateSSOConfiguration`

Updates SSO provider settings and authentication rules.

Use this method to:

- Rotate client credentials
- Update provider endpoints
- Modify claim mappings
- Change authentication policies
- Toggle SSO enforcement

### Examples

- Update credentials:

  Rotates client ID and secret.

  ```yaml
  ssoConfigurationId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  clientId: "new-client-id"
  clientSecret: "new-client-secret"
  ```

- Update provider status:

  Activates or deactivates SSO provider.

  ```yaml
  ssoConfigurationId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  state: SSO_CONFIGURATION_STATE_ACTIVE
  ```

### Body Parameters

- `ssoConfigurationId: string`

  sso_configuration_id is the ID of the SSO configuration to update

- `additionalScopes: optional AdditionalScopesUpdate`

  additional_scopes replaces the configured OIDC scopes when present.
  When absent (nil), scopes are left unchanged.
  When present with an empty scopes list, all additional scopes are cleared.

  - `scopes: optional array of string`

- `claims: optional map[string]`

  claims are key/value pairs that defines a mapping of claims issued by the IdP.

- `claimsExpression: optional string`

  claims_expression is a CEL expression evaluated against OIDC token claims during login.
  When set, the expression must evaluate to true for the login to succeed.
  When present with an empty string, the expression is cleared.

- `clientId: optional string`

  client_id is the client ID of the SSO provider

- `clientSecret: optional string`

  client_secret is the client secret of the SSO provider

- `displayName: optional string`

- `emailDomain: optional string`

- `emailDomains: optional array of string`

- `issuerUrl: optional string`

  issuer_url is the URL of the IdP issuer

- `state: optional SSOConfigurationState`

  state is the state of the SSO configuration

  - `"SSO_CONFIGURATION_STATE_UNSPECIFIED"`

  - `"SSO_CONFIGURATION_STATE_INACTIVE"`

  - `"SSO_CONFIGURATION_STATE_ACTIVE"`

### Example

```http
curl https://app.gitpod.io/api/gitpod.v1.OrganizationService/UpdateSSOConfiguration \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{
          "ssoConfigurationId": "d2c94c27-3b76-4a42-b88c-95a85e392c68"
        }'
```

#### Response

```json
{}
```

## Domain Types

### Additional Scopes Update

- `AdditionalScopesUpdate object { scopes }`

  AdditionalScopesUpdate wraps a list of OIDC scopes so that the update request
  can distinguish "not changing scopes" (field absent) from "clearing all scopes"
  (field present, empty list).

  - `scopes: optional array of string`

### Provider Type

- `ProviderType = "PROVIDER_TYPE_UNSPECIFIED" or "PROVIDER_TYPE_BUILTIN" or "PROVIDER_TYPE_CUSTOM"`

  - `"PROVIDER_TYPE_UNSPECIFIED"`

  - `"PROVIDER_TYPE_BUILTIN"`

  - `"PROVIDER_TYPE_CUSTOM"`

### SSO Configuration

- `SSOConfiguration object { id, issuerUrl, organizationId, 9 more }`

  - `id: string`

    id is the unique identifier of the SSO configuration

  - `issuerUrl: string`

    issuer_url is the URL of the IdP issuer

  - `organizationId: string`

  - `providerType: ProviderType`

    provider_type defines the type of the SSO configuration

    - `"PROVIDER_TYPE_UNSPECIFIED"`

    - `"PROVIDER_TYPE_BUILTIN"`

    - `"PROVIDER_TYPE_CUSTOM"`

  - `state: SSOConfigurationState`

    state is the state of the SSO configuration

    - `"SSO_CONFIGURATION_STATE_UNSPECIFIED"`

    - `"SSO_CONFIGURATION_STATE_INACTIVE"`

    - `"SSO_CONFIGURATION_STATE_ACTIVE"`

  - `additionalScopes: optional array of string`

    additional_scopes are extra OIDC scopes requested from the identity provider during sign-in.

  - `claims: optional map[string]`

    claims are key/value pairs that defines a mapping of claims issued by the IdP.

  - `claimsExpression: optional 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: optional string`

    client_id is the client ID of the OIDC application set on the IdP

  - `displayName: optional string`

  - `emailDomain: optional string`

  - `emailDomains: optional array of string`

### SSO Configuration State

- `SSOConfigurationState = "SSO_CONFIGURATION_STATE_UNSPECIFIED" or "SSO_CONFIGURATION_STATE_INACTIVE" or "SSO_CONFIGURATION_STATE_ACTIVE"`

  - `"SSO_CONFIGURATION_STATE_UNSPECIFIED"`

  - `"SSO_CONFIGURATION_STATE_INACTIVE"`

  - `"SSO_CONFIGURATION_STATE_ACTIVE"`

### SSO Configuration Create Response

- `SSOConfigurationCreateResponse object { ssoConfiguration }`

  - `ssoConfiguration: SSOConfiguration`

    sso_configuration is the created SSO configuration

    - `id: string`

      id is the unique identifier of the SSO configuration

    - `issuerUrl: string`

      issuer_url is the URL of the IdP issuer

    - `organizationId: string`

    - `providerType: ProviderType`

      provider_type defines the type of the SSO configuration

      - `"PROVIDER_TYPE_UNSPECIFIED"`

      - `"PROVIDER_TYPE_BUILTIN"`

      - `"PROVIDER_TYPE_CUSTOM"`

    - `state: SSOConfigurationState`

      state is the state of the SSO configuration

      - `"SSO_CONFIGURATION_STATE_UNSPECIFIED"`

      - `"SSO_CONFIGURATION_STATE_INACTIVE"`

      - `"SSO_CONFIGURATION_STATE_ACTIVE"`

    - `additionalScopes: optional array of string`

      additional_scopes are extra OIDC scopes requested from the identity provider during sign-in.

    - `claims: optional map[string]`

      claims are key/value pairs that defines a mapping of claims issued by the IdP.

    - `claimsExpression: optional 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: optional string`

      client_id is the client ID of the OIDC application set on the IdP

    - `displayName: optional string`

    - `emailDomain: optional string`

    - `emailDomains: optional array of string`

### SSO Configuration Delete Response

- `SSOConfigurationDeleteResponse = unknown`

### SSO Configuration Retrieve Response

- `SSOConfigurationRetrieveResponse object { ssoConfiguration }`

  - `ssoConfiguration: SSOConfiguration`

    sso_configuration is the SSO configuration identified by the ID

    - `id: string`

      id is the unique identifier of the SSO configuration

    - `issuerUrl: string`

      issuer_url is the URL of the IdP issuer

    - `organizationId: string`

    - `providerType: ProviderType`

      provider_type defines the type of the SSO configuration

      - `"PROVIDER_TYPE_UNSPECIFIED"`

      - `"PROVIDER_TYPE_BUILTIN"`

      - `"PROVIDER_TYPE_CUSTOM"`

    - `state: SSOConfigurationState`

      state is the state of the SSO configuration

      - `"SSO_CONFIGURATION_STATE_UNSPECIFIED"`

      - `"SSO_CONFIGURATION_STATE_INACTIVE"`

      - `"SSO_CONFIGURATION_STATE_ACTIVE"`

    - `additionalScopes: optional array of string`

      additional_scopes are extra OIDC scopes requested from the identity provider during sign-in.

    - `claims: optional map[string]`

      claims are key/value pairs that defines a mapping of claims issued by the IdP.

    - `claimsExpression: optional 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: optional string`

      client_id is the client ID of the OIDC application set on the IdP

    - `displayName: optional string`

    - `emailDomain: optional string`

    - `emailDomains: optional array of string`

### SSO Configuration Update Response

- `SSOConfigurationUpdateResponse = unknown`