# Single sign-on (SSO) Enterprise
Single sign-on (SSO) is a Memgraph enterprise feature that provides authorization and authentification to your database.
Memgraph supports two types of SSO methods: [OpenID Connect (OIDC + OAuth
2.0)](#openid-connect-oidc) and [SAML](#saml), and three identity providers -
Microsoft Azure (Entra ID), Okta, and custom identity provider (e.g. IdentityServer, Keycloak).
To set up SSO on Memgraph Lab, you must configure the
appropriate [environment variables](https://memgraph.com/docs/memgraph-lab/configuration).
> **Info**
>
> **Enterprise**: To enable Single sign-on feature, you need to [enable Memgraph
> Enterprise license](https://memgraph.com/docs/database-management/enabling-memgraph-enterprise).
> **Info**
>
> **Environment**: Single sign-on is not supported on the desktop version of
> Memgraph Lab. It is available exclusively when the Lab is started in a Docker
> environment.
## OpenID Connect (OIDC)
The setup of OIDC (which includes OAuth 2.0) is configured with several environment
variables for any of the providers: Microsoft Entra ID, Okta, and custom identity provider.
### Entra ID
To set up OIDC for Microsoft Azure,
[follow the official guide](https://learn.microsoft.com/en-us/entra/architecture/auth-oidc#implement-oidc-with-microsoft-entra-id) and
[register an application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app).
To enable OIDC for the Microsoft Entra ID identity provider, make sure to
[assign the following environment
variables](https://memgraph.com/docs/memgraph-lab/configuration#changing-configuration) when hosting
Memgraph Lab:
```bash
AUTH_OIDC_ENTRA_ID_IS_ENABLED=true
AUTH_OIDC_ENTRA_ID_DISPLAY_NAME='Entra ID'
AUTH_OIDC_ENTRA_ID_AUTHORIZATION_URL=
AUTH_OIDC_ENTRA_ID_TOKEN_URL=
AUTH_OIDC_ENTRA_ID_USER_INFO_URL=
AUTH_OIDC_ENTRA_ID_CLIENT_ID=
AUTH_OIDC_ENTRA_ID_CLIENT_SECRET=
AUTH_OIDC_ENTRA_ID_CALLBACK_URL=http:///auth/providers/oidc-entra-id/callback
AUTH_OIDC_ENTRA_ID_PKCE_IS_ENABLED=true
AUTH_OIDC_ENTRA_ID_SCOPE='$YOUR_CLIENT_ID/.default openid offline_access'
```
The empty values can be found on the Azure dashboard under the created app registration.
### Okta
To set up OIDC for Okta, follow the [official guide](https://developer.okta.com/docs/guides/implement-grant-type/authcode/main/)
and make sure to set up a [custom authorization server](https://developer.okta.com/docs/concepts/auth-servers/#custom-authorization-server).
To enable OIDC for the Okta provider, make sure to [assign the following
environment variables](https://memgraph.com/docs/memgraph-lab/configuration#changing-configuration) when
hosting Memgraph Lab:
```bash
AUTH_OIDC_OKTA_IS_ENABLED=true
AUTH_OIDC_OKTA_DISPLAY_NAME=Okta
AUTH_OIDC_OKTA_AUTHORIZATION_URL=https://xxx.okta.com/oauth2/v1/authorize
AUTH_OIDC_OKTA_TOKEN_URL=https://xxx.okta.com/oauth2/default/v1/token
AUTH_OIDC_OKTA_CLIENT_ID=
AUTH_OIDC_OKTA_CLIENT_SECRET=
AUTH_OIDC_OKTA_CALLBACK_URL=http:///auth/providers/oidc-okta/callback
AUTH_OIDC_OKTA_PKCE_IS_ENABLED=true
AUTH_OIDC_OKTA_SCOPE='openid offline_access'
```
The empty values can be found on the Okta admin panel dashboard under the created app.
### Custom identity provider
To configure OpenID Connect (OIDC) with a custom identity provider, refer to
the official documentation provided by your chosen provider.
If you're using **Keycloak**, after creating a realm, you will find all the
necessary OIDC details under the Endpoints section.
To enable OIDC authentication in Memgraph Lab, be sure to
[set the required environment variables](https://memgraph.com/docs/memgraph-lab/configuration#changing-configuration)
when deploying the application.
Here is an example configuration for integrating Keycloak as the identity provider:
```bash
AUTH_OIDC_CUSTOM_IS_ENABLED=true
AUTH_OIDC_CUSTOM_DISPLAY_NAME=Keycloak
AUTH_OIDC_CUSTOM_AUTHORIZATION_URL=https:///realms/myrealm/protocol/openid-connect/auth
AUTH_OIDC_CUSTOM_TOKEN_URL=https:///realms/myrealm/protocol/openid-connect/token
AUTH_OIDC_CUSTOM_CLIENT_ID=
AUTH_OIDC_CUSTOM_CLIENT_SECRET=
AUTH_OIDC_CUSTOM_CALLBACK_URL=http:///auth/providers/oidc-custom/callback
AUTH_OIDC_CUSTOM_PKCE_IS_ENABLED=true
AUTH_OIDC_CUSTOM_SCOPE='openid offline_access'
```
### PKCE Support in OIDC SSO
PKCE (Proof Key for Code Exchange) support was introduced in
Lab version `3.4`. You can enable PKCE for your OIDC SSO
integration by setting the environment variable
`AUTH_OIDC_ENTRA_ID_PKCE_IS_ENABLED`, `AUTH_OIDC_OKTA_PKCE_IS_ENABLED`,
or `AUTH_OIDC_CUSTOM_PKCE_IS_ENABLED` to true.
By default, the PKCE code verifier is securely stored in Lab
for 5 minutes. This timeout is controlled by the
`AUTH_SSO_STATE_EXPIRY_SEC` environment variable. If you're
running Lab in high-availability (HA) mode, ensure your load
balancer uses sticky sessions so that each user continues
interacting with the same Lab instance throughout the login
flow.
Note that all SSO credentials (e.g., client ID, client secret)
are securely managed within the Lab backend and are never
exposed to the browser - eliminating the risk of credential
leakage through frontend code.
While we recommend using both the client ID and PKCE together,
it's also possible to omit the client ID when PKCE is enabled.
To allow this, configure your Azure Entra ID application to use
the "Mobile and Desktop Applications" platform.
### Session expiry in OIDC SSO
In OIDC, a user's Lab session remains active as long as the current
access token and ID token have not expired. Lab will automatically
refresh the session by using a refresh token to obtain new access
and ID tokens before they expire.
To receive a refresh token from your identity provider, ensure the
OIDC scope includes `offline_access` for the specific provider:
- `AUTH_OIDC_ENTRA_ID_SCOPE`
- `AUTH_OIDC_OKTA_SCOPE`
- `AUTH_OIDC_CUSTOM_SCOPE`
Without `offline_access` in the scope, Lab won't receive a refresh
token and cannot renew tokens, so the user's session will end when
the access/ID tokens expire.
## SAML
You can integrate Single sign-on (SSO) using SAML protocol for
Microsoft Entra ID, Okta and/or custom identity provider. Check the
details for each identity provider down below.
### Entra ID
The setup consists of two steps: creating a new app registration through the
Microsoft Entra ID portal and then filling out the Lab environment variables
for a complete integration.
#### Register new application
On the Microsoft Entra ID portal, make sure to create a new App registration.
You will need to fill out the application name and the redirect URI. The type
of the redirect URI should be "Web" and the value should be in the form:
`://:/auth/providers/saml-entra-id/callback`. If
your Lab is on `localhost:3000`, then the full URL is `http://localhost:3000/auth/providers/saml-entra-id/callback`.
If your Lab is deployed on some other domain (e.g. `my.domain.com` with SSL) then
the URL should be `https://my.domain.com/auth/providers/saml-entra-id/callback`.
> Note: A value for the "Redirect URI" field will be the same one for the
> Lab environment variable `AUTH_SAML_ENTRA_ID_CALLBACK_URL`.
Check the screenshot below for a reference.
If you already have an app registration, just make sure to add a new Redirect URI to
your existing app registration.
#### Set up Lab integration
Once the app registration is ready, you have all the required values for a full
integration. You will need two fields:
* **Application (client) ID** - shown in the app "Essentials" list.
* **SAML sign-on endpoint** - shown in the list after you click on "Endpoints".
To [configure the Lab](https://memgraph.com/docs/memgraph-lab/configuration#changing-configuration) for
the Entra ID SSO SAML integration, make sure to fill out the following
environment variables:
Required:
* `AUTH_SAML_ENTRA_ID_IS_ENABLED=true` - to enable SAML via Entra ID. The
default is `false`.
* `AUTH_SAML_ENTRA_ID_ENTRY_POINT=https://...` - value from the "SAML sign-on endpoint" on
in the "Endpoints" list. The entry point usually ends up with `.../saml2`, e.g.
`https://login.microsoftonline.com/651mem6g-25ra-4ph2-me52-23mg24r906aph/saml2`.
* `AUTH_SAML_ENTRA_ID_CALLBACK_URL=http://...` - SAML redirect URI used when creating
an app integration on Entra ID, it should contain the lab host and port along with
the URL path `/auth/providers/saml-entra-id/callback`, e.g.
`http://localhost:3000/auth/providers/saml-entra-id/callback`.
* `AUTH_SAML_ENTRA_ID_APP_ID=` - application ID is shown in the app "Essentials" list,
e.g. `651mem6g-25ra-4ph2-me52-23mg24r906aph`.
Optional:
* `AUTH_SAML_ENTRA_ID_DISPLAY_NAME=` - the display name of the SSO integration on the
Lab UI. The default value is `Entra ID` so the UI will be `Sign in with Entra ID`.
### Okta
The set up consists of two steps: creating an application through Okta admin
interface and then filling out the Lab environment variables for a complete
integration.
#### Create Okta application
To set up SAML with Okta, open up the Okta admin interface and
create a new app integration. For a "Sign-in method" select SAML 2.0
and click "Next".
In the second step of SAML set up, set the following value for the
"Single-sign on URL" input: `://:/auth/providers/saml-okta/callback`.
If your Lab is on `localhost:3000`, then the full URL
is `http://localhost:3000/auth/providers/saml-okta/callback`. If your Lab
is deployed on some other domain (e.g. `my.domain.com` with SSL) then
the URL should be `https://my.domain.com/auth/providers/saml-okta/callback`.
> Note: A value for "Single-sign on URL" field will be the same one for the
> Lab environment variable `AUTH_SAML_OKTA_CALLBACK_URL`.
For the field "Audience URI (SP Entity ID)" you can input just the
`://:/` part. Check the screenshot above for
a reference. You are free to set up and configure all other fields
however you like.
#### Set up Lab integration
Once the app integration is created, click on "Settings" and expand
the "SAML details". In there, you will find two values, "Sign on URL" and
"Issuer". You will need both values for the Lab configuration.
To [configure the Lab](https://memgraph.com/docs/memgraph-lab/configuration#changing-configuration) for
the Okta SSO SAML integration, make sure to fill out the following environment
variables:
Required:
* `AUTH_SAML_OKTA_IS_ENABLED=true` - to enable SAML via OKTA. The
default is `false`.
* `AUTH_SAML_OKTA_ENTRY_POINT=https://...` - value from the "Sign on URL" on
SAML settings. The entry point usually ends up with `.../sso/saml`, e.g.
`https://my.okta.com/app/my-application/exke6ubrkbz/sso/saml`.
* `AUTH_SAML_OKTA_CALLBACK_URL=http://...` - SAML callback URL used when creating
an app integration on Okta, it should contain the lab host and port along with
the URL path `/auth/providers/saml-okta/callback`, e.g.
`http://localhost:3000/auth/providers/saml-okta/callback`.
* `AUTH_SAML_OKTA_ISSUER=http://www.okta.com/...` - value from the "Issuer" on
SAML settings, e.g. `http://www.okta.com/exke6ubrkbz`.
Optional:
* `AUTH_SAML_OKTA_DISPLAY_NAME=` - the display name of the SSO integration on the
Lab UI. The default value is `Okta` so the UI will be `Sign in with Okta`.
### Custom identity provider
To configure SAML with a custom identity provider, refer to the official documentation
provided by your chosen provider.
If you're using **Keycloak**, after creating a realm, you will find all the
necessary SAML details under the Endpoints section.
To enable SAML authentication in Memgraph Lab, be sure to
[set the required environment variables](https://memgraph.com/docs/memgraph-lab/configuration#changing-configuration)
when deploying the application.
Here is an example configuration for integrating Keycloak as the identity provider:
```bash
AUTH_SAML_CUSTOM_IS_ENABLED=true
AUTH_SAML_CUSTOM_DISPLAY_NAME=Keycloak
AUTH_SAML_CUSTOM_ENTRY_POINT=https:///realms/myrealm/protocol/saml
AUTH_SAML_CUSTOM_ISSUER=http:///realms/myrealm
AUTH_SAML_CUSTOM_CALLBACK_URL=http:///auth/providers/saml-custom/callback
```
#### Registering custom CA certificates
If your custom Identity Provider uses self-signed certificates, Lab may
block access to unverified resources with the error **"unable to get local issuer certificate"**.
To resolve this, Lab needs to recognize those certificates. Make sure
to mount them and register them in the Docker container using the following
environment variable:
```
docker run \
...
-e NODE_EXTRA_CA_CERTS=path/to/ca-certificates-mounted-in-docker-container.crt
memgraph/lab
```