Migrating from Microsoft Active Directory Federation Services
On this page
Many organizations have existing websites that base security on the Web Browser SSO Profile from the Security Assertion Markup Language (SAML) 2.0 standard. Websites integrate with a SAML Identity Provider (IDP) and receive a SAML assertion that contains user attributes. Websites uses a SAML security library to cryptographically verify the SAML assertion, then apply authorization based on the assertion's user attributes.
The SAML 2.0 security standard dates from 2005 and various identity systems implement the standard. One such provider is Microsoft Active Directory Federation Services (ADFS), which added support for SAML 2.0 in its Windows Server 2008 release. In ADFS you store user accounts in an on-premise Active Directory store. To issue SAML assertions, the IDP reads user attributes from Active Directory.
Modernize Security and Infrastructure
Many SAML identity systems are no longer maintained or provide the best features for organizations. The following list provides a high-level overview of the main behaviors organizations are likely to need:
- Use OAuth 2.0 and OpenID Connect for the most up to date security protocols.
- Run API architectures that use access tokens for authorization.
- Implement sophisticated user authentication workflows with modern login user experiences.
- Use a cloud native approach to productively manage infrastructure.
- Deploy identity data to your preferred locations to manage data sovereignty.
Many organizations use Active Directory to secure logins to employee workstations, but are likely to prefer a different solution for customer-facing applications. To enable modernization, organizations can migrate from ADFS to a Customer Identity and Access Management (CIAM) system, like the Curity Identity Server, which implements both the SAML Identity Provider and OAuth Authorization Server roles.
Often, the driver for modernization is a new customer experience or API product that uses the latest identity architecture. However, an organization cannot use a big-bang approach and modernize all SAML web applications at once. Therefore, the organization needs to plan a safe migration. The following sections explain some techniques you can use.
Use Existing Data Sources
The Curity Identity Server uses a database, such as Microsoft SQL Server, for token and session data. However, you can configure separate data sources for user accounts and user credentials. To configure the Curity Identity Server to integrate with Active Directory, use an LDAP Data Source. An initial rollout of the Curity Identity Server might therefore include a dependency on Active Directory.
You can use different URLs for the Curity Identity Server and ADFS to enable old and new identity systems to run side by side. New applications can start using OAuth and OpenID Connect with Active Directory users and passwords, but with the Curity Identity Server's login screens, which you can customize with your preferred Branding and User Experiences.
Repoint SAML Websites
Once you are satisfied with the new login user experience, repoint existing SAML websites to use the Curity Identity Server. The following example settings show environment variables for an existing ADFS-secured SAML website. To update each website's deployment you typically only need to update SAML endpoints and the certificate that the website uses to cryptographically verify received SAML assertions. In some cases, it may be possible for operational team to perform complete migrations without requiring work from development teams.
PORT='3000'SAML_SSO_ENDPOINT='https://idp.example.com/adfs/ls/'SAML_METADATA_ENDPOINT='https://idp.example.com/FederationMetadata/2007-06/FederationMetadata.xml'CALLBACK_URL='https://www.example.com/login/callback'ENTITY_ID='saml-web-client'ASSERTION_VERIFICATION_CERTIFICATE='-----BEGIN CERTIFICATE-----\nMIIDUzCCAjugAwIBAgIJ ...'COOKIE_SECRET='34c15d7d60eefc8b46b3afaf6a6f981fd5d5...'
For the website to continue to work you must also port settings from ADFS to the Curity Identity Server. In ADFS you configure a Relying Party Trust for each website and define a Claims Issuance Policy to define the user attributes that the website receives in user attributes. To understand the equivalent configuration steps for the Curity Identity Server, follow the Integrate a SAML Website tutorial.
After basic testing and an initial rollout, you may no longer need ADFS. You can therefore retire any ADFS servers (including the ADFS proxy server role) and simplify infrastructure.
Repoint OAuth Websites
ADFS has some support for OAuth and OpenID Connect standards. If you have any OAuth-secured applications that integrate with ADFS's endpoints you should be able to follow a similar repointing approach to migrate them to the Curity Identity Server. Again, this should require zero or minimal website code changes.
Migrate WS-Federation Websites
Some organizations use ADFS's support for WS-Federation, an alternative SAML-like standard, to secure websites. SOAP-based web services may also use ADFS's support for WS-Trust. In practice, these security standards were not widely adopted outside of Microsoft, and are now considered deprecated.
Organizations need a migration strategy that keeps these websites and web services running. For that, continue to run ADFS until you are comfortable operating the Curity Identity Server. Then, plan an approach to update those components and complete your infrastructure modernization. Base solutions on the following Curity code examples:
- Upgrade WS-Federation website middleware to OpenID Connect website middleware.
- Upgrade WS-Trust web service middleware to OAuth JWT Bearer middleware.
If developers inspect the code for these Curity code examples, they should understand how to:
- Use a low code approach to swap out libraries.
- Integrate a complete application security lifecycle.
- Handle error and expiry conditions.
- Perform basic deployments, such as to Docker images.
Therefore, migrating WS-Federation and WS-Trust components to the Curity Identity Server requires development work, rather than simple changes to configuration settings. Although organizations do not need to do this work immediately, aim to prioritize it to enable infrastructure modernization.
Migrate User Accounts
When you use the Curity Identity Server it usually makes sense to remove customer user accounts from Active Directory and store them in the Curity Identity Server's native database. You can store user accounts in the same database that the Curity Identity Server uses for session and token data. You then no longer depend on Windows infrastructure and can use cloud native techniques to deploy user account data anywhere, on-premise or in the cloud.
To perform a user migration, you could write a Powershell script that calls the Get-ADUser command, iterates over the result set, then sends an insert request to the Curity Identity Server's User Management APIs for each user.
During user migrations you can save any built-in or custom user attributes to user accounts. You can then issue those user attributes to SAML assertions or OAuth tokens. Include critical identity values like custom user identifiers that SAML websites need, to identify users and authorize requests.
Using the Curity Identity Server's native database also provides the most complete control over user authentication choices. For example, you can store linked user accounts, or store public keys against user accounts, so that you can use modern authentication methods like Passkeys.
Modernize Web Architectures
After integrating SAML websites with the Curity Identity Server, you have the option to further modernize websites at a later time, when it is convenient to assign development work. Doing so can provide multiple benefits:
- Get a least-privilege API message credential (the access token) and integrate with APIs.
- Further harden web cookie security in line with the current best practices.
- Run Single Page Applications to use frontend-focused development.
- Simplify web development setups by removing backend responsibilities.
- Deploy to a Content Delivery Network (CDN) to improve global web performance.
You can compare the web security code in the SPA using Token Handler code example to the code in the Example SAML Website. Notice that both web applications only require low code integrations. However, the token handler design meets all of the above requirements.
Conclusion
Migrate from Microsoft AFDS to the Curity Identity Server to modernize user, application and API security. Doing so can also help to modernize infrastructure, provide closer control over the deployment of user account data and improve other aspects of web architectures. You can safely perform such a migration in a phased manner, without any downtime for any websites.
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
