# Set up single sign-on with SAML 2.0

Connect a SAML 2.0 identity provider so people sign in to the console through it.

Replace _Entra_ with a name for the connection, and the URLs and certificate with what your
identity provider publishes.

## Prerequisites

- Permission for `iam:CreateSsoConnection`; to turn the connection on, `iam:UpdateSsoConnection`.
  To open the **Single sign-on** page in the console, `iam:ListSsoConnections`.
- From your identity provider: its sign-in URL (single sign-on URL, HTTP-Redirect binding, an
  `https://` URL), its entity ID (issuer) and its signing certificate in PEM form. To prepare a
  certificate rotation, paste the old and the new certificate together.

## Create the connection

**Console**
1. Open **IAM**, then choose **Single sign-on**.
2. Choose **New connection**, then **SAML 2.0**.
3. For **Name**, enter Entra.
4. For **Role on first sign-in**, choose the role people get when they first sign in. The default
   is Member, with `DeveloperAccess`.
5. For **IdP sign-in URL**, **IdP entity ID (issuer)** and **IdP signing certificate (PEM)**, enter
   the values from your identity provider.
6. Choose **Create connection**. The connection appears as a card, **Off**, with the values for
   your identity provider.

**CLI**
```sh
dcloud iam sso-connections create --protocol saml --name Entra \
  --saml '{"idpSsoUrl":"https://login.example.com/saml2","idpEntityId":"https://sts.example.com/","idpCertificate":"-----BEGIN CERTIFICATE-----\n…\n-----END CERTIFICATE-----"}'
```

**API**
```http
POST /iam/api/sso-connections
{ "protocol": "saml", "name": "Entra", "saml": { "idpSsoUrl": "https://login.example.com/saml2", "idpEntityId": "https://sts.example.com/", "idpCertificate": "-----BEGIN CERTIFICATE-----\nMIIC…\n-----END CERTIFICATE-----" } }
```

**Terraform**
```hcl
resource "dcloud_iam_sso_connection" "entra" {
  name                 = "Entra"
  protocol             = "saml"
  saml_idp_sso_url     = "https://login.example.com/saml2"
  saml_idp_entity_id   = "https://sts.example.com/"
  saml_idp_certificate = file("idp-signing.pem")
  enabled              = false
}
```

## Configure your identity provider

Enter the values from the connection's card (or the `serviceProvider` object of the API response,
or the `sp_*` attributes in Terraform) in the application at your identity provider:

| At your identity provider                         | On the card                 |
| ------------------------------------------------- | --------------------------- |
| Identifier, Entity ID or Audience                 | **SP entity ID (audience)** |
| Reply URL or Assertion Consumer Service (ACS) URL | **Reply / ACS URL**         |
| Metadata, where the provider can import it        | **SP metadata URL**         |

Then:

1. Release the person's email address, as the NameID or as an attribute named `email`, `mail` or
   `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`. Given name, surname and
   display name are read when present.
2. Sign the response, the assertion or both with SHA-256. SHA-1 signatures are refused unless the
   connection is created or updated with `allowSha1` (`saml_allow_sha1` in Terraform).

## Turn it on

[Verify a domain](verify-a-domain.md), then choose **Turn on** on the card, or send
`{ "enabled": true }` as in
[Set up single sign-on with OpenID Connect](set-up-sso-with-openid-connect.md#turn-it-on).

## Result

People whose address is on a verified domain see **Continue with SSO** on the sign-in page and
are sent to your identity provider's sign-in URL. A sign-in started at the identity provider is
refused: it must start at the console.

## If it is refused

- 400 `The IdP sign-in URL must be an https:// URL`
- 400 `The IdP signing certificate is not a valid X.509 certificate`. A certificate field left
  empty is not sent: the console says `Still needed: the IdP signing certificate.`
- 400 `Verify at least one domain before turning the connection on.`
- At sign-in: `The identity provider signed this response with SHA-1, which is not accepted. …`,
  or `The SAML response was rejected: …` when the audience, signature or certificate does not
  match. See [Troubleshooting](troubleshooting.md).

## Related

- [Single sign-on](single-sign-on.md) · [Enforce single sign-on](enforce-single-sign-on.md)
- `iam.sso-connections.create` · `dcloud iam sso-connections create` · `dcloud_iam_sso_connection`
