SAML 2.0 Website

The Integrate a SAML Website tutorial explains how to configure the Curity Identity Server as a SAML Identity Provider. You can clone the GitHub repository link at the top of this page and run a basic SAML website when planning your own integrations.

Run a SAML Identity Provider

Follow the README instructions in the GitHub repository to spin up an instance of the Curity Identity Server and sign in to the Admin UI. Navigate to Profiles → SAML → Service Providers and inspect the settings for the SAML website.

Next, navigate to Facilities → Crypto → Keys and Cryptography → Signing and view the default keypair. The example deployment uses the default signing key to cryptographically sign SAML assertions and websites can use the default verification key when they process received SAML assertions.

Select the verification key to view its settings and click the Download PEM button. Then save the key file to the root folder of the GitHub repository so that the example website can load it.

Run the SAML-Secured Website

Next, follow the README instructions to run the example website, which uses Node.js and a SAML security library. The website first presents an unauthenticated view. When the user clicks Sign In, a SAML flow runs, that uses the HTTP Redirect Binding to connect to the SAML SSO endpoint of the Curity Identity Server.

The Curity Identity Server processes the SAML request and receives a SAML authentication request that provides the Entity ID of the SAML website. The Curity Identity Server checks that the request references a registered SAML Service Provider and then runs a user authentication workflow. The example deployment uses a simple HTML Form authenticator and a fixed user account with a username of demouser and a password credential of Password1.

After successful user authentication, the Curity Identity Server posts a SAML response to the SAML website. The SAML security library processes the response and cryptographically verifies the signed SAML assertion using its public key. The website then receives and renders user attributes from the response's SAML assertion.

The use of user attributes demonstrates that you can issue any built-in or custom attribute from user accounts to SAML assertions, so that SAML websites have the values they need for authorization. The deployed user account contains a custom region attribute in addition to built-in attributes.

The example website stores user attributes from the SAML assertion in a session store and then begins a web session that uses an HTTP Only session cookie. The website can run a complete security lifecycle, including a basic option to sign out the user, which ends the web session and expires the session cookie.

Configuration Settings

The example website uses configuration settings from a .env file. Often, existing SAML websites use environment variables for configuration settings, in which case a migration to the Curity Identity Server only requires environment variable updates. This type of job is often done by operational teams and may not require any code changes to the SAML website.

PORT='3000'
SAML_SSO_ENDPOINT='http://localhost:8443/saml/sso'
SAML_METADATA_ENDPOINT='http://localhost:8443/saml/sso/metadata'
CALLBACK_URL='http://localhost:3000/login/callback'
ENTITY_ID='saml-web-client'
ASSERTION_VERIFICATION_CERTIFICATE='-----BEGIN CERTIFICATE-----\nMIIDUzCCAjugAwIBAgIJ ...'
COOKIE_SECRET='34c15d7d60eefc8b46b3afaf6a6f981fd5d5...'

SAML Security Code

The SAML website uses Node.js and Express, along with the Passport-SAML security library. Integrating SAML only requires minimal code, to apply configuration settings to the security library.

function initializeSaml(app: Application) {

    const options: SamlConfig = {
        issuer: this.configuration.entityId,
        entryPoint: this.configuration.samlSsoEndpoint,
        callbackUrl: this.configuration.callbackUrl,
        audience: this.configuration.entityId,
        identifierFormat: null,
        cert: this.configuration.assertionVerificationCertificate,
        forceAuthn: true,
    };

    passport.use(new Strategy(options, this.receiveUserAttributes));
    app.use(passport.initialize());
}

The website receives the SAML assertion after the library has cryptographically verified it. The website can then make any additional validation checks and return a user object containing user attributes from the SAML assertion.

private receiveUserAttributes(profile: Profile | null | undefined, done: VerifiedCallback): any {

    const user = {
        nameID: profile['nameID'],
        attributes: profile.attributes || [],
    };

    return done(null, user);
}

The security library updates the Express Request object, which the website's routes can use for authorization or to return user attributes to frontend views for display.

function renderView(request: Request, response: Response) {

    const model: any = {
        isAuthenticated: request.isAuthenticated(),
        user: request.user || null,
        errorMessage: null,
    };
    
    const errorMessage = (request.session as any)?.errorMessage;
    if (errorMessage) {
        model.errorMessage = errorMessage;
    }
    
    response.render('index', { model });
}

Since the above code is standards-based, you can reconfigure the website and integrate it with other SAML Identity Providers, like Microsoft ADFS, without code changes.

Migration Considerations

There are a number of additional aspects that architects may need to think about when planning SAML migrations to the Curity Identity Server. The Migrating from Microsoft ADFS tutorial explains the approaches you can use, to perform safe migrations in a phased manner, rather than needing to use a big-bang approach.

For example, it is possible to integrate with existing data sources for user accounts and user credentials, or integrate with existing authentication systems using plugins. Architects or developers could use the example SAML website to test integrations rather than needing to change code in real websites.

The example website uses a Microsoft SQL Server deployment of the Curity Identity Server's native database to store user accounts and user credentials. This shows that after integrating with the Curity Identity Server you no longer need to depend on Windows infrastructure like Active Directory and can instead follow a cloud native approach.

Conclusion

Integrating a SAML website into the Curity Identity Server enables phased security modernizations. The impact on the website code should be minimal, requiring only changes to configuration settings, so you may be able to migrate without requiring work from development teams.

The SAML website can receive any existing user attributes in SAML responses, to ensure business continuity. After integration, you can use the advanced user authentication capabilities of the Curity Identity Server to provide a modern login user experience for website users.

Join our Newsletter

Get the latest on identity management, API Security and authentication straight to your inbox.

Email

Subscribe

I agree to Curity's Privacy Policy

Start Free Trial

Try the Curity Identity Server for Free. Get up and running in 10 minutes.

Start Free Trial