# Authentication



# Migrating from SAML to OpenID Connect

To migrate an EMS cloud host with SAML to OpenID Connect, follow the following steps.

1. Follow the [OpenID Connect setup guide](https://ems-docs.element.io/books/element-cloud-documentation/page/openid-connect#bkmrk-google) to create an OAuth2 client ID. **Important**, only do the Google console part, do NOT configure OpenID Connect on your EMS host. Do NOT remove your SAML configuration from the Google console or the EMS configuration.
2. Once you have your Google OAuth2 client ID and secret, contact EMS support (via the [portal](https://ems.element.io/support) or `ems-support@element.io`) to agree on how to securely deliver the credentials. For the ticket, request "SAML to OpenID Connect" migration, indicating the hostname in question. DO NOT put the Oauth2 client id or secret in the support ticket. Please also indicate a preferred time during week days for the migration to happen.

Support will agree on a secure delivery method for the client ID and secret, and notify of an actual migration time.

During the migration time you do not need to take any action. There will be downtime on the service for a few minutes while the changes are applied. While the migration happens the old SAML subscription will be cancelled and a new one for OpenID Connect made. This may mean a charge on your credit card. The subscription cost of OpenID Connect and SAML will be the same.

One the migration is complete, you can safely remove the SAML configuration from the Google console. Existing user sessions will work as before.

# LDAP Active Directory

This guide assumes you already have a forest/domain configured and that your environment is properly secured.

This is a basic configuration. You may want to set additional options or permissions in your forest/domain.

See also <a href="https://element.io/enterprise/enterprise-functionality/delegated-authentication" target="_blank" rel="noopener noreferrer">Delegated Authentication for single sign-on (SSO) integration</a>.

## Setup

To enable authentication with LDAP and Active Directory, the following needs to be done:

- Configure secure LDAP in your domain.
- Create a user and optionally an UO to use for LDAP authentication.

## Configure Your EMS Server

- Set up an Element Cloud Enterprise server.
- Click the Integrations tab.
- Select LDAP from the list of available Advanced Authentication methods.
- Set the following configuration parameters:

```none
Bind URI: ldaps://ldap.example.com:636
Base: OU=matrix,DC=example,DC=com
Bind DN: CN=emsadmin,CN=Users,DC=example,DD=com
Bind Password: supersecret
UID: SamAccountName
Display Name: See below
Email: mail
```

- For Display Name, you have a few options based on your preference. For example:
  - displayName
  - GivenName
  - Name
  - sn
- For a full list, open PowerShell on your domain controller and enter

```powershell
Import-Module ActiveDirectory
Get-ADUser test_user -Properties *
```

- Save your LDAP settings and wait for your EMS server to reprovision.
- Authentication in Element should now be working. If not, please look in the logs for your firewall or domain controllers
or contact EMS support from <a href="https://ems.element.io/support" target="_blank" rel="noopener noreferrer">our support form</a>

# OpenID Connect

Your homeserver can be configured to authenticate its users with an OpenID Connect provider. Here we list the most
popular providers and how to configure them.

- [Authentik](#bkmrk-authentik)
- [Gitea](#bkmrk-gitea)
- [GitHub](#bkmrk-github)
- [GitLab](#bkmrk-gitlab)
- [Google](#bkmrk-google)
- [Okta](#bkmrk-okta)

See also
<a
  href="https://element.io/enterprise/enterprise-functionality/delegated-authentication"
  target="_blank"
  rel="noopener noreferrer">
Delegated Authentication for single sign-on (SSO) integration
</a>.

## Authentik

- Create a new `OAuth2/OpenID Provider` provider
- Name: can be anything
- Authentication flow: `default-authentication-flow`
- Authorization flow: `default-provider-authentication-explicit-consent`
- Client type: Confidential
- Take note of the Client ID and Client Secret
- Redirect URIs/Origins (RegEx): `https://my-host.ems.host/_synapse/client/oidc/callback`. Adapt the URL to match your homeserver's address. You must use your `.ems.host` domain, even if your server uses Custom DNS.
- Signing Key: `authentik Self-signed Certificate`
- Create an application using the provider you just created. Take note of the Slug

### In the Element Matrix Services configuration form

- Preset: `Custom`
- Issuer: `https://your-authentik-instance.com/application/o/the-slug-from-above/` (you can also find this URL on the provider as `OpenID Configuration Issuer`)
- Client ID and Secret: Values from above
- Discover endpoints: Enable
- Scopes: `openid,profile,email`
- Subject claim: `sub`
- Username attribute: `preferred_username`
- Display name attribute: `name`

## Gitea

- Create a new `OAuth2 Application` on <https://your-gitea-instance.com/user/settings/applications>
- Choose a name for you and your users to recognize
- Set `Redirect URIs` to `https://my-host.ems.host/_synapse/client/oidc/callback`. Adapt the URL to match your
  homeserver's address. You must use your `.ems.host` domain, even if your server uses Custom DNS.
- Confidential Client: enable

### In the Element Matrix Services configuration form

- Preset: `Custom`
- Issuer: `https://your-gitea-instance.com/`
- Client ID and Secret: Values given by Gitea OAuth2 settings
- Discover endpoints: Enable
- Scopes: `openid,profile`
- Subject claim: leave empty
- Username attribute: `name`
- Display name attribute: `name`'

## GitHub

For detailed information, read
<a href="https://docs.github.com/en/developers/apps/authorizing-oauth-apps" target="_blank" rel="noopener noreferrer">
  GitHub's guide on OpenID
</a>.

1. Create a<a href="https://github.com/settings/applications/new" target="_blank" rel="noopener noreferrer">
    new application on GitHub.com
  </a>.
1. Choose a name for you and your users to recognize.
1. Choose a homepage URL. You can pick any URL. If your company maintains a guide on how to use Matrix, this would be
  most helpful.
1. The Authorization callback URL needs to be `https://my-host.ems.host`. Adapt the URL to match your homeserver's
  address.
You must use your `.ems.host` domain, even if your server uses Custom DNS.
1. Save and note the client ID and client secret. Those are needed when adding the OpenID Connect integration in our
  interface.

### In the Element Matrix Services configuration form

Use the preset `GitHub` for a simplified form or use `Custom` with the following values:

- Issuer must be `https://github.com/`
- Use the client id and secret from above.
- Discover must be turned off.
- Authorization URI must be `https://github.com/login/oauth/authorize`.
- Token URI must be `https://github.com/login/oauth/authorize`.
- User Info URI must be `https://api.github.com/user`.
- JWKS URI is not required, because the scope `profile` will be requested.
- The scopes should be `openid,profile,read:user`.
- Subject Claim must be `id`.
- Username attribute should be `login`.
- The display name can be `name` (GitHub's display name) or `login` (GitHub's user handle).

## GitLab

For detailed information, read
<a href="https://docs.gitlab.com/ee/integration/openid_connect_provider.html" target="_blank" rel="noopener noreferrer">
  GitLab's guide on OpenID
</a>.

1. Create a <a href="https://gitlab.com/-/user_settings/applications" target="_blank" rel="noopener noreferrer">new application
  on GitLab.com</a>.
1. Choose a name for you and your users to recognize.
1. Choose a homepage URL. You can pick any URL. If your company maintains a guide on how to use Matrix, this would be
  most helpful.
1. The Redirect URL needs to be `https://my-host.ems.host/_synapse/client/oidc/callback`. Adapt the URL to match your
  homeserver's address.
You must use your `.ems.host` domain, even if your server uses Custom DNS.
1. Check the scopes `read_user`, `openid` and `profile`.
1. Save and note the client ID and client secret. Those are needed when adding the OpenID Connect integration in our
  interface.

To connect your own GitLab instance, simply adapt the URL path.

### In the Element Matrix Services configuration form

- Issuer must be `https://gitlab.com/` or the URL of your GitLab instance.
- Use the client id and secret from above.
- Discover must be turned on.
- The scopes should be `openid,profile,read_user`.
- Leave Subject Claim empty.
- Username attribute should be `nickname`.
- Display name attribute can be `name` (GitLab's display name) or `nickname` (GitLab's user handle).

## Google

For detailed information, read
<a
  href="https://developers.google.com/identity/protocols/oauth2/openid-connect"
  target="_blank"
  rel="noopener noreferrer">
Google's guide on OpenID
</a>.

1. Create a <a href="https://console.developers.google.com/apis/credentials" target="_blank" rel="noopener noreferrer">
  new application on Google
</a>.
1. Click `Create credentials` and `OAuth client ID`.
1. Select the application type `Web application`.
1. Choose a name for you and your users to recognize.
1. Add an authorized redirect URI with your homeserver URL, like
  `https://my-host.ems.host/_synapse/client/oidc/callback`.
  You must use your `.ems.host` domain, even if your server uses Custom DNS.
1. Save and note the client ID and client secret. Those are needed when adding the OpenID Connect integration in our
  interface.
<!--[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702389800129.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702389800129.png)-->
<video width="600" controls
  poster="https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702389800129.png"
  src="https://ems-cust-content.s3.eu-central-1.amazonaws.com/ems-docs/create-google-oauth.webm">
</video>

### In the Element Matrix Services configuration form

Use the preset `Google` for a simplified form or use `Custom` with the following values:

- Issuer must be `https://accounts.google.com/`.
- Use the client id and secret from above.
- Discover must be turned on.
- The scopes should be `openid,profile,email`.
- Leave Subject Claim empty.
- Username attribute can be `email`. This means your Matrix addresses will include the server domain of the user's
  e-mail address.
- Display name attribute can be `name`.

## Okta

For detailed information, read
<a href="https://developer.okta.com/docs/reference/api/oidc/" target="_blank" rel="noopener noreferrer">
  Okta's guide onOpenID
</a>.

1. Create a new App. Sign-in method `OIDC - OpenID Connect` and Application type `Web Application`.
1. Choose a name for you and your users to recognize.
1. Sign-in redirect URIs: `https://my-host.ems.host/_synapse/client/oidc/callback`. Adapt the URL to match your
homeserver's address. You must use your `.ems.host` domain, even if your server uses Custom DNS.
1. Sign-out redirect URIs: `https://my-host.ems.host/_synapse/client/oidc/backchannel_logout`. Adapt the URL to match
your homeserver's address. You must use your `.ems.host` domain, even if your server uses Custom DNS.

### In the Element Matrix Services configuration form

- Choose Preset Custom.
- Issuer: `https://your-domain.okta.com`.
- Client ID: Your client ID from the Okta admin panel.
- Client secret: Your client secret from the Okta admin panel.
- Scopes: `openid,profile`.
- Leave Subject Claim empty.
- Username attribute: See below
- Display name attribute: for example, `given_name family_name`

#### Username attributes

This refers to the user's localpart in their Matrix ID (`@localpart:example.com`). The data provided in a minimally
configured Okta user is not ideal for integration with EMS. Below are some possible configuration suggestions. All
examples below use the Matrix server domain `example.com`.

Available values for username and display name are `email` (you must include `email` in Scopes), `phone_number` (you
must include `phone` in Scopes), `address`, `name`, `family_name`, `given_name`, `middle_name`, `nickname`,
`preferred_username`, `profile`, `picture`, `website`, `gender`, `birthdate`, `zoneinfo`,`locale`, and `updated_at`.
(List updated June 8, 2023. See [this](https://developer.okta.com/docs/reference/api/oidc/#scopes) document for updated
information. Available options are listed in the table under "Scopes" and after the "profile" bullet under "Scope
values").

Make sure all users that will be using your EMS server have the selected attributes set.

Option 1: Username attribute `email`. This will use the user's entire email address as their localpart. Including the
domain. It will also be encoded to be compatible with Matrix. For example, email `jane@example.com` will become
`jane=40example.com:example.com`. To use the email, you must also include `email` in Scopes.

Option 1b: We can add some logic to your OIDC config to exclude the email domain. Contact support for further details.

Option 2: Username attributes: `name`. This will use the user's full name from Okta. Note that spaces (and other
special characters) are not supported in Matrix localparts. For example, spaces will be encoded as `=20`. (I.e., `Jane
Doe` becomes `@jane=20doe:example.com`.

Option 2b: We can add some logic to replace spaces with for example underscore. Contact us for details.

Option 3: By default, usernames in Okta must be an email. But, if you have changed this behavior, you can set Username
attributes to `preferred_username` to use the username.

Note, the attribute you choose for localparts does not have to be unique. But if you, for example, set Username
attributes to `given_name`, the first Jane who sign in to your EMS server will become `@jane:example.com` and the
second Jane becomes `@jane1:example.com`.

Please contact EMS Support at <https://ems.element.io/support> to discuss your options.