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.

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.

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 ParametersJSONExpand Collapse

clientId: string

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

minLength1

clientSecret: string

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

minLength1

issuerUrl: string

issuer_url is the URL of the IdP issuer

formaturi

organizationId: string

formatuuid

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

maxLength4096

displayName: optional string

maxLength128

emailDomain: optional string

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

minLength4

emailDomains: optional array of string

ReturnsExpand Collapse

ssoConfiguration: SSOConfiguration { id, issuerUrl, organizationId, 9 more }

sso_configuration is the created SSO configuration

id: string

id is the unique identifier of the SSO configuration

formatuuid

issuerUrl: string

issuer_url is the URL of the IdP issuer

organizationId: string

formatuuid

providerType: ProviderType

provider_type defines the type of the SSO configuration

One of the following:

"PROVIDER_TYPE_UNSPECIFIED"

"PROVIDER_TYPE_BUILTIN"

"PROVIDER_TYPE_CUSTOM"

state: SSOConfigurationState

state is the state of the SSO configuration

One of the following:

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

maxLength4096

clientId: optional string

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

displayName: optional string

maxLength128

emailDomain: optional string

emailDomains: optional array of string

CreateSSOConfiguration

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"
        }'

{
  "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"
    ]
  }
}

Returns Examples

{
  "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"
    ]
  }
}