Set Up SAML SSO

Security Assertion Markup Language (SAML) single sign-on (SSO) requires the following services to communicate with each other:

Service provider—The Privitar Data Security Platform (the platform) is the service provider.
Identity provider—The identity provider (IdP) is the service that manages identity information for your organization. Examples include Okta, Microsoft Entra ID (formerly Azure Active Directory), auth0, Ping, and VMware. The examples in this document use Okta as the IdP, but the instructions apply to all IdPs.
Broker—The platform supports Keycloak as the SSO broker.

Start the Broker Setup

After you configure LDAP on the platform, set up a broker to work with your identity provider. The platform supports Keycloak as the SSO broker.

Obtain the Keycloak admin password by entering the following Kubernetes command (replace <control-plane-namespace> with the name of your control plane):
```
kubectl get secret dpp-keycloak-admin-secret -n <control-plane-namespace> -o jsonpath='{.data.admin-password}' | base64 --decode
```
Copy the value for dpp-keycloak-admin-secret (generated by the DSP installation package).
Go to the Keycloak admin console in your browser at https://<domain>/keycloak/admin.
A login page appears.
Log in to the Keycloak admin console:
- Username or email—admin
- Password—[This is the value for dpp-keycloak-admin-secret that you copied in a previous step.]
Select PrivitarAuth from the Realm menu.
Click Identity providers in the left navigation.
Select SAML v2.0 from the Add provider menu.
The Add SAML provider page appears.

Redirect URI—Copy the redirect URI, which is in the following format:

https://<domain>/<service_provider>/realms/<realm_name>/broker/<alias>/endpoint

For example:

https://acme.privitar.cloud/keycloak/realms/PrivitarAuth/broker/acme-okta/endpoint

Alias—Specify a unique alias for the identity provider.
This alias will be a component of the redirect uniform resource identifier (URI).
Display name—Specify a display name for the identity provider that will show up in the user interface (UI) of the Keycloak admin console.
Service provider entity—Copy this URL for later use.
Follow the steps in Set Up an Identity Provider.

Set Up an Identity Provider

After you configure LDAP on the platform and set up a broker, you can set up an identity provider.

Log in to your identity provider.
These instructions use Okta as an example.
Go to Applications.
Click Create App Integration.
The Create a new app integration window opens.
Select SAML.
The Application type section appears.
Click Next.
The Create SAML Integration page appears.
App name—Enter a name for the app. For example, enter "Data Security Platform SAML".
App logo (optional)—Upload a logo for the app.
App visibility—Indicate whether the app icon should appear for users.
Click Next.
The Configure SAML tab appears.
Single sign-on URL—Enter the redirect URI that you noted down while following the steps in Start the Broker Setup. For example:
```
https://acme.privitar.cloud/keycloak/realms/PrivitarAuth/broker/acme-okta/endpoint
```
Select whether to use this URL for both the recipient URL and destination URL.
Audience URI (SP Entity ID)—Enter the service provider entity URL that you noted down while following the steps in Start the Broker Setup. For example:
```
https://acme.privitar.cloud/keycloak/realms/PrivitarAuth/
```
Default RelayState—Leave this field blank.
Name ID format—Select X509SubjectName.
Application username—Select Email prefix.
Update application username on—Select Create and update.
Click Save.
Click the Assignments tab.
Specify who should have access to the platform.
Click the Sign On tab.
Metadata details—Click Copy.
Click Save.
A confirmation page appears.
Follow the steps in Complete the Broker Setup.

Complete the Broker Setup

After you configure LDAP on the platform, set up a broker and an identity provider, you can now complete the broker setup.

Log in to Keycloak.
Click Identity providers.
Click the Add provider menu, and select SAML v2.0.
The Add SAML provider page appears.
SAML entity descriptor —Paste the metadata URL that you copied when completing the steps in Set Up an Identity Provider.
The rest of the fields in this section should auto-populate after you enter this URL.
Click Add.
Trust email —Select On.
First login flow —Select Automatically link existing first login flow.
Click Save.
Your identity provider now appears in the list of identity providers.
Go to Authentication > Flows.
Click browser.
Identity Provider Redirector —Click the Settings (gear) icon.
Default Identity Provider—Enter the provider alias (for example, acme-okta).
Click Save.

Complete Identity Mappings

After you configure LDAP on the platform, set up a broker and an identity provider, and complete the broker setup, you can now complete mappings between your broker and your identity provider.

In order to authenticate a user, the platform requires that the following information exists in the token coming from the identity provider:

username
email address
first name
last name

Map these to the following broker user model:

userName
email
firstName
lastName

Reference your broker's documentation for specific details. For example, if you use Keycloak as a broker, see https://www.keycloak.org/docs/latest/server_admin/#_mappers.

To complete identity mappings between your broker and your identity provider:

Log in to your identity provider.
These instructions use Okta as an example.
Go to Directory > Profile Editor > [the name of your Privitar DSP profile, for example "Data Security Platform User"]
Click Mappings.
The User Profile Mappings window appears.
Click Override with mapping.
Specify nickName as the field from which to populate the username claim.
Click Save.
A confirmation page appears.
Click Apply updates now.