OAuth and SAML are protocols in identity and access management. OAuth is used for authorization, allowing third-party apps to access user resources securely. SAML is designed for authentication and single sign-on, facilitating user identity data exchange. OAuth is common in consumer and enterprise apps, while SAML is often used in government and enterprise environments. Both protocols can be used together for a comprehensive authentication and authorization solution.

PlexTrac supports multiple authentication methods for single-sign-on (SSO):

• OAuth: OAuth is an open standard for authorization that grants access via access tokens. OAuth authorizes an application to access your data without giving it access to your credentials.

• OpenID: OpenID Connect provides an authentication layer on top of OAuth 2.0. It addresses the lack of an authentication mechanism in OAuth and is thus a more secure solution.

• SAML: Security Assertion Markup Language (SAML) is an open standard that attempts to bridge the divide between authentication and authorization.

OAuth is used in access authorization, while SAML and OpenID Connect are used in user authentication.

Requirements

Users need an account with PlexTrac before being authorized to use an alternative sign-on method. The users' email in PlexTrac must be identical to the email address used to authenticate through the third-party tool.

Configuration Instructions

Microsoft Entra ID (formerly Azure AD) is a cloud-based identity and access management service that enables employees to access external resources.

OAuth operates through a token-based authentication system, allowing users to authorize access to Microsoft Entra ID resources without sharing credentials. The user logs in to their Microsoft Entra ID account and grants permission to a third-party application to access specific resources using an access token. Subsequently, the application utilizes this token to access the authorized resources on behalf of the user, eliminating the need for the user to re-enter their login credentials.

Configuring Microsoft Entra ID

Step 1: Log in at https://portal.azure.com/#home.

Step 2: Click Microsoft Entra ID under the "Azure services" section.

Step 3: From the Overview tab, copy the Tenant ID value and save it for later.

Step 4: Click App registrations under "Manage" on the left menu bar.

Step 5: Click New Registration.

Step 6: Provide the following information:

• Name: The user-facing display name for this application (this can be changed later)

• Supported account type: "Accounts in this organizational directory only" is the most restrictive

• Redirect URI: Choose "Web" from the pulldown menu, then enter the value composed of domain name + "/api/v2/authenticate/azure"

Step 7: Click Register at the bottom of the page.

Step 8: Copy the value for the Application (client) ID and save it for use later.

Step 9: Click Certificates and Secrets under "Manage" on the left menu bar.

Step 10: Click New client secret.

Step 11: Enter a value for Description and select the desired expiration date. Click Add.

Step 12: A new secret appears on the page under the Client Secrets tab. Copy the value for use later.

Step 13: Click Token Configuration from the left menu bar.

Step 14: Click Add optional claim.

Step 15: Choose "ID" for the Token type, then select "email" from the list of options that appears after clicking "ID." Click Add.

Step 16: Navigate back to the Microsoft Entra ID home page (see Step 2) and click Users from the left nav bar.

Step 17: Validate that the desired users exist in the list. Add new users as needed.

Step 18: Log in to PlexTrac as an admin.

Step 19: Navigate to the Admin Dashboard. Click Security under "Security & User Management."

Step 20: Click Authentication Methods under "Authentication."

Step 21: From the OAuth Providers tab, select "Azure" from the dropdown menu "Authentication Providers."

Step 22: Enter the appropriate values for the following fields:

• Provider URL: Enter "https://login.microsoftonline.com."

• Provider Tenant ID: Enter the "Directory (tenant) ID" value copied in Step 3.

• Identifier: Enter the "Application (client) ID" value copied in Step 8.

• Secret: Enter the secret value copied in Step 14.

Step 23: Toggle on the Enabled button. Click Save.

Step 24: Return to "Security & User Management" and click Users.

Step 25: Under the column header "Authentication Provider," select the desired user and change the value to "Azure."

OAuth (Open Authorization) is a standard token-based authorization framework. OAuth enables account information to be used by a third party without exposing the user's account credentials to the third party.

It provides the third-party service with an access token that authorizes the sharing of specific account information.

OpenID Connect is an identity layer built on the OAuth 2.0 protocol that permits a third-party application to obtain a user's identity information managed by a service. This functionality makes it easier for developers to authenticate users.

Clicking the card below will open further documentation for integrating PlexTrac with the following OAuth/OpenID solutions.

Additional Resources

Community Forums

Tutorials and Guides

Google OAuth (Open Authorization) is a secure authorization protocol that allows users to grant third-party applications access to their Google accounts without sharing their usernames and passwords. It is a standard authentication mechanism used by Google to provide secure, delegated access to resources on its platform, including Google Drive, Gmail, Google Calendar, and other services.

OAuth provides a token-based authentication system where users can grant access to their account data without disclosing their credentials to that service. The user first logs in to their Google account and then permits the third-party application to access specific resources using an access token. The application then uses this token to access the authorized resources on the user's behalf without needing the user to provide their login credentials again.

Configuring Google OAuth

Step 1: Log into the APIs & Services page on the Google Cloud platform:

Step 2: Click the project pulldown menu.

Step 3: Click NEW PROJECT.

Step 4: Enter a project name and click Create.

