The easiest way to implement SAML in any app

Implementing SAML on your own can be quite a challenge. 

It demands a lot of development work and specialized knowledge of the SAML spec. You’ll need to know how to read and parse XML assertions, respond to SAML requests, and most importantly, secure your integration against threats like XML injections, replay attacks, and XML signature wrapping.

Luckily, you don’t have to tackle all this by yourself. 

In this article, we’ll show you a much easier way of adding SAML support to any app using the WorkOS SSO API. It’s one of the most straightforward methods to get SAML up and running in your app.

What is SAML, and when should you implement it?

Secure Assertion Markup Language (SAML) is an XML-based standard for exchanging authentication and authorization data between parties, specifically between an identity provider and a service provider.  

It’s one of the most popular Single Sign-On (SSO) protocols. It allows users to log in once and access multiple applications without re authenticating.

You should implement SAML when you want to support legacy enterprise SSO in your app. It’s been around for decades, and most large organizations still use it.

Why use a SAML provider and how to pick one?

SAML providers, like WorkOS, handle identity and access management, making it easier by managing the technical details of the SAML protocol for you.

Here are some of the things a provider can offer:

• Ready-to-use tools: Providers offer SDKs, APIs, and dashboards that simplify the integration process and significantly reduce engineering time.
• Enhanced security: SAML providers can afford to have dedicated experts who help ensure the SAML setup is correct from the start, reducing the risk of vulnerabilities from incorrect configurations.
• Compliance assurance: SAML providers ensure their solutions meet strict regulations like HIPAA and GDPR, making compliance easier for you.
• Cost efficiency: Developing and maintaining an in-house SAML solution is expensive. SAML providers offer a more cost-effective alternative by reducing development, maintenance, security testing, and compliance costs.

When you're looking for a SAML provider, focus on these key aspects to find the right fit for your needs:

• Easy integration: Opt for providers with well-documented SDKs, APIs, and user-friendly dashboards. These tools make it easier to integrate the service into your existing setup.
• Industry compliance: Verify that the provider adheres to compliance standards relevant to your industry.
• Customization: Check if you can customize the login interface and user interactions to match your brand.
• Support: Evaluate the support the provider offers. Good support can be a lifesaver, especially in the integration phase and in the event of security issues.
• Cost: Review the pricing structure carefully. Does it fit your budget?

Implement SAML with WorkOS

In the following sections, we'll guide you step-by-step on how to use the WorkOS API to configure a new SAML connection and build an SSO authentication workflow for your application.

Once you’ve set up the API for SAML, you can easily extend it to support OpenID Connect as well as other enterprise features like SCIM (System for Cross-domain Identity Management) and JIT (Just-In-Time) provisioning.

Before we begin, you’ll need to sign up for a WorkOS account if you don’t already have one.

Step 1: Get the API key and Client ID

To authenticate the API calls made from your application to WorkOS, you’ll need an API Key and Client ID. Get them from your WorkOS dashboard and securely store them as managed secrets.

	
WORKOS_API_KEY='sk_example_123456789'
WORKOS_CLIENT_ID='client_123456789'
	

Step 2: Configure the SAML connection

Each identity provider requires specific information to create and configure a new connection. This information can differ from provider to provider.

At WorkOS authentication methods, like SSO, are configured at the organization level. To configure your SSO connection go to the dashboard, select your organization, and click “Configure manually”.

Select the provider you want to connect to from the list of available integrations or choose the custom SAML connection if you’re connecting to a generic provider. Then follow the provided configuration instructions.

Step 3: Add an endpoint to initiate SSO

After you configure and test the SAML connection you are ready to start authenticating users using it. 

To start the authentication flow, call the WorkOS API to get an authorization URL. This URL will redirect the user to their IdP's login page.

	
curl https://api.workos.com/sso/authorize -G \
  -d response_type=code \
  -d client_id=client_id \
  -d redirect_uri=https://your-app.com/callback \
  -d state=dj1kUXc0dzlXZ1hjUQ== \
  -d organization=org_id
	

You should set the organization_id parameter to the ID of the organization you created earlier.

You should also include the following information in the request:

• response_type: Use the value code.‍
• client_id: The one you got from the WorkOS dashboard.
• ‍redirect_uri: Your app's URL where WorkOS will redirect the user after authentication.
• ‍state: An optional parameter used to persist information between redirects.

You’ll need to add the redirect_uri you’re using to the list of allowed redirect URIs for your app on the Redirects page of your dashboard. Without it, your users won’t be able to sign in.

Step 4: Get the user profile

After the user authenticates successfully, WorkOS generates an authorization code and includes it as a code query parameter in your redirect URI. Your application will use this code to retrieve the user’s profile.

For example, if your redirect URI is https://your-app.com/callback WorkOS will include the code parameter and an optional state parameter in the URL like this:

	
https://your-app.com/callback?code=01E2RJ4C05B52KKZ8FSRDAP23J&state=dj1kUXc0dzlXZ1hjUQ==
	

You can now exchange this code for the user’s profile and an access token:

	
curl -X POST "https://api.workos.com/sso/token" \
  -d 'client_id=client_123456789' \
  -d 'client_secret=sk_example_123456789' \
  -d 'grant_type=authorization_code' \
  -d 'code=01E2RJ4C05B52KKZ8FSRDAP23J'
	

The client_secret is the API key you generated from your dashboard.

This request returns an object containing the access token and the user’s profile. You can exchange an access token for a user profile, but typically, there's no need to do so again since the profile is already provided. 

However, if your authentication flow requires an additional endpoint for retrieving user data, you can use it; just know that the token expires a few minutes after it’s created (you can get a new one if you need to by using a refresh token).

Once you get your user data, you can establish a session in your app and use the profile data you received to personalize your app's UI for your user.

Next steps

Want to add SSO support that goes beyond a simple SAML connection? WorkOS allows you to connect to dozens of identity providers like Microsoft Entra, Okta, and any other identity provider that supports OIDC or SAML, complete with session management and user provisioning features.

With WorkOS, you can get enterprise-grade SSO up and running in your app within minutes and start closing those enterprise deals.

• Get started fast: With SDKs in every popular language, easy-to-follow documentation, and Slack-based support, you can implement SSO in minutes rather than weeks.
• Support every protocol: With OAuth 2.0 integrations to popular providers like Google and Microsoft, compatibility with every major IdP, and full support for custom SAML/OIDC connections, WorkOS can support any enterprise customer out of the box.
• Avoid the back-and-forth: WorkOS’s Admin Portal takes the pain out of onboarding your customers’ IT teams and configuring your app to work with their identity provider.
• Pricing that makes sense: Unlike competitors who price by monthly active users, WorkOS charges a flat rate for each company you onboard — whether they bring 10 or 10,000 SSO users to your app.

Explore Unified SSO by WorkOS.