Guide-Saml

SAML Single Sign-On

SAML SSO lets your organization members authenticate with Gemfury using your corporate Identity Provider (IdP). When enabled, users log in through your IdP and are automatically added to your organization.

Requirements

  • Gemfury organization account
  • Administrator access to your Identity Provider
  • IdP SAML metadata XML file

Supported Identity Providers

Gemfury works with any SAML 2.0 compliant Identity Providers (IdP) like Okta, Microsoft Entra ID (Azure AD), Google Workspace, OneLogin, JumpCloud, PingIdentity, etc.

  …

Getting Started with SAML SSO

This guide walks through enabling SAML authentication for your Gemfury organization. Setup requires two phases: initial configuration and finalization after receiving your Provider ID.

Service Provider Information

Configure your IdP with these Gemfury settings. Replace PROVIDER_ID with the identifier assigned after initial setup.

Setting Value
ACS URL https://manage.fury.io/auth/saml/PROVIDER_ID/callback
Entity ID https://manage.fury.io/auth/saml/PROVIDER_ID
Name ID Format Email or Persistent

Name ID Format options:

  • Email — Uses email address as identifier (simpler, but may break if user’s email changes)
  • Persistent — Uses an opaque identifier (recommended for stability)

Your IdP must send signed assertions and include the user’s email attribute. See IdP Configuration for specific steps to enable signing in your Identity Provider.

  …

Configuring Your Identity Provider

After setting up SAML in Gemfury, configure your IdP with the Gemfury service provider details.

Required Settings

All IdPs need these values (replace PROVIDER_ID with your assigned identifier):

ACS URL:    https://manage.fury.io/auth/saml/PROVIDER_ID/callback
Entity ID:  https://manage.fury.io/auth/saml/PROVIDER_ID

When providing metadata to Gemfury, provide the Metadata XML content. Metadata URLs and manual configuration are not yet supported.

Okta
  1. Go to Applications → Create App Integration
  2. Select SAML 2.0
  3. Configure SAML settings:
    • Single Sign-On URL: https://manage.fury.io/auth/saml/PROVIDER_ID/callback
    • Audience URI: https://manage.fury.io/auth/saml/PROVIDER_ID
    • Name ID format: EmailAddress
  4. Add attribute statement:
    • Name: email
    • Value: user.email
  5. Under SAML Settings → Advanced Settings, ensure:
    • Response is set to Signed
    • Assertion Signature is set to Signed
  6. Assign users or groups to the application
  7. Go to Sign On tab and download metadata XML (click View SAML setup instructions or Identity Provider metadata)
Microsoft Entra ID (Azure AD)
  1. Go to Enterprise Applications → New Application
  2. Select Create your own application (Non-gallery)
  3. Go to Single sign-on → SAML
  4. Edit Basic SAML Configuration:
    • Identifier: https://manage.fury.io/auth/saml/PROVIDER_ID
    • Reply URL: https://manage.fury.io/auth/saml/PROVIDER_ID/callback
  5. Verify Attributes & Claims includes email (typically user.mail or user.userprincipalname)
  6. Under SAML Certificates, click Edit and set Signing Option to Sign SAML response and assertion
  7. Download Federation Metadata XML
Google Workspace
  1. Go to Admin Console → Apps → Web and mobile apps → Add app
  2. Select Add custom SAML app
  3. Enter app name (e.g., “Gemfury”)
  4. Configure Service Provider details:
    • ACS URL: https://manage.fury.io/auth/saml/PROVIDER_ID/callback
    • Entity ID: https://manage.fury.io/auth/saml/PROVIDER_ID
    • Name ID format: EMAIL
    • Name ID: Basic Information > Primary email
  5. Map attributes:
    • Primary email → email
  6. Under Service Provider Details, ensure Signed response is checked
  7. Save the application, then download IdP metadata (available on the app details page)
  8. Enable the app for your organizational unit

Testing

Test both authentication flows to ensure complete configuration:

  …

User Provisioning

Gemfury uses just-in-time provisioning: users are added to your organization when they first log in through your IdP. No manual invitation is required, but users must initiate login themselves.

How It Works

When a user logs in through your SAML provider for the first time:

  1. Gemfury validates the SAML assertion
  2. Creates or links their Gemfury account
  3. Adds them to your organization with the appropriate role

Subsequent logins authenticate the user without changing their membership or role.

  …

Group Mapping

Gemfury can automatically assign membership roles to users based on their group claims sent by your Identity Provider in the SAML assertion. This lets you control access levels without manually assigning roles to each new user.

How It Works

Group mapping is configured with two settings on your SAML provider:

Setting Description
Group Mapping A mapping of IdP group names to Gemfury roles.
Default Role Fallback role (Download only) when no group mapping matches.

When a user logs in via SAML for the first time and is provisioned into your organization, Gemfury resolves their role as follows:

  …

Troubleshooting SAML SSO

Common issues and solutions for SAML authentication.

Error Messages

Error Cause Solution
Unauthorized Provider not active Contact support to activate your provider
Login expired Session timeout or clock drift Re-initiate SAML login; check server time sync
Invalid credentials Assertion validation failed See detailed causes below
Invalid Credentials — Detailed Causes

This error indicates SAML assertion validation failed. Check these items in order:

  1. Unsigned assertion — Assertions must be signed. Verify signing is enabled in your IdP (see IdP Configuration)
  2. Signature algorithm mismatch — Gemfury supports SHA-256. If your IdP uses SHA-1, update to SHA-256
  3. Expired assertion — Assertion timestamp outside validity window. Check clock synchronization
  4. Audience mismatch — Entity ID in IdP doesn’t match https://manage.fury.io/auth/saml/PROVIDER_ID
  5. Missing email attribute — Assertion must include email attribute
  6. Name ID format mismatch — Verify Name ID format matches your Gemfury configuration
  7. Certificate mismatch — IdP certificate was rotated but metadata wasn’t updated in Gemfury

Configuration Issues

Assertions Not Signed

Gemfury requires signed SAML assertions. In your IdP settings, enable:

  …