# Single Sign-On (SSO) in Azure

{% hint style="info" %}
**Syntho beta feature**
{% endhint %}

## Introduction

To set up Single Sign-On (SSO), adjustments will have to be made to the application called **backend**. The exact place where you need to make changes will depend on your method of deployment (Kubernetes or Docker Compose).

### Kubernetes (Helm chart)

The mentioned environment variables can be added to the Helm chart under the YAML path of `backend.env`. An example of this is:

```yaml
backend:
  env:
    SSO_PROVIDER: Azure
    SSO_CLIENT_ID: <your-client-id>
    SSO_CLIENT_SECRET: <your-client-secret>
    SSO_TENANT_ID: <Azure tenant-id>
    USERNAME_PASSWORD_LOGIN_ENABLED: True
```

### Docker Compose

In the case of using Docker Compose, the Docker Compose file will need to be adjusted. The backend application can again be adjusted here, in this case, additional environment variables will need to be added directly to the existing list. An example of this:

```yaml
version: '3'

services:
  backend:
    image: ${BACKEND_IMAGE}
    restart: on-failure
    environment:
      ...
      SSO_PROVIDER: Azure
      SSO_CLIENT_ID: <your-client-id>
      SSO_CLIENT_SECRET: <your-client-secret>
      SSO_TENANT_ID: <Azure tenant-id>
      USERNAME_PASSWORD_LOGIN_ENABLED: "True"
```

## Username and password login

By default, Syntho users can log in using their username and password. To disable logging in with username and password, set the environment variable `USERNAME_PASSWORD_LOGIN_ENABLED` to `False`.

## Single Sign-On

Syntho supports signing in using external identity providers. Use the provider-specific documentation for setting up SSO for your identity provider or use the OpenID Connect provider in case your provider is not listed below.

#### OpenID Connect

Consult the documentation of your identity provider to configure access by external applications.

When configuring access for Syntho, set the callback (redirect) URL to `https://<my-syntho-domain>/api/v1/oidc/callback/`.

Provide the following environment variables when deploying Syntho:

* `SSO_PROVIDER=generic`
* `SSO_CLIENT_ID=<your-client-id>`
* `SSO_CLIENT_SECRET=<your-client-secret>`
* `SSO_AUTHORIZATION_ENDPOINT=<your-authorization-endpoint>`
* `SSO_TOKEN_ENDPOINT=<your-token-endpoint>`
* `SSO_USER_ENDPOINT=<your-user-endpoint>`
* `SSO_JWKS_ENDPOINT=<your-jwks-endpoint>`

#### Azure

