SAML Setup

SAML stands for Security Assertion Markup Language. It is an XML-based standard for exchanging authentication and authorization data between parties, particularly between an identity provider (IdP) and a service provider (SP).

SAML enables single sign-on (SSO) by allowing users to authenticate themselves once and access multiple services without the need to log in again for each one. SAML achieves this by exchanging digitally signed XML documents, called SAML assertions, between the IdP and SP.

When a user tries to access a resource on a service provider, the SP redirects the user to the identity provider for authentication. The IdP then verifies the user's identity and generates a SAML assertion that includes information about the user's identity and attributes. The IdP signs the assertion using its private key to ensure its authenticity and sends it back to the SP. The SP then verifies the signature using the IdP's public key and grants access to the requested resource.

Plextrac allows any SAML Identity Provider to log into the application. Multiple providers can be configured for each tenant and managed per user. For example, one user could log in with Google while another uses Okta.

This authentication method is only valid for the UI and not for authenticating with the PlexTrac API.

Requirements

SAML requires the following environment variables to be set in the PlexTrac Docker:

• PROVIDER_CODE_KEY: A secure signing key set by default in the latest version.

• CLIENT_DOMAIN_NAME: The hosting domain name, such as app.plextrac.com. Do not include HTTP(s)://.

PROVIDER_CODE_KEY is an environment variable that acts as a secure signing key. It is used in the SAML configuration within PlexTrac to facilitate secure communication between the identity provider (IdP) and PlexTrac. This key ensures that the SAML assertions exchanged during the authentication process are signed and can be trusted.

When setting up SAML for PlexTrac, the PROVIDER_CODE_KEY must be set to a secure value in the Docker compose file for the PlexTrac instance.

Users need an account with PlexTrac before being authorized to use an alternative sign-on method. The user's email in PlexTrac needs to be the same as the email the user will use to authenticate through the third-party tool. The name ID value (or similar field) found in the SAML provider must be the user's email address.

Configuring SAML

Step 1: From the Admin Dashboard, click Security and then Authentication Methods.

Step 2: Click the SAML Providers tab.

Step 3: Click Create New SAML Provider.

Step 4: Enter the information obtained through the provider setup in the appropriate fields.

1. Provider Name: Identifies the service provider used, such as Okta. This entity acts as an identity or service provider within the SAML authentication and authorization framework.

2. Allow IDP Initiated SSO: Identifies if a user can initiate SSO with the provider first without visiting PlexTrac. This is an authentication process in which the user's interaction begins with the identity provider rather than the service provider.

3. Identity Provider Single Sign-On URL: Identifies the specific endpoint provided by the IdP to initiate the SAML authentication process during SSO. When users attempt to access a service provider application, they are redirected to the IdP SSO URL to authenticate themselves.

4. Provider Issuer URL: Identifies the provider. The IdP uses the service provider's Issuer URL/entity ID to determine which metadata and configurations to use when processing authentication requests.

   The Issuer URL is typically a URL or a URN (Uniform Resource Name) that uniquely identifies the SAML entity, such as:

   • https://karbo.okta.com/example

   • http://www.okta.com/example

   • urn:amazon:webservices

   • urn:federation:MicrosoftOnline

5. X.509 Certificate: The location to paste the certificate. An X.509 certificate is a digital document adhering to the X.509 standard, which governs the structure of public key certificates. X.509 certificates validate identities, ensuring secure communication via encryption.

6. Enabled: A toggle to turn the SAML configuration on or off.

Step 5: Click Create when finished.

The new setup is listed on the SAML Providers tab.

Allowing IDP Initiated SSO

When choosing not to utilize IDP Initiated SSO with activated JIT, deactivate JIT User Provisioning before disabling IDP Initiated SSO.

Step 1: Toggle “Allow IDP Initiated SSO.”

Step 2: Enter the identity provider origin URL.

Step 3: Toggle on “JIT User Provisioning.”

Step 4: Select the desired default role for newly created users, the default classification level (if applicable), and if any users provisioned via this SAML Provider are assigned to the Default Group.

Step 5: Click Save (if updating an existing configuration) or Create when finished.