Step 5: Click the OAuth consent screen in the left nav bar.

Step 6: Validate that the user type is "internal" and click EDIT APP.

Step 7: Enter a value for the App name, select a value for the User Support email from the pulldown menu, and enter an email address for the Developer contact information. Click SAVE AND CONTINUE.

Step 8: Click ADD OR REMOVE SCOPES.

Step 9: Add the following scopes: email, profile, and openid. Click Update.

Step 10: Click Credentials from the left main menu.

Step 11: Click CREATE CREDENTIALS and then select OAuth client ID.

Step 12: Select Web application as the Application Type.

Step 13: Click ADD URI under the "Authorized JavaScript origins" header and enter the PlexTrac UI URL (i.e., http://app.plextrac.com).

Step 14: Click ADD URI from "Authorized redirect URIs," insert the PlexTrac URL, and add "/api/v2/authenticate/google" at the end of the url used in Step 10. Click CREATE.

Step 15: Copy the values provided for Your Client ID and Your Client Secret. Click Ok.

Step 16: Log in to PlexTrac as an admin.

Step 17: Navigate to the Account Admin page. Click Security under "Security & User Management."

Step 18: Click Authentication Methods under "Authentication."

Step 19: From the OAuth Providers tab, select "Google" from the dropdown menu under "Authentication Providers.

Step 20: For the Provider URL, enter https://accounts.google.com. Enter the Client ID value into the "Identifier" field and the Client Secret value obtained earlier from previous steps into the "Secret" field. Toggle on the Enabled button. Click Save.

Step 21: Return to "Security & User Management" and click Users.

Step 22: Under the column header "Authentication Provider," select the desired user and change the value to "Google."

OpenID is a decentralized authentication protocol allowing users to authenticate with multiple websites using a single login credentials. It enables users to create a single digital identity that can be used across different websites and services without creating a new account or remembering multiple usernames and passwords.

OpenID provides users with an OpenID URL, a unique identifier for their digital identity. When users log in, they are redirected to their OpenID provider's website to authenticate themselves. Once established, the OpenID provider sends a token back to the website, verifying the user's identity and allowing them to access the site.

OpenID is an open standard. It is supported by many websites and services and designed to be interoperable with other authentication protocols like OAuth.

Configuring OpenID

Step 1: Log in to PlexTrac as an admin.

Step 2: Navigate to the Account Admin page. Click Security under "Security & User Management."

Step 3: Click Authentication Methods under "Authentication."

Step 4: From the OAuth Providers tab, select "OpenID Connect" from the dropdown menu under "Authentication Providers."

Step 5: Enter values for the following:

• .well-known Configuration: The URL to the provider's .well-known configuration. The ".well-known" directory is a standardized way for web applications and services to expose metadata about themselves. One of the most commonly used files in the .well-known directory is the "openid-configuration" file, which provides metadata about the OpenID Connect provider used by the web application. The file specifies the authorization and token endpoints, the supported scopes and claims, and the public keys used to sign and verify ID tokens.

• Identifier: The identifier provided by the IDP.

• Secret: The secret value provided by the IDP.

PlexTrac requests to the provided .well-known Configuration’s authorization endpoint with the following query string parameters:

• client_id

• redirect_uri

• response_type=code

• scope=openid email

• state

Step 6: Toggle on the Enabled button. Click Save.

Step 7: Return to "Security & User Management" and click Users.

Step 8: Under the column header "Authentication Provider," select the desired user and change the value to "OpenID Connect."

Okta OAuth is a secure authorization protocol that Okta, a cloud-based identity and access management service, allows users to grant third-party applications access to their Okta resources without sharing their username and password.

OAuth provides a token-based authentication system where users can grant access to their Okta resources without disclosing their credentials to that service. The user first logs in to their Okta account and then permits the third-party application to access specific resources using an access token. The application then uses this token to access the authorized resources on the user's behalf without needing the user to provide their login credentials again.

Configuring Okta

Step 1: Log in to Okta.

Step 2: Click Applications in the admin panel.

Step 3: Click Add Application.

Step 4: Click Create New App and fill out the form. For Platform, choose "Web." For the Sign-on method, select "OpenID Connect." Click Create.

Step 5: Enter a value for the Application name and add {{ your_domain }}/api/v2/authenticate/okta to Login redirect URIs. Click Save.

Step 6: On the next page, copy values for Client ID and Client secret for later use.

Step 7: Click the Sign On tab, copy the value for Issuer, and save for later. This will be later used in PlexTrac as the Provider URL.

Step 8: Log in to PlexTrac as an admin.

Step 9: Navigate to the Account Admin page. Click Security under "Security & User Management."

Step 10: Click Authentication Methods under "Authentication."

Step 11: From the OAuth Providers tab, elect "Okta" from the dropdown menu under "Authentication Providers."

Step 12: Enter values for the fields Provider URL, Identifier, and Secret obtained from earlier steps.

Step 13: Toggle on the Enabled button. Click Save.

Step 14: Return to "Security & User Management" and click Users.

Step 15: Under the column header "Authentication Provider," select the desired user and change the value to "Okta."

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.

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.

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

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.