First, register Syntho as an application in the [Azure Active Directory Portal](https://aad.portal.azure.com/):

1. Select Azure Active Directory, then go to App registrations and select New registration

<figure><img src="https://content.gitbook.com/content/U61B9DqtWCNO3Z30vnjh/blobs/UIU43gVez2oXvBCHPb5C/sso_azure_1.png" alt=""><figcaption></figcaption></figure>

2. Enter a name, for example Syntho. For Redirect URI, select Web and enter the url that points to the `/api/v1/oidc/callback/` endpoint on your Syntho deployment.

<figure><img src="https://content.gitbook.com/content/U61B9DqtWCNO3Z30vnjh/blobs/HeqhtCtNjOshbgDfmKyB/sso_azure_2.png" alt=""><figcaption></figcaption></figure>

3. Copy the "Application (client) ID" and "Directory (tenant) ID", these values are used later.

<figure><img src="https://content.gitbook.com/content/U61B9DqtWCNO3Z30vnjh/blobs/T0FLPtn7ybgsD55qnvYT/sso_azure_3.png" alt=""><figcaption></figcaption></figure>

4. Click on "Certificates & secrets", and select "New client secret". Enter a name, for example Syntho, select an expiration and click "Add"

<figure><img src="https://content.gitbook.com/content/U61B9DqtWCNO3Z30vnjh/blobs/8KsbxSLviCknKVbcp6oU/sso_azure_4.png" alt=""><figcaption></figcaption></figure>

5. Copy the client secret value. This value will only be visible once. If you lost the value, remove the secret and create a new one.

<figure><img src="https://content.gitbook.com/content/U61B9DqtWCNO3Z30vnjh/blobs/aMuQSazLpaY4fhiD21kB/sso_azure_5.png" alt=""><figcaption></figcaption></figure>

6. In the left menu, select "API permissions", then click "Add a permission"

<figure><img src="https://content.gitbook.com/content/U61B9DqtWCNO3Z30vnjh/blobs/rT944blj4O6SlP2mMlFx/sso_azure_6.png" alt=""><figcaption></figcaption></figure>

7. Select "Microsoft Graph"

<figure><img src="https://content.gitbook.com/content/U61B9DqtWCNO3Z30vnjh/blobs/vOXUP1tepPnGVXOqHqQb/sso_azure_7.png" alt=""><figcaption></figcaption></figure>

8. Select "Delegated Permissions"

<figure><img src="https://content.gitbook.com/content/U61B9DqtWCNO3Z30vnjh/blobs/b6i5KVfUDIy4GJsPmSEz/sso_azure_8.png" alt=""><figcaption></figcaption></figure>

9. Add the following permissions, then select "Add permissions"

* OpenId permissions
  * email
  * offline\_access
  * openid
  * profile
* GroupMember
  * GroupMember.Read.All
* User
  * User.Read

<figure><img src="https://content.gitbook.com/content/U61B9DqtWCNO3Z30vnjh/blobs/hSp9Uy4xrgWMkHD7OK8s/sso_azure_9.png" alt=""><figcaption></figcaption></figure>

10. Select "Grant admin consent for 'your directory'"

<figure><img src="https://content.gitbook.com/content/U61B9DqtWCNO3Z30vnjh/blobs/4jwmcBX1bURTxppczqZj/sso_azure_10.png" alt=""><figcaption></figcaption></figure>

11. After granting admin consent, all permissions should have a green checkmark.

<figure><img src="https://content.gitbook.com/content/U61B9DqtWCNO3Z30vnjh/blobs/YVXCaGrhAKRuOCRSHyXk/sso_azure_11.png" alt=""><figcaption></figcaption></figure>

After registering Syntho in Azure, set the following environment variables:

* `SSO_PROVIDER=Azure`
* `SSO_CLIENT_ID=<Azure Client ID>`
* `SSO_CLIENT_SECRET=<Azure Client Secret>`
* `SSO_TENANT_ID=<Azure Tenant ID>`

#### Groups

{% hint style="info" %}
**Upcoming feature**
{% endhint %}

When your identity provider supports groups, these groups will be automatically created in Syntho when a user signs in using the identity provider. These groups can be used for assigning workspace permissions.

Groups coming from the identity provider can be filtered using the `SSO_GROUP_FILTER_REGEX` environment variable. When this environment variable is set, only groups matching the provided regular expression will be created in Syntho.

#### Administrator access

If Single Sign-On is enabled, users can become administrators by setting the environment variable `SSO_ADMINS`. This environment variable expects a comma-separated list of e-mail addresses. When a user logs in to Syntho for the first time with their Single Sign-On provider, if their e-mail address matches one of the e-mail addresses in the environment variable, the created user will become administrator.

Note that becoming administrator via this environment variable only happens on the first login and not on consecutive logins. This is to prevent needing to redeploy Syntho to prevent users becoming administrator again on consecutive logins.

## Limitations

* **Provider support:** Azure AD is supported. Generic OpenID Connect is supported as well.
* **Scope of SSO:** SSO can be used for logging into the Syntho platform but not for database connections. For database access, you'll still need to use a traditional username and password.

Being aware of these limitations will help you better understand the scope and restrictions of using Single Sign-On with Syntho.