# Set up single sign-on with OpenID Connect

Connect an OpenID Connect identity provider such as Microsoft Entra ID, Okta, Google Workspace or Keycloak so people sign in to the console through it.

Replace _Okta_ with a name for the connection, and the issuer, client ID and client secret with
the values from your identity provider.

## Prerequisites

- Permission for `iam:CreateSsoConnection`; to turn the connection on, `iam:UpdateSsoConnection`.
  To open the **Single sign-on** page in the console, `iam:ListSsoConnections`.
- An application registered at your identity provider as a **web** application, with the redirect
  URI `https://<console host>/api/auth/sso/oidc/callback` and the scopes `openid`, `email` and
  `profile`. The console shows this URI when you create the connection.
- The provider supports PKCE with `S256`, and its issuer is a public `https://` URL.

Typical issuer URLs:

| Provider           | Issuer                                                               |
| ------------------ | -------------------------------------------------------------------- |
| Microsoft Entra ID | `https://login.microsoftonline.com/<tenant id>/v2.0`                 |
| Google Workspace   | `https://accounts.google.com`                                        |
| Okta               | `https://<your domain>.okta.com`, or a custom authorization server's |
| Keycloak           | `https://<host>/realms/<realm>`                                      |

## Create the connection

**Console**
1. Open **IAM**, then choose **Single sign-on**.
2. Choose **New connection**, then **OpenID Connect**.
3. For **Name**, enter Okta.
4. For **Role on first sign-in**, choose the role people get when they first sign in. The default
   is Member, with `DeveloperAccess`.
5. Copy the **Redirect URI** into the application at your identity provider.
6. For **Issuer URL**, **Client ID** and **Client secret**, enter the values from your identity
   provider.
7. Choose **Create connection**. The connection appears as a card, **Off**.

**CLI**
```sh
dcloud iam sso-connections create --protocol oidc --name Okta --default-role member \
  --oidc '{"issuer":"https://example.okta.com","clientId":"0oa1example","clientSecret":"example-secret"}'
```

**API**
```http
POST /iam/api/sso-connections
{ "protocol": "oidc", "name": "Okta", "defaultRole": "member", "oidc": { "issuer": "https://example.okta.com", "clientId": "0oa1example", "clientSecret": "example-secret" } }
```

**Terraform**
```hcl
resource "dcloud_iam_sso_connection" "okta" {
  name               = "Okta"
  protocol           = "oidc"
  default_role       = "member"
  oidc_issuer        = "https://example.okta.com"
  oidc_client_id     = "0oa1example"
  oidc_client_secret = var.oidc_client_secret
  enabled            = false
}
```

The client secret is stored encrypted and never returned. The connection signs nobody in yet.

## Turn it on

[Verify a domain](verify-a-domain.md) of the connection first. Then:

**Console**
1. On the connection's card, choose **Turn on**. The card shows **On**.

**CLI**
```sh
dcloud iam sso-connections update connection-id --enabled
```

**API**
```http
PATCH /iam/api/sso-connections/connection-id
{ "enabled": true }
```

**Terraform**
Set `enabled = true` on the `dcloud_iam_sso_connection` resource.

## Result

People whose address is on a verified domain see **Continue with SSO** on the sign-in page. The
console reads `<issuer>/.well-known/openid-configuration` each time someone starts a sign-in. See
[Single sign-on](single-sign-on.md) for what the first sign-in does.

## If it is refused

- 400 `The issuer must be a public https:// URL on the default port, without credentials, query or fragment`
- 400 `Verify at least one domain before turning the connection on.`
- 400 `This is a SAML connection` when you send OIDC settings to a SAML connection.
- The single sign-on connections quota is reached (see [Quotas](quotas.md)).

At sign-in, an issuer that cannot be reached, or does not support PKCE with `S256`, ends with
`The identity provider could not be reached: …` on the sign-in page.

## Related

- [Single sign-on](single-sign-on.md) · [Enforce single sign-on](enforce-single-sign-on.md)
- [Map identity provider groups to IAM groups](map-idp-groups-to-iam-groups.md)
- `iam.sso-connections.create` · `dcloud iam sso-connections create` · `dcloud_iam_sso_connection`
