---
alias: operation-guide-security-portal-strategy-openidconnect
description: "OpenID Connect integration enables user authentication and identity management within the portal"
---

# OpenID Connect

The integration of **OpenID Connect**, a layer built on top of OAuth 2.0, allows the Critical Manufacturing Security Portal to establish a login session using a RESTful HTTP API to provide user identity and authentication on top of the OAuth 2.0 framework while allowing OAuth to access protected resources. All this while using a framework that is interoperable (using JSON), simple to implement and secure.

![security_portal_openidconnect_flow][security_portal_openidconnect_flow]

More information on these external guides:

* [OpenID Connect explained in plain English](https://www.onelogin.com/blog/openid-connect-explained-in-plain-english)
* [OIDC in a nutshell](https://infosec.mozilla.org/guidelines/iam/openid_connect.html)
* [AccessToken Vs ID Token Vs Refresh Token](https://www.c-sharpcorner.com/article/accesstoken-vs-id-token-vs-refresh-token-what-whywhen)

## Configuration

Available out of the box. Enable and configure it in DevOps Center during the installation, with the strategy ID (**Display Name** field, default `OpenID`), metadata URL, client ID, and extra scopes. Disabled by default. DevOps Center doesn't set a client secret, so the strategy uses PKCE. To use a client secret, configure the strategy through a customization package. See [Deployment via CmfEntrypoint](https://developer.criticalmanufacturing.com/explore/guides/customizations/securityportal/configuration/#deployment-via-cmfentrypoint) in the Developer Portal.

In this section, `<Security Portal URL>` is the public address of the Security Portal, for example `https://mes.example.com/SecurityPortal`.

### Parameters

| **Strategy type** | **Plugin**                                         |
|-------------------|----------------------------------------------------|
| `open-id-connect` | `@criticalmanufacturing/auth-plugin-openidconnect` |

Table: OpenID Connect strategy type and plugin

Each strategy entry also accepts the [common strategy properties](../security-portal-configuration/security_portal_config_securityportal.md#common-strategy-properties).

| **Parameter**             | **Required** | **Description**                                                                                                                                                                                      |
|---------------------------|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `metadataUrl`             | Yes          | OpenID Connect discovery URL of the provider, usually ending in `/.well-known/openid-configuration`.                                                                                                 |
| `redirectUrl`             | Yes          | `<Security Portal URL>/tenant/<TenantName>/login/callback`. Register the same URL in the provider.                                                                                                   |
| `clientId`                | Yes          | Client ID of the application registered in the provider.                                                                                                                                             |
| `clientSecret`            | No           | Client secret of the application. If omitted, the Security Portal uses PKCE.                                                                                                                         |
| `scopes`                  | No           | Scopes to request, as an array or a space-separated string. Default: `openid email`.                                                                                                                 |
| `openIdProviderLoginHint` | No           | MES User property sent to the provider as sign-in hint: `UserAccount`, `MailAddress`, or `Legacy`. `Legacy` (default) sends the user account if it is an email address, otherwise the email address. |

Table: OpenID Connect strategy parameters

### Example

```json
{
  "id": "OpenID",
  "type": "open-id-connect",
  "config": {
    "metadataUrl": "https://<ProviderAddress>/.well-known/openid-configuration",
    "redirectUrl": "<Security Portal URL>/tenant/<TenantName>/login/callback",
    "clientId": "<ClientID>",
    "scopes": "openid email"
  }
}
```

## Sign-In with Email Address

If the OIDC provider identifies users by email address, add the following property to the `dataSource.config` section of the tenant in `config.json` (`tenants[0].config.<TenantName>.dataSource.config`):

```json
"userAccountFallbackField": "MailAddress"
```

With this setting, the Security Portal matches the account returned by the provider against both the `UserAccount` and the `MailAddress` of the MES User.

!!! warning "Email Addresses Must Be Unique"
    If more than one MES User matches the account, through either `UserAccount` or `MailAddress`, the sign-in fails. The Security Portal logs `There is more than one User with UserAccount or MailAddress = '<account>'`.

[security_portal_openidconnect_flow]: ../../images/security_portal_openidconnect_flow.png