**Glasswall Halo** can be configured to enable **Single Sign-On** (SSO) with OpenID Connect ([OIDC](https://www.microsoft.com/en-us/security/business/security-101/what-is-openid-connect-oidc)).

SSO is an authentication method that allows users to sign in using one set of credentials to multiple independent software systems. Using SSO means a user doesn't have to sign in to every application they use.

Below is information on how to configure SSO within your Glasswall Halo solution using [Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/what-is-single-sign-on) as the identity and access management (IAM) provider.

In principle, *any* IAM solution that offers OIDC may be configured to support SSO for Glasswall Halo.

## Prerequisites for Microsoft Entra ID integration

- A Microsoft enterprise agreement for a Microsoft Entra ID account is required to enable this SSO option.
- A domain name must be configured for the Halo portal (*portal service*) to use SSO authentication.
- Azure App Registrations are required whenever SSO authentication using Microsoft Entra ID needs to be enabled.
- Three App Registrations must be created:
  - `Cdrplatform-API-access`
  - `Cdrplatform-portal-access`
  - `Cdrplatform-portal-client`
- The [attached shell script](/.attachments/create-azure-app-registrations.sh) helps create these app registrations. Enter the domain name you would like to use for the portal as an argument to the script. Example:

```bash
bash create-azure-app-registrations.sh halo.glasswall.com
```

- The enterprise application `ar-Halo-portal-client` must be granted admin consent.

---

## Configuration

### Enable Microsoft Entra ID API authentication

To enable Microsoft Entra ID based authentication, set `configuration.authenticationscheme=bearer`. Also set `tenant_id`, `api_domain` and `valid_audiences` variables while deploying the Helm chart.

**Note:** Set `valid_audiences` to the **Application (client) ID** of the `cdrplatform-api-access` app registration (found in the Azure portal under **App registrations** > **Overview**).

```sh
tenant_id=""
api_domain=""
valid_audiences=""  # Application (client) ID of the cdrplatform-api-access app registration (copy from Azure portal)
```

```sh
helm upgrade cdrplatform-api-access cdrplatform-api-access \
  --reuse-values \
  --set ingress.tls.enabled=true \
  --set ingress.tls.domain=${api_domain} \
  --set ingress.tls.secretName=tls-secret \
  --set configuration.AuthenticationScheme=Bearer \
  --set configuration.Authentication__Schemes__Bearer__ValidAudiences__0=${valid_audiences} \
  --set configuration.Authentication__Schemes__Bearer__ValidIssuer=https://sts.windows.net/${tenant_id}/ \
  --set configuration.Authentication__Schemes__Bearer__Authority=https://login.microsoftonline.com/${tenant_id}/v2.0/ \
  --atomic
```

---

### Configure SSO login for Glasswall Halo

Set `portal_domain`, `portal_client_id`, `tenant_id` variables in the commands below.  
`portal_domain` is the domain used for TLS on the portal service and is also the domain used in the `cdrplatform-portal-client` App Registration.

`portal_client_id` is the application (client) ID of the `cdrplatform-portal-client` App Registration.

`enabled_pages` includes additional pages based on which services are deployed:

- **ICAP Server**: add `IcapSettings,IcapRequests,IcapReporting`
- **Storage Monitor**: add `SharePointMonitoring,OneDriveMonitoring,OutlookMonitoring`

```sh
portal_domain=""
portal_client_id=""
tenant_id=""
# Add pages based on deployed services:
#   + ICAP Server:     IcapSettings,IcapRequests,IcapReporting
#   + Storage Monitor: SharePointMonitoring,OneDriveMonitoring,OutlookMonitoring
enabled_pages="SystemSettings\,PolicySettings\,ValidationSettings"
```

```sh
helm upgrade cdrplatform-portal cdrplatform-portal \
  --reuse-values \
  --set ingress.tls.enabled=true \
  --set ingress.tls.domain=${portal_domain} \
  --set ingress.tls.secretName=tls-secret \
  --set configuration.BackendUrl="https://${portal_domain}" \
  --set configuration.EnabledPages=${enabled_pages} \
  --set configuration.OIDC.ProviderOptions.Authority="https://login.microsoftonline.com/${tenant_id}/v2.0" \
  --set configuration.OIDC.ProviderOptions.RedirectUri="https://${portal_domain}/authentication/login-callback" \
  --set configuration.OIDC.ProviderOptions.ClientId="${portal_client_id}" \
  --set configuration.OIDC.ProviderOptions.PostLogoutRedirectUri="https://${portal_domain}/authentication/logout-callback" \
  --atomic
```

Next, the *portal access* service needs to enable SSO authentication using Microsoft Entra ID.

Set `tenant_id`, `portal_domain` and `valid_audiences` variables below.

**Note:** Set `valid_audiences` to the **Application (client) ID** of the `cdrplatform-portal-access` app registration (found in the Azure portal under **App registrations** > **Overview**).

```sh
tenant_id=""
portal_domain=""
valid_audiences=""  # Application (client) ID of the cdrplatform-portal-access app registration (copy from Azure portal)
```

```sh
helm upgrade cdrplatform-portal-access cdrplatform-portal-access \
  --reuse-values \
  --set ingress.tls.enabled=true \
  --set ingress.tls.domain=${portal_domain} \
  --set ingress.tls.secretName=tls-secret \
  --set configuration.AuthenticationScheme=Bearer \
  --set configuration.Authentication__Schemes__Bearer__ValidAudiences__0=${valid_audiences} \
  --set configuration.Authentication__Schemes__Bearer__ValidIssuer=https://sts.windows.net/${tenant_id}/ \
  --set configuration.Authentication__Schemes__Bearer__Authority=https://login.microsoftonline.com/${tenant_id}/v2.0/ \
  --atomic
```

## User roles

### To assign roles to portal users

1. Navigate to the enterprise application titled `ar-cdrplatform-portal-access` within Microsoft Entra ID.

**Note:** The screenshots use `ar-cdrplatform-perf-portal-access` as an example.

![Sso_1](/.attachments/SSO_1.png)
![Sso_2](/.attachments/SSO_2.png)

2. Navigate to the *Users and groups* section and select **Add user/group**.

![Sso_3](/.attachments/SSO_3.png)

3. Select the desired user or group, then choose the appropriate role.

![Sso_4](/.attachments/SSO_4_1.png)
![Sso_5](/.attachments/SSO_5.png)

4. Click **Assign**.

![Sso_6](/.attachments/SSO_6.png)
![Sso_7](/.attachments/SSO_7.png)

---

### To assign roles to API users

- Navigate to the enterprise application titled `ar-cdrplatform-API-access` in Microsoft Entra ID.
- From the *Users and groups* section, click **Add user/group**.
- Select the desired user or group, then choose the appropriate role.
  - [Learn more via Microsoft application management documentation](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/what-is-single-sign-on)
- Click **Assign**.