Configuring Forms Based Authentication in SharePoint 2016 and SharePoint 2019 – Part 2 – Editing the Web.Config Files

Configuring forms based authentication (FBA) in SharePoint 2016 and SharePoint 2019 is exactly the same process as configuring it for SharePoint 2013.  I’ve recreated the SharePoint 2013 FBA tutorial specifically for SharePoint 2016 and SharePoint 2019, using screenshots from SharePoint 2016 and Windows Server 2012 R2.  I have changed the tutorial to use the SharePoint FBA Pack to create the FBA users, but otherwise it remains the same and can be used interchangeably between SharePoint 2013 and SharePoint 2016/2019.

I’ll go through all of the steps required to setup FBA for SharePoint 2016 and 2019, from start to finish.  I’ve broken down the steps into 4 sections, so if you already have an existing membership database setup from a previous version of SharePoint, feel free to skip forward to Part 2.

Part 1 – Creating the Membership Database

Part 2 – Editing the Web.Config Files

Part 3 –  Configuring SharePoint

Part 4 – Adding Users to the Membership Database

You can also watch a video of the whole process on YouTube: Configuring Forms Based Authentication in SharePoint 2016 and SharePoint 2019.

Part 2 – Editing the Web.Config Files

The next thing that has to be done to get forms based authentication working with SharePoint is setting up the membership provider.  A membership provider is an interface from the program to the credential store.  This allows the same program to work against many different methods of storing credentials. For example you could use an LDAPMembershipProvider to authenticate against Active Directory, or a SQLMembershipProvider to authenticate against a SQL Server database. For this example we’re using the SQLMembershipProvider to authenticate against a SQL Server database.

SharePoint is actually divided up into several web applications – Central Administration, the Security Token Service and all of the SharePoint web applications that you create. Each of those web applications needs to know about the membership provider. Most tutorials have you adding the membership provider settings over and over again in each web config (as well as every time you setup a new SharePoint web application).  I prefer to add the membership provider settings directly to the machine.config. By adding it to the machine.config, the configuration is inherited by all of the web.config files on the machine – so you only have to make the changes once, and don’t have to remember to make the changes every time you create a new SharePoint web application.

If you don’t have access to the machine.config, or prefer not to edit it, you will have to make all of these changes to the following web.config files:

  • SharePoint Central Administration
  • SecurityTokenServiceApplication
  • Every SharePoint web application you create that you would like to access via FBA.

NOTE – IF YOU HAVE MULTIPLE SERVERS, THESE STEPS MUST BE PERFORMED ON ALL SERVERS.

