Integrate a SAML Website
On this page
Many existing websites use the Web Browser SSO Profile from the Security Assertion Markup Language (SAML) 2.0 security standard, to manage user authentication and the initiation of a secured web session. Each website then acts as a SAML Service Provider and runs a flow to authenticate users at a SAML Identity Provider (IDP).
Starting with the 10.4 release of the Curity Identity Server, you can use the Curity Identity Server as a SAML Identity Provider. The 10.4 release is a preview version that does not yet support the full feature set from the SAML 2.0 Web Browser SSO Profile. Read more about supported features in the SAML IDP Service Admin Guide. This tutorial explains how to integrate a SAML-secured website with the Curity Identity Server.
Typically, you will integrate SAML websites with the Curity Identity Server as part of a phased security modernization. To learn more about ways to safely modernize, see the Migrating from ADFS tutorial.
Create a SAML IDP Profile
To enable SAML endpoints, first ensure that you have a suitable license and then use the Admin UI's + New Profile option to create a SAML IDP Profile. Follow the profile creation wizard, provide a URL prefix such as /saml, select the Authentication Service and deploy SAML endpoints to a service role.
Next, configure basic settings and specify the key with which the Curity Identity Server signs assertions. You can use the same key that signs OAuth tokens.
Finally, enable the allowed SAML bindings for inbound SAML authentication requests from applications. Optionally, expose a metadata endpoint that SAML websites can connect to.
Typical endpoint locations are shown in the following table, where /saml is the URL prefix for the SAML profile. The metadata URL is also the default Entity ID for the Curity SAML Identity Provider unless you set an issuer override.
| Endpoint Type | Example URL |
|---|---|
| SAML SSO | https://login.example.com/saml/sso |
| SAML Metadata | https://login.example.com/saml/sso/metadata |
Resolve Attribute Values
Next, control the user attributes for issuance to SAML assertions, so that the website gets the values it needs for authorization. To issue attributes, navigate to Profiles → SAML → Attributes → Attribute Value Providers and create one or more of the following Attribute Value Providers:
| Type | Description |
|---|---|
| Data Source Attributes Provider | Read attributes from a data source, like a SQL or LDAP store. |
| Authentication Subject Attributes Provider | Read attributes that authenticators provide. |
| Authentication Context Attributes Provider | Read attributes that authentication actions provide. |
| Script Attributes Provider | Read attributes in custom ways, such as from REST APIs. |
Resolve Attributes from User Accounts
In many deployments, a standalone database stores user accounts that contain user attributes, and you can use the Data Source Attributes Provider to retrieve attribute values for authenticated users. Create data sources in the Facilities menu of the Admin UI, or use the default data source. Configure the data source's Attributes Query to return the attributes you need. Start with a simple query like the following example:
SELECT * from accounts WHERE username = :subject
Next, add attributes that use the Data Source Attributes Provider. Select an attribute name from the attribute query's results. Use any built-in or custom values stored against the user account. The following screenshot shows how to issue an email field as an attribute.
The Curity Identity Server can store arbitrary custom user attributes against user accounts. To enable this, the data schema uses a JSON attributes field. To return JSON values as top-level fields from the attributes query, use your database provider's support for querying JSON data. In PostgreSQL, for example, you can use the following syntax to retrieve the value for the given_name attribute as a top-level field.
SELECT *, attributes->'name'->'given_name' from accounts WHERE username = :subject
For the preview release, the Curity Identity Server does not support transformation procedures in SAML Attribute Providers. If you need to perform transformations you can use the other Attribute Providers to apply custom logic.
Resolve Attributes with Custom Logic
The Authentication Subject Attributes Provider, Authentication Context Attributes Provider and Script Attributes Provider provide additional ways to issue attributes to SAML assertions. To understand how to set subject or context attributes during user user authentication, see the Authentication Actions tutorials. Retrieve those values during SAML assertion issuance using the same type of configuration as the Data Source Attributes Provider.
Finally, you can use the Admin UI to organize attributes into Attribute Groups, to make it easier to reference the same sets of attributes for multiple websites.
Register a SAML Service Provider
In the Admin UI, create a SAML Service Provider and assign it a name. The name becomes the Entity ID of the SAML Service Provider. Provide the following settings to enable the website to run a SAML flow against the Curity Identity Server:
- The SAML Request Binding with which the Curity Identity Server should receive authentication requests.
- The Assertion Consumer Service URL to which the Curity Identity Server returns SAML responses.
- The Attributes or Attribute Groups to include in SAML assertions.
The following screenshot shows some example settings:
You can optionally configure various other properties. For SAML websites that sign authentication requests, configure the signing verification key under the Security tab. Use the Attributes tab to reference the attributes the website receives in SAML assertions.
Implement Authentication Workflows
SAML web clients can use any Authenticators or Authentication Actions to take control over authentication workflows in many possible ways. To get integrated, start with a simple option like the HTML Form Authenticator, where the user signs in with a username and password.
For some SAML migrations it can be important to integrate with existing authentication systems. When required, the Curity Identity Server's SDKs enable custom authenticators so that you are never blocked and can deliver your preferred login user experiences.
Integrate a SAML Website
Finally, your SAML website can integrate with the Curity Identity Server's endpoints, received SAML assertions and cryptographically verify them. To enable that, locate the public key that corresponds to the private key with which the Curity Identity Server signs SAML assertions and deploy the public key to the SAML website.
SAML website migrations often only require deployment reconfiguration, like changes to environment variables, and should require zero or minimal development work. You can run the SAML 2.0 Example Website on a local computer to understand how to implement a complete application security lifecycle.
Conclusion
The Curity Identity Server can run as a SAML Identity Provider to implement the most essential parts of the SAML 2.0 Web Browser SSO Profile. You can integrate the Curity Identity Server with existing data sources and authentication systems, control user attributes returned to websites, and deploy anywhere. You can migrate a SAML website to the Curity Identity Server as part of a phased security modernization strategy.
Join our Newsletter
Get the latest on identity management, API Security and authentication straight to your inbox.
Start Free Trial
Try the Curity Identity Server for Free. Get up and running in 10 minutes.
Start Free Trial