BEFORE EDITING ANY .CONFIG FILE – MAKE A BACKUP OF IT. It’s very easy to make a typo.

  • Navigate to “C:\Windows\Microsoft.Net\Framework64\v4.0.30319\Config” and open “machine.config”.sharepoint_2013_fba_config_1
  • In the <ConnectionString> section, add the following line:
    <add connectionString="Server=win-h472cerv001;Database=aspnetdb;Integrated Security=true" name="FBADB" />

    Be sure to replace the value for Server with the name of your SQL Server.machine config connection string

  • In the <membership><providers> section add the following:
    <add name="FBAMembershipProvider"
     type="System.Web.Security.SqlMembershipProvider, System.Web, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"
     connectionStringName="FBADB"
     enablePasswordRetrieval="false"
     enablePasswordReset="true"
     requiresQuestionAndAnswer="false"
     applicationName="/"
     requiresUniqueEmail="true"
     passwordFormat="Hashed"
     maxInvalidPasswordAttempts="5"
     minRequiredPasswordLength="7"
     minRequiredNonalphanumericCharacters="1"
     passwordAttemptWindow="10"
     passwordStrengthRegularExpression="" />

    You can customize the authentication by modifying each of these options. The most important thing to remember though is that if you define a membership provider in multiple locations for the same database, they MUST ALL USE THE SAME OPTIONS. Otherwise you’ll run into all kinds of problems with users created with one set of options, and later being authenticated against with a different set of options.

    Here’s a description of the different options available:

    Option Description
    connectionStringName The name of the database connection to the aspnetdb database.
    enablePasswordRetrieval true/false. Whether the user’s password can be retrieved. I suggest setting this to false for security purposes.
    enablePasswordReset true/false. Whether the user can reset their password. I suggest setting this to true.
    requiresQuestionAndAnswer true/false. Whether accounts also have a question and answer associated with them. The answer must be provided when resetting the password. I suggest setting this to false, as setting it to true prevents an administrator from resetting the user’s password.
    applicationName Setting the application name allows you to share a single membership database with multiple different applications, with each having their own distinct set of users. The default applicationName is /.
    requiresUniqueEmail true/false. Determines if multiple users can share the same email address. I suggest setting this to false, in case you ever want to implement a login by email system.
    passwordFormat Clear, Hashed or Encrypted. Clear stores the password in the database as plain text, so anybody with access to the database can read the user’s password. Encrypted encrypts the user’s password, so although the password isn’t human readable in the database, it can still be decrypted and the user’s actual password retrieved. Hashed stores a one way hash of the password.  When a user authenticates, the password they enter is hashed as well and matched against the stored hashed value. Using this method, the user’s password can never be retrieved (even if your database is stolen), only reset.  I always recommend using “Hashed” as it is the most secure way of storing the user’s password.
    maxInvalidPasswordAttempts The number of times in a row that a user can enter an invalid password, within the passwordAttemptWindow, before the user’s account is locked out. Defaults to 5.
    passwordAttemptWindow The number of minutes before the invalid password counter is reset. Defaults to 10.
    minRequiredPasswordLength The minimum password length. Defaults to 7.
    minRequiredNonalphanumericCharacters The minimum number of non-alphanumeric characters required in the password. Defaults to 1.
    passwordStrengthRegularExpression A regular expression that can be used to validate the complexity of the password.

    sharepoint_2013_fba_config_3

  • In the <roleManager><providers> section add the following:
    <add name="FBARoleProvider" connectionStringName="FBADB" applicationName="/"
     type="System.Web.Security.SqlRoleProvider, System.Web, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" />

    Save and close the machine.config file.
    sharepoint_2013_fba_config_3_1

  • I mentioned that if you modified the machine.config, you’d only have to put the config in a single place.  I wasn’t being completely truthful.  The SharePoint Web Services configuration overrides the machine.config and clears the entries we created. For that reason, the membership and role providers also need to be added to the SecurityTokenService (But only there – you won’t have to add them to the central admin or other SharePoint web app web.configs.First we need to find the web.config for the SecurityTokenService. Open up IIS. Under sites, SharePoint Web Services, right click on SecurityTokenServiceApplication and click on Explore. Edit the web.config in the folder that opens.SharePoint Security Token Service
  • Add the following to the web.config, just before the closing </configuration> tag:
    <system.web>
     <membership>
     <providers>
     <add name="FBAMembershipProvider"
     type="System.Web.Security.SqlMembershipProvider, System.Web, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"
     connectionStringName="FBADB"
     enablePasswordRetrieval="false"
     enablePasswordReset="true"
     requiresQuestionAndAnswer="false"
     applicationName="/"
     requiresUniqueEmail="true"
     passwordFormat="Hashed"
     maxInvalidPasswordAttempts="5"
     minRequiredPasswordLength="7"
     minRequiredNonalphanumericCharacters="1"
     passwordAttemptWindow="10"
     passwordStrengthRegularExpression="" />
     </providers>
     </membership>
    <roleManager>
     <providers>
     <add name="FBARoleProvider" connectionStringName="FBADB" applicationName="/"
     type="System.Web.Security.SqlRoleProvider, System.Web, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" />
     </providers>
     </roleManager>
     </system.web>

    Remember to match all of the options with what was entered in the machine.config.Save and close the file.

    sharepoint_2013_fba_config_5

The role and membership providers have now been setup for SharePoint. Continue on to Part 3 to configure SharePoint to use the membership provider we just setup.

Comments

42 responses to “Configuring Forms Based Authentication in SharePoint 2016 and SharePoint 2019 – Part 2 – Editing the Web.Config Files”

  1. Bret Avatar
    Bret

    Do these config changes need to be done on the distributed cache server and/or the app server?

    1. Chris Coulson Avatar

      They need to be done anywhere where either authentication is being done or fba users are being queried.

      So no, you shouldn’t need it on the distributed cache server. I don’t expect that any of the services running on the app server require it, but I myself would make the changes there anyways, just in the off chance that one of the services does query the fba users.

  2. john adams Avatar
    john adams

    Hi Chris,

    We are having trouble signing in to the SP site using FBA. We have a SP farm configured to use AG’s in SQL and a listener. Please see below for transcript. We tested on our dev box which is not using a listener and it works, but IIS does not seem to like the connection string for the listener:? any help appreciated:

    Token Handler: Claims Forms Sign-In: Membership Provider ‘FBA_Membership’ username-password check for user ‘XXXXXXXXXX@gmail.com’ generated exception. Exception: ‘System.ArgumentException: An error occurred while attempting to initialize a System.Data.SqlClient.SqlConnection object. The value that was provided for the connection string may be wrong, or it may contain an invalid syntax. Parameter name: connectionString —> System.ArgumentException: Keyword not supported: ‘sp16-xxx-sag.XXXXXXX.lan;database’. at System.Data.Common.DbConnectionOptions.ParseInternal(Hashtable parsetable, String connectionString, Boolean buildChain, Hashtable synonyms, Boolean firstKey) at System.Data.Common.DbConnectionOptions..ctor(String connectionString, Hashtable synonyms, Boolean useOdbcRules) … 9978d79d-f239-20d0-53af-3c4b27321734
    02/22/2017 10:27:40.68* w3wp.exe (0x25F4) 0x14B4 SharePoint Foundation Claims Authentication ad1qp Unexpected … at System.Data.SqlClient.SqlConnectionString..ctor(String connectionString) at System.Data.SqlClient.SqlConnectionFactory.CreateConnectionOptions(String connectionString, DbConnectionOptions previous) at System.Data.ProviderBase.DbConnectionFactory.GetConnectionPoolGroup(DbConnectionPoolKey key, DbConnectionPoolGroupOptions poolOptions, DbConnectionOptions& userConnectionOptions) at System.Data.SqlClient.SqlConnection.ConnectionString_Set(DbConnectionPoolKey key) at System.Data.SqlClient.SqlConnection.set_ConnectionString(String value) at System.Data.SqlClient.SqlConnection..ctor(String connectionString, SqlCredential credential) at System.Web.DataAccess.SqlConnectionHolder..ctor(String connectionString)

    1. john adams Avatar
      john adams

      Hi Chris,

      All sorted, the connection string was missing ‘server=’ all fixed.

      Cheers
      Grizzly

  3. Ernie Encinas Avatar
    Ernie Encinas

    Hey Chris.
    I have made the necessary changes to web configs in CA, Web App, and Security token. I have added the section for password to not require users to enter secret answer. However, I am getting this error when trying to reset a user’s password from User Management list:
    “Your current membershipprovider settings prevent a user’s password from being reset. To allow for resetting of a password by an administrator, you must have enablePasswordReset=”true” and requiresQuestionAndAnswer=”false” in your membership provider settings in your web.config”. I also have the section for secret question and answer when creating a new profile.
    Appreciate any assistance on resolving this issue.

    Thanks,
    Ernie Encinas
    SharePoint Administrator

    1. Chris Coulson Avatar

      You should only be getting this error if the active membership provider has settings other than:
      enablePasswordReset=”true” and requiresQuestionAndAnswer=”false”

      It could be that you have multiple membership providers setup. The FBA Pack will use the one specified by name in the ‘Authentication Providers’ option for managing web applications in Central Admin.

      It could also be that you are editing a membership provider entry that is getting overwritten by another .config file. Or possibly that you have multiple servers and haven’t adjusted the .config files in all of them.

      1. Ernie Encinas Avatar
        Ernie Encinas

        Chris,
        Thanks for your response and suggestions. I was able to resolve the issues with password reset by running the FBA Configuration Manager for SP2013 and included enablePasswordReset=”true” and requiresQuestionAndAnswer=”false” in the membership provider section. Appears that my SP2016 farm included an additional WFE and APP server that needed the web configs modified.

        Thanks,
        Ernie

  4. Ernie Encinas Avatar
    Ernie Encinas

    Dear Chris,
    I had a question regarding the “FBA Membership Request Management” list. When I try to create new FBA users in the request management list(by saving as pending and the approved) the new users are never sent to the FBA user management list or in SharePoint User Profile store. The reason why I was wanting to use FBA membership request management list is so that I can add custom properties to list for synchronization to SharePoint UPS. Look forward to expertise.

    Thanks,
    Ernie
    SharePoint Administrator

    1. Chris Coulson Avatar

      I think that doing what you’re doing should work for creating the user’s. I haven’t tried it myself, but that’s all the membership request web part is doing is creating a new item in the membership request list, and then when it is approved it goes and creates the actual user. I expect one or more of the fields is not getting filled out properly. You might want to check the SharePoint log file, it should tell you what errors are occurring when the item approval happens.

      Unfortunately, even if you do get this working, adding new properties to this list will not add the properties to the user’s profile. Right now the fields it pulls from the membership request list are hard coded, so any new columns you add will be ignored. The source code would have to be modified to allow for that.

  5. Andy Avatar
    Andy

    Hi Chris,

    Your FBA pack is amazing, and it is working perfectly on my development servers (soon to be production though).

    Just curious, if I already had 1 web application which is configured to use FBA, then I want to add other web applications which will use FBA too, or extend another web application to use FBA (all on different database), then I just need to add the second connection string, membership provider, and role provider under each respective section under the machine.config on the server and STS web.config, right? Do I need further changes aside from those config files?

    Thanks.

    1. Chris Coulson Avatar

      If you’re adding additional web applications, you don’t need to make any additional changes to the config files – as the machine config entries are shared for everything on the machine. You just have to enter the membership/role provider names in the ‘Authentication Providers’ section of Central Admin (Part 3).

      That is assuming you want to share the same FBA users. If you want a separate set of users, then yes, you’d have to create separate config file entries with different names.

  6. Joshua Avatar
    Joshua

    Chris,

    I wasn’t sure exactly where to post this but here is my scenario. I would like to allow non-site collection administrators to add users and utilize the FBA user creation process.

    How can I grant access to non-site collection administrators?

    Thank you,
    Joshua

    1. Chris Coulson Avatar

      Unfortunately, allowing non-site administrators to use the User Management pages is not possible without a code change.

      If you just want them to be able to create users, you could create a page for them and add the Membership Request web part to it, and then give the page appropriate permissions. That would allow them to create new users, but would not allow them to manage existing ones.

  7. Krunal Mehta Avatar
    Krunal Mehta

    Hi Chris,
    Your article worked pretty smooth.I wanted to understand how do we modify these settings in an extended web application ? I tried to replicate the settings as it is from the other web.config files. However when i navigate to FBA User Roles it says “Membership provider is not configured correctly.Kindly modify web.config”. Please assist me with this issue.

    Thanks in advance.

    Krunal Mehta

    1. Chris Coulson Avatar

      That’s the beauty of modifying the machine.config instead of the individual web.config’s directly – when you extend a web application there’s no need to modify the new web.config. All you have to do is set the values for the Authentication Providers in Central Admin, as described in part 3.

      From your post though it sounds like maybe you modified the web.config directly. If you went and added the same entries that were added to the machine config, you will get errors like described due to duplicate membership providers configured (the web.config inherits the values from the machine.config – so if you also add them to the web.config you now have duplicates).

      1. Steve Johns Avatar
        Steve Johns

        Hi Chris,

        I am experiencing the same error when attempting to manage forms based users… “A Membership Provider has not been configured correctly. Check the web.config setttings for this web application”. In this case, this is a brand new Sharepoint 2019 installation. I have followed your tutorial exactly, and I have not modified any of the config files except as specified in the tutorial. Just to prove the point, I completely removed my Sharepoint server and database installations, and still end up with the exact same error. Your post is now fairly old, is it possible that something has changed in Sharepoint that would cause your tutorial to no longer function?

        1. Chris Coulson Avatar

          Hi Steve,

          The tutorial still works, the only thing that has really changed is that to use it in Chrome you need to be accessing the site via https/ssl. But nothing to do with the above error.

          That error just means that the FBA Pack can’t access the database specified in the config file/FBA Setup. I’d say 90% of the time it is due to a permissions issue. The database requests happen as the SharePoint app pool user, and that user doesn’t have permission to the DB. There’s information in Part 1 about assigning the proper permissions to the DB.

  8. Ravi Singh Avatar
    Ravi Singh

    Hi Chris,

    Thanks for your excellent article.
    In my environment I have 2 WFEs and 2AS.

    I have modified machine.config for all four machines and also modified web.config for all security token service as mentioned in your article.

    I also reset IIS on all machines.

    When I am trying to access

    Site Settings : Manage Forms Based Authentication Users page

    It shows this error.

    A Membership Provider has not been configured correctly. Check the web.config settings for this web application.

    This is my connection string

    Do you think is it valid ?

    Or can you help me to debug the issue.

    Regards

    Ravi Singh

    1. Chris Coulson Avatar

      Unfortunately the connection string was filtered out of your reply. If you’re sure the .config files were updated properly, my guess would be a permissions issue on the sql server. Make sure that the app pool user has db owner permissions on the membership database.

      1. Ravi Singh Avatar
        Ravi Singh

        Hi Chris,

        Thanks for quick reply.

        As per my understanding all configuration are done correctly and I also assigned correct permission to pool identity in the db. I configured it in single box installation and it was working fine there, But now when I am working with multiple WFEs and ASs it is showing error in configuration files.

        Can you please share your email address where i can send more details about the configurations done, so you can provide expert advice on it.

        Regards

        Ravi Singh

        1. Ravi Singh Avatar
          Ravi Singh

          Hi Chris,

          Its working fine for me. I forgot to complete Part 3 as mentioned by you.

          Regards

          Ravi Singh

  9. Neeraj Malhotra Avatar
    Neeraj Malhotra

    Hi Chris,

    I followed all the steps mentioned, however I am unable to login into portal now, though I am net any error, SharePoint portal is just not accepting the credentials, even I tried with farm account.
    I believe we can’t go with both the authentications (Windows and Forms) enabled simultaneously, please suggest.
    Thanks in advance!!!

    1. Chris Coulson Avatar

      Both Windows and Forms enabled simultaneously definitely works in SharePoint. At the login screen it should show you a dropdown asking if you want to login via windows or forms, and then take you to the appropriate login page. If you’re still having issues after double checking your configuration, I would suggest looking at the sharepoint log files after a failed login – that might give you a better clue as to what’s happening.

  10. […] I’ll go through all of the steps required to setup FBA for SharePoint 2016 and 2019, from start to finish.  I’ve broken down the steps into 4 sections, so if you already have an existing membership database setup from a previous version of SharePoint, feel free to skip forward to Part 2. […]

  11. […] I’ll go through all of the steps required to setup FBA for SharePoint 2016 and 2019, from start to finish.  I’ve broken down the steps into 4 sections, so if you already have an existing membership database setup from a previous version of SharePoint, feel free to skip forward to Part 2. […]

  12. Joe Avatar

    Hi Chris, first off, thank you thank you thank you for being here and contributing to the community.

    You don’t mention machinekeys in this post – we have multiple WFE, do we need to have the machine keys configured? Thanks!

    1. Chris Coulson Avatar

      Hi Joe,

      You only need the machinekeys if you use a passwordFormat of “Encrypted”. I really suggest you use the more secure format of “Hashed”, which does not require machinekeys.

  13. Sampath Avatar
    Sampath

    Hi Chris,
    Amazing, Your FBA pack works well.
    I just need to know some of the details, I want to add the Reset/Change Password links on login screen correct? can you pls share the details how can we add these links?

    Thanks in Advance.

    1. Chris Coulson Avatar

      Yes – to add the links you will have to create a SharePoint custom login page. I usually just take a copy of the existing SharePoint forms login page and add the links.

  14. Irfan Khan Avatar
    Irfan Khan

    Hi, i am using fba through machine.config in sharepoint 2016. Client has configured earlier fba on one web application and it is perfectly working fine. Now, they have created a new and as per using machine.config, there is no need for adding membership provider and role. When they are trying to login then fba login form is redirecting to the login form again n again.

    It is validating the user, if i give wrong credentials then give alert for invalid user but not redirecting me into the web application in case of valid user.

    1. Chris Coulson Avatar

      Are you using Chrome? Does it work fine in Internet Explorer (Not Edge)?

      Chrome made changes to it’s cookie security a while ago, and Microsoft put out a patch to SharePoint 2016 to work with it. However the changes they made causes it only to work over SSL in Chrome.

      I expect this is your issue. Get an SSL cert for the site and access it via https and I think it will start working properly.

  15. pragna patel Avatar
    pragna patel

    Hi Chris,

    I have a multiple server environment with 1 WEF, 1 APP, and 1 Sql server. As you mention in the blog we need to change the machine.config on all the environment. Is this applicable to sql server environment also?

    When i try to login with FBA users i get below errors in ULS log though i used the hashed passwordFormat

    STS Call: Failed to issue new security token. Exception: ‘System.ServiceModel.FaultException`1[Microsoft.IdentityModel.Tokens.FailedAuthenticationException]: The security token username and password could not be validated. (Fault Detail is equal to Microsoft.IdentityModel.Tokens.FailedAuthenticationException: The security token username and password could not be validated.).’.

    Please advice
    Regards

    1. Chris Coulson Avatar

      You don’t need to make the machine.config change on SQL Server, only on SharePoint servers.

      As for the error, did you make the SecureTokenService web.config changes? If so, I think there’s some differences in the membership settings in that web.config and the machine.config.

      1. Pragna patel Avatar
        Pragna patel

        Thank you for quick reply.

        Yes, I have made changes to SecureTokenService web.config as mentioned.
        When I do the FBA configuration on my dev box with is single server environment it works just fine. The only difference on the staging environment is its multiple server architecture. I will double check my web.config though.

        Here are few errors I find in ULS log.
        SPSecurityContext: Request for security token failed with exception. Exception: ‘System.ServiceModel.FaultException: The security token username and password could not be validated.
        at Microsoft.IdentityModel.Protocols.WSTrust.WSTrustChannel.ReadResponse(Message response)
        at Microsoft.IdentityModel.Protocols.WSTrust.WSTrustChannel.Issue(RequestSecurityToken rst, RequestSecurityTokenResponse& rstr)
        at Microsoft.IdentityModel.Protocols.WSTrust.WSTrustChannel.Issue(RequestSecurityToken rst)
        at Microsoft.SharePoint.SPSecurityContext.SecurityTokenForContext(Uri context, Boolean bearerToken, SecurityToken onBehalfOf, SecurityToken actAs, SecurityToken delegateTo, SPRequestSecurityTokenProperties properties)’.

        SetupUserValidationType: Password not set. Defaulting to sign-in operation. Username:

        An exception occurred when trying to issue security token: The security token username and password could not be validated..

        1. Chris Coulson Avatar

          Yeah, it should be fine in a multi server environment, as long as all the machine.config files and securetokenservice web.configs are all configured the same.

  16. Mahmood Avatar
    Mahmood

    Hi Chris,
    Thank you for this amazing article. I have a multiple server environment and I did the FBA configuration on my WEB1 & WEB2 servers, but I’m facing an issue where FBA users are redirected to the login page repeatedly, and sometimes after getting redirected they would get an Error saying that the username/password are wrong.

    I tried to turn off the WEB1 IIS and everything worked fine. but still I need both of them the stay up.

    any thoughts?

    1. Chris Coulson Avatar

      My guess is that something is configured differently in web1 than web2. Have you checked to make sure all of the .config file changes are the same? Are you sure that the connection string properly connects to the sql server from web1? Shouldn’t be, but is it possible that the app pool account is different between the two servers and only the web2 account has permissions to the fba database?

      Another possibility is if you are using the encrypted password format instead of hashed (you should use hashed). The encrypted password format requires the same machine key values set on all servers.

      1. Mahmood Avatar
        Mahmood

        Hi Chris,
        Thank you very much for your fast replies.
        I have indeed configured both servers with the same configurations, going through this article. so both had the same configurations. however, I found the issue which seems to be strange to me.

        I did the following:
        1- Open IIS Manager.
        2- Clicked on securityTokenServiceApplication -> features View -> Connection Strings.
        3- Here I noticed that I have different Connection strings that are pointing to different server, once I fixed it everything worked fine.

        I checked the web.config again and found that the connection strings have been added there.

        Thank you so much for your time and effort.

Leave a Reply

Your email address will not be published. Required fields are marked *