Documentation for Crowd 2.8. Documentation for earlier versions of Crowd is available too.

Skip to end of metadata
Go to start of metadata

Crowd provides a number of modules that allow you to configure Crowd to authenticate HTTP Basic Authentication requests made to an Apache web server.

The following features are supported:

  • Authentication: Use Crowd to password-protect resources on your website.
  • Authorisation: Configure website locations to restrict access to specific Crowd groups or users.

This version of the connector is supported under Linux. Please see Choosing the Correct Apache Connector for your Operating System for details and alternatives.

Note: These instructions apply to Crowd 2.1 and later. We assume some UNIX system and Apache configuration knowledge.

On this page:

Prerequisites

Download and configure Crowd. Refer to the Crowd installation guide for detailed information on how to do this.

Step 1. Disabling any Previous Version of the Crowd Apache Connector

If you are upgrading from a previous version of the Connector, you must disable it by following these instructions before proceeding.

Step 2. Configuring Crowd to Talk to Apache

If you are upgrading from an earlier version of the Apache Connector, you will have already completed this step and you can skip it.

Crowd needs to be aware that Apache will be making authentication requests to Crowd. In brief, you will need to do the following:

  1. Define Apache as a Crowd-connected application to Crowd.
  2. Add and configure the directories visible to Apache.
  3. Add and map the groups which are allowed to authenticate with Apache.

Step 3. Choosing the Correct Apache Connector for your Operating System

The installation procedures for Apache and the Crowd Apache connector vary depending on the operating system you are using. Use the links below to find installation instructions for your chosen operating system. If you have not chosen an operating system yet, you will probably find one of the Linux variants easiest to set up.

The 2.x version of the Crowd-Apache connector supports advanced features such as nested groups and single sign-on but is currently only supported for certain operating systems.

Note about Crowd-Apache 1.4 Connector

This document is for the 2.x version of Crowd-Apache Connector, if you can't find an compatible version of the 2.x Subversion Connector for your O/S in the table below then refer to the 1.4 version of the Crowd-Apache Connector.

Previous version of Crowd-Apache connectors don't support the SVNParentPath directive. 

Operating System

Crowd-Apache Connector 2.0

Crowd-Apache Connector 1.4

Red Hat Enterprise Linux

(tick) 6.0 (tick) 5.5 Installation guide

(info) Installation guide for other OS versions

CentOS Linux

(tick) 5.5 Installation guide

(info) Installation guide for other OS versions

Ubuntu Linux

(tick) 11.04 (tick) 10.10 (tick) 10.04 Installation guide

(info) Installation guide for other OS versions

Debian

(tick) 6.0 Installation guide

(info) Installation guide for other OS versions

Other UNIX-Like Systems

Not supported*

(tick) Installation guide

Windows

Not supported*

(tick) Installation guide

*The Crowd-Apache Connector 2.0 source code is available with instructions to build from source. If you have the expertise to compile the C library and get it working for an environment that is currently not supported then feel free to contribute by adding a comment to this page. We will try to incorporate your fix in the next release of the Crowd-Apache Connector.

Step 4. Configuring Authentication

In this section, you will tell Apache to use Crowd to authenticate requests for a particular location. Edit the Apache config file and add the following commands to a <Location> or <Directory> section.

This is the minimum configuration required to password-protect a location with Crowd.

These commands must be added to the Apache config. It does not work with .htaccess.

Command

Explanation

<Directory "/var/mysite/">
.
.
.
</Directory>

See the Apache documentation for the format of the <Directory> and <Location> directives. We have used the directory path of /var/mysite/ as the simplest example. You may substitute your own directory path here.

AuthName "Atlassian Crowd"

Defines the realm of the authentication. This information is typically provided to the user in the dialogue box popped up by their browser. This must be a unique name for each Crowd application

AuthType Basic

Tells Apache to use HTTP Basic authentication. HTTP Digest authentication is not currently supported.

AuthBasicProvider crowd

Tells Apache to delegate authentication to the Apache Crowd connector.

CrowdAppName myappname

Set 'myappname' to the application Apache should authenticate as.

CrowdAppPassword mypassword

Set 'mypassword' to the password for the application.

CrowdURL http://localhost:8095/crowd/

The URL of the Crowd server.

Require valid-user

Tells Apache that clients must provide a valid username/password to access the location.

The following configuration commands are optional, and can be used to customise your configuration further:

Command

Explanation

Default

CrowdAcceptSSO Off

When set to 'On', the Apache Crowd connector will attempt to validate single sign-on (SSO) tokens provided in requests, avoiding the need for the user to log in if they have already logged in to another application.

On

CrowdCreateSSO Off

When set to 'On', the Apache Crowd connector will create a single sign-on (SSO) token whenever a user successfully authenticates, avoiding the need for the user to log in to other applications.

On

CrowdBasicAuthEncoding ISO-8859-1 UTF-8

Sets the list of character encoding schemes that the Apache Crowd connector will use to decode usernames and passwords. Each is tried in turn, until authentication succeeds. This setting may need to be changed if you have users with non-ASCII characters in their usernames or passwords, as browsers differ in the encoding schemes they use. Note that when an authentication attempt fails with one or more encodings before succeeding with another, the failures may still be counted and logged as failures by the directory.

ISO-8859-1

CrowdTimeout 5

The maximum number of seconds that the Apache Crowd connector should wait for a response from Crowd. If set to 0, the connector will wait indefinitely.

0

CrowdCacheMaxAge 120

The maximum number of seconds that a response from Crowd will be cached by the Apache Crowd connector.

60

CrowdCacheMaxEntries 1000

The maximum number of entries cached at any time by the Apache Crowd connector. If set to 0, caching is disabled.

500

For more detail about Apache configuration, please refer to the Apache documentation.

Step 5. Configuring Authorisation

If you want to restrict access to a certain Apache <Directory> or <Location>, so that only a subset of Crowd users and/or groups have permissions, add the following lines to your configuration:

Note that you must also remove any Require valid-user command from this <Directory> or <Location> for the new restrictions to take effect.

Command

Explanation

Require user johnh kevinr

Allow the users johnh or kevinr to access the location.

Require group developers crowd-administrators

Allow members of the developers or crowd-administrators groups to access the location.

If both 'Require user' and 'Require group' are used, these are combined using OR rather than AND, so any user that authenticates successfully will be able to access the resource.

 

If you are using "Require user" and "Require group" directives together, you will need to add the following setting:

Command

Explanation

Default

AuthzUserAuthoritative Off

When set to 'On', authorisation decisions made by mod_authz_user on the basis of "Require user" directives are final. When set to 'Off', they may be overruled by other Apache authorisation providers.

On

If you have configured authorisation providers in addition to the Crowd Apache connector, you may need to add the following optional setting:

Command

Explanation

Default

AuthzCrowdAuthoritative Off

When set to 'On', authorisation decisions made by Crowd are final. When set to 'Off', they may be overruled by other Apache authorisation providers.

On

Step 6. Configuring Subversion (Optional)

If you are using Subversion under Apache, Crowd's Subversion connector allows you to password-protect a Subversion repository and provide fine-grained access control by group or user.

Follow the instructions on integrating Crowd with Subversion.

Notes

  • Typically, only one of the Require user or Require group commands is needed for a particular location. You can define both. If you do, then access is granted if either is satisfied.
  • If the CrowdCacheMaxEntries setting is missing or set to a non-zero value, then requests to Crowd are cached in order to increase performance. This means that changes to passwords, group membership and session expiry in Crowd may not be reflected immediately in user access.
  • Although the Apache Connector does not support Digest Authentication, the connection with Crowd can still be secured by using httpsto make the SOAP connections.

    For information on how to secure Crowd connections, refer to the documentation on configuring Crowd to work with SSL.

  • If you are using Crowd 2.0 or earlier, you need to follow the instructions for Crowd 2.0.
RELATED TOPICS

Crowd Documentation

50 Comments

  1. I got a error: CrowdAuth: Failed to authenticate application.

    According to the troubleshooting steps I checked the CrowdAppName or CrowdAppPassword parameters. They were correct. After comparing with other applications where Crowd authentication did work, I found that the Remote Addresses list is very important. This list contained only the DNS name and 127.0.0.1. After adding the real server ip address, the authentication succeeded.

    The DNS name was resolved to 127.0.0.1 during addition of the application. I'm not sure whether this is a bug.

    1. I too have been bitten by Remote Address issues, many times because many of my servers have virtual IPs and are hosting multiple services.  Always check the atlassian-crowd.log and search for the phrase: is forbidden from making requests to the application.  This INFO level log message will contain the name of the application and the source address that is forbidden.  In all likelihood you'll just simply have to the add this address to your application definition's Remote Addresses section inside Crowd.  Hopefully that helps...read your logs people.

  2. Anonymous

    would it be possible to add a HTTP NTLM authentication to automatically login to every crowd integrated application?

    1. Hi,

      There's a third-party NTLM & Kerberos plugin for Crowd here: https://plugins.atlassian.com/plugin/details/6110

      We don't have official NTLMv2 and Kerberos support planned for the near future, I'm afraid.

      Cheers,

      Dave.

  3. Hi,

    Can you add usecases describing the SSO functionnality ?

    My own case is as follows : SVN client: SmartSVN, JIRA/Confluence client: Firefox. How can a SSO session be shared between Firefox and SmartSVN ?

    Thx

    1. Hi Issa,

      Unfortunately, it is not possible to configure SmartSVN to participate in SSO.

      This is because Crowd uses HTTP cookies to share SSO tokens between web applications in the same domain. SmartSVN does not have access to Firefox's cookies, so it is not able to send the required SSO token to the Subversion server.

      You can learn more about how SSO works by reading this overview.

      1. Hi Adrian, thx for your reply.

        That was my guess about SmartSVN.

        But then, which subversion client would be able to share SSO tokens with the other Atlassian software suite ?

        1. Sorry, I'm not aware of any Subversion client (apart from the browser itself) which shares SSO tokens with the browser.

          1. Ok Adrian, you confirm my guess.

            It would be fair to explain that crowd will never share sso tokens between webapps and svn clients to avoid marketing people and other non technical people from believing this otherwise... (smile)

  4. Either "The 2.0 version of the Crowd-Apache connector supports advanced features such as nested groups and single sign-on but is currently only supported for Red Hat and CentOS." is wrong or the "Crowd-Apache Connector 2.0" column in the table below.

    1. Thanks for spotting that inconsistency, Dennis. I've corrected it.

  5. Hi!

    I've raised an support issue also, but I thought that I should post my question here also.

    What are the limitations for using Crowd Apache Connector against Jira's embedded Crowd? I've gotten it to work basically, but there are some issues that might go away if I would know more about the connector limitations.

    Tanks in advance,

    Tanel

    1. Hi Tanel,

      I'm afraid that using the connector with JIRA's user management is not a supported configuration.

      If you need to share a user base between JIRA and Apache, you should look at using Crowd instead.

      1. Hi Adrian,

        I know that, but nevertheless, it works :) Even though with error messages in Apache log, massive amount of user session in Jira server and occasional auth prompts when browsing around.

        The thing I wanted to know what is the conceptual difference between embedded and external Crowd? Is the protocol different?

        But anyway, I'll probably switch to other means for Basic Auth. But it still would be a good feature to get the Apache Connector to work against Jira crowd also.

        Thanks,

        Tanel 

  6. Anonymous

    Is there any way the AuthzSVNCrowdAccessFile code be provided as AuthzCrowdAccessFile to support an Authz file for non SVN cases. I have been trying to setup DAV as well as other directories with Crowd Authz and while i can use the require user and require group tags in different files, i really like the convenience of defining access via users and groups in a single file (like SVN). This used to work fine if i use the 1.4 module but using 2.0 if i add the AuthzSVNCrowdAccessFile then the mod complains that i need to set a SVNPath or SVNparentPath and setting those when i am not really using svn makes the code bomb in different ways. (e.g. the svn module either barfing that i need to provide the module name in the url etc).. 

    You can test this out with either using the mod_ftp or mod_dav modules. 

    -Gaurang

  7. Anonymous

    Hi,

    I get 500 Internal error.

    Error_Log says:

    [Wed Dec 07 14:33:46 2011] [crit] [client 10.9.23.44] Failed to send authentication request (CURLcode 7)
    [Wed Dec 07 14:33:46 2011] [crit] [client 10.9.23.44] Crowd authentication failed due to system exception

    any ideas??

    1. CURLcode 7 indicates that the Connector failed to connect to Crowd.

      Check that Crowd is running, that you've correctly specified its URL, and that there's no firewall preventing the connection.

      If you need further help, please contact our support team.

  8. Hi, i have a problem when i try to get this to work:

    Cannot load /modules/mod_authz_svn_crowd.so into server: /modules/mod_authz_svn_crowd.so: undefined symbol: authnz_crowd_user_groups

    I don´t understand what i have missing, i load:

    LoadModule dav_module modules/mod_dav.so
    LoadModule dav_svn_module modules/mod_dav_svn.so
    # LoadModule authz_svn_module modules/mod_authz_svn.so
    LoadModule authz_svn_crowd_module modules/mod_authz_svn_crowd.so

     

     

    1. Hi,

      With the four lines, it works fine...

       

      LoadModule dav_svn_module modules/mod_dav_svn.so
      LoadModule authz_svn_module modules/mod_authz_svn.so
      LoadModule authnz_crowd_module modules/mod_authnz_crowd.so
      LoadModule authz_svn_crowd_module modules/mod_authz_svn_crowd.so
      1. Thanks a lot now it´s working for me also.

         

  9. Anonymous

    We are integrating Gitolite with mod_authnz_crowd using the ideas on this page: http://www.codinginahurry.com/2011/05/21/integrating-gitolite-with-atlassian-crowd/

    Our patch to set the list of a user's remote groups in an environment variable for use by Gitolite via CGI is here: https://gist.github.com/2154942

    1. Anonymous

      I fixed some defects with the above patch. Unfortunately, I created that gist anonymously and don't see a way to claim it, so instead of repairing it I posted a new gist. Sorry for the procreation.

      Newest patch: https://gist.github.com/2402673

      Although, I would prefer the mod_authnz_crowd source to be on bitbucket so that we could improve it using a better collaborative workflow..

  10. Thanks for the helpful documentation for setting this up.

    My only issue is that when I log in using this, one of the SERVER variables I am able to access once logged in is the user's password.

    The username is certainly helpful for user lookup and such to keep an audit trail of activity, but concerned about the module apparently passing the password along as well.

    Any further information on this? 

    Thanks!

    1. Hi Brad,

      That doesn't sound right.

      If you raise a request at support.atlassian.com with the specific details and mention my name, I'll look into it.

  11. Unable to logout on Confluence/Jira after login using apache connector?

    Hi

    I've setup Confluence/Jira/Fisheye accessible via apache mod_proxy and authenticating against Crowd. That's working very well. Additionally I set up the apache crowd integration which works nice too. But we spot the problem, that the logout from Confluence/Jira/Fisheye did not work after login on a page using the apache Crowd integration!? Any ideas what's wrong? If there's some important configuration part to know, it should be mentioned above.

    Additional question: How to do logout on page which uses the apache connector?

    1. Hi Yves,

      The problem you describe is a limitation of HTTP Basic Authentication.  It provides no mechanism to "log out".  The best you can do is restart your web browser.

      Each request from the browser using Basic Authentication is effectively a new login attempt, which is why it seems impossible to log out from Confluence, JIRA and FishEye: You're being logged right back in every time you use an application that employs Basic Authentication.

      1. Hi Adrian,

        wow, what a fast response! (smile)

         

        Hm, strange. But why am I still logged in on the page which uses the Apache-connector even if I closed the browser, re-open it and came back to the page?

         

        Kind regards,

        Yves

        1. That behaviour is caused by the browser cookie that's created and used by the SSO mechanism.  Unlike your basic authentication credentials, it survives between browser restarts.

          You can disable that behaviour by using the "CrowdAcceptSSO Off" setting described above, but that means that you won't automatically be logged into the application that uses basic authentication when you log into another application.

  12. Curious, because of multiple Crowd/Atlassian-product installations in my environment I've had to fine-tune my SSO cookies through the crowd.properties file (e.g. the session.tokenkey and the cookie.tokenkey values).  Now, how do I get my apache/subversion SSO module to detect these alternate token names?  Its quite simple for our java applications as we embed the crowd.properties file right into the root classpath or supply the -Dcrowd.properties variable to the JVM on startup; but these mechanisms don't exist here in httpd-land.  Did I miss something?

    1. I must apologize for my previous post, but it appears somehow my SSO with httpd/subversion will work, so long as I log into one of my other products first: JIRA, Confluence, Crowd, etc.  Now, if I login into httpd/subversion FIRST (via my browser) and then try to navigate to one of my other products, say JIRA, it won't recognize the token cookie/session names from the httpd/subversion login (which is something I fully expect and agree with).  So that begs the question, how is httpd/subversion permitting access even when my cookie/session names have been customized in the JIRA/Confluence/Crowd etc. product stack?  Hopefully this isn't too confusing.  I haven't looked in JIRA yet to see if this has been reported previously...and I have cleared my browser's cache and cookies before making any of the afore mentioned assertions.

      1. Hi Dan. It sounds like you're suffering from this bug, which can be fixed by applying this patch to the source for the connector.

        If you contact our support team, they'll be able to help you further. 

  13. I am using a .htaccess file in which i setup the same way as described for a location/directory. Whatever i try i cannot login, i do see in the logs that the application in crowd is working (when setting debug to all):

    And i also see that it is loaded with apache:

    I keep getting:

    But the strangest part of it all, if i login to any working crowd authentication (JIRA for instance) and then go to the apache website, it works! (so i also know the username/pwd is correct) perhaps its my somewhat different .htaccess?

    I need the "allows" since i have a crontab running on a php file so it wont ask for a password. I hope i didn't make too big a post, feel free to inform/remove otherwise.

    1. Hi Erik-jan,

      If you contact our support team, they should be able to help you.

  14. Hi,

    two tips when you are using the crowd apache module in a reverse proxy setup and forward requests to atlassian applications within the same SSO domain.

    The follwoing patch helps, so the upstream atlassian application will already have the correct authentication cookie:

    Second, if you use basic authentication you need to remove the authorization header, because it confuses seraph when this is send upstream. Example apache snippet:

  15. Anonymous

    If you are attempting to secure an iOS distribution page ( HockeyKit or others ), or any website that has to embed the user and password in the url for a separate application to consume you will need to set these parameters:

     

    CrowdAcceptSSO Off

      

    CrowdCreateSSO Off

      

     

    This is the only way the iOS app installer will work to fetch an itms-services url that contains the user and pass embedded in itms links, if crowd tries to set the cookie then you will get failures.

     

    example (modded hockeykit's index.php, repeat the modification to the base url in the include file platforms/ios.php):

     


     

     

    This allows a user to log in once to the hockey kit page on their iphone, click download, and not receive several more login prompts.

     

  16. Hi,

    unfortunately the apache crowd connector is not working with our configuration. Do you have any ideas on how to fix this? We use HTTPS, the location to secure is at https://www.tuinvest.de/webapps/TUident and crowd runs on https://tuinvest.de:8446/crowd/

    Thanks in advance for your help!

    Crowd configuration:

      SSO Domain: .tuinvest.de

    .htaccess:

      AuthName "Atlassian Crowd"
      AuthType Basic
      AuthBasicProvider crowd

      CrowdAppName apache
      CrowdAppPassword securepwd
      CrowdURL https://tuinvest.de:8446/crowd/

      CrowdSSLVerifyPeer Off

      Require valid-user

    Crowd Log:

      2013-03-07 23:50:09,702 http-8446-12 DEBUG [crowd.manager.validation.ClientValidationManagerImpl] Client address: 144.76.32.76
      2013-03-07 23:50:09,738 http-8446-12 DEBUG [plugin.rest.filter.BasicApplicationAuthenticationFilter] Application 'apache' authenticated successfully
      2013-03-07 23:50:09,740 http-8446-12 DEBUG [crowd.console.filter.CrowdOpenSessionInViewFilter] Closing single Hibernate Session in OpenSessionInViewFilter

    Apache Log:

      user user.name: authentication failure for "/webapps/TUident": Password Mismatch

    Crowd Version: 2.6.0

  17. Didn't this trigger you?

    These commands must be added to the Apache config. It does not work with .htaccess.

    I should try that if i where you.

    1. SOLVED: Thanks, the statements work inside the apache config!

      A "Password mismatch" error message is a bit confiusing here. Perhaps the statements could be disabled in .htaccess files or it could be supported in the future.

  18. If you are using https, the SSO cookie will not be set. 

    The code that is leading to this behavior is the following in ./src/mod_authnz_crowd.c:

    static bool is_https(request_rec *r) {
         const char *https = apr_table_get(r->subprocess_env, "HTTPS");
         return https != NULL && strcmp(https, "on");
    }
    As strcmp returns 0 on string equality, is_https will actually return false if https is used.
    Correct would be !strcmp.


    1. I've made that change and I'm still getting prompted for authentication when I've previously authenticated directly against Crowd.

      Am I misunderstanding what should happen here? Just to be clear, I'm browsing directly to the Crowd server and logging in. I'm then browsing to my Apache server and it is prompting for credentials.

      Thanks.

       

      1. This change in the sourcecode only affects the behavior concerning https. It would be helpful if you could post your apache config, apache log and crowd log (remember to set crowd logging to a higher log level).

        1. It is working now ... I'm not sure what might have changed overnight but it is now behaving as I would have expected.

          Thanks.

           

  19. Anonymous

    The crowd connector does not work when the response is in expanded format. In the code it has a "TODO: Not yet required" tag. For me it was required! I have created a patch to make it work:

    # patch for mod_crowd to cope with white space and to properly ignore subtrees in <group> elements.
    --- crowd_client.c.org  2012-03-13 00:10:12.000000000 +0100
    +++ crowd_client.c      2012-03-13 00:10:16.000000000 +0100
    @@ -390,6 +390,10 @@
                     break;
                 case 1:
                     node_type = xmlTextReaderNodeType(write_data->xml_reader);
    +                // Ignore whitespace.
    +                if (node_type == XML_READER_TYPE_SIGNIFICANT_WHITESPACE) {
    +                    break;
    +                }
                     if (node_type < 0 || node_type > XML_READER_TYPE_MAX) {
                         node_type = XML_READER_TYPE_NONE;
                     }
    @@ -438,8 +442,20 @@
     
     static bool handle_ignored_elements(write_data_t *write_data, const xmlChar* text) {
         if (!xmlTextReaderIsEmptyElement(write_data->xml_reader)) {
    -        // TODO: Not yet required
    -        return true;
    +        int depth = 0;
    +        while (1) {
    +           int node_type = xmlTextReaderNodeType(write_data->xml_reader);
    +           if (node_type == XML_READER_TYPE_ELEMENT) {
    +              depth++;
    +           } else if (node_type == XML_READER_TYPE_END_ELEMENT) {
    +              if (--depth == 0) {
    +                 return false;
    +              }
    +           }
    +           if (!xmlTextReaderRead(write_data->xml_reader)) {
    +             return true;
    +           }
    +        }
         }
         return false;
     }
    1. The code is in Bitbucket (https://bitbucket.org/atlassian/cwdapache/), so please open pull requests if you think those changes would be helpful to others.

  20. mod_authnz_crowd is compatible with apache httpd 2.4?

    I had issue 'undefined symbol ap_requires'. http://httpd.apache.org/docs/2.4/developer/new_api_2_4.html > REMOVED ap_default_type, ap_requires, all 2.2 authnz API.

    httpd 2.2 - everything is OK, have to rollback to 2.2.

    1. Hi, please check my comment here. It is a patch to make it work under 2.4. It seems Atlassian does not invest time in this connector to support httpd 2.4...

  21. Anonymous

    Hi, I have same problem with apache http 2.4 server. Could anyone please post the updated plugin which supports apache http 2.4.x server for RedHat Linux system. Thanks.

  22. I remember having issues with apache 2.4 over a year ago, and it's still not fixed?! What's wrong with you Atlassian?

    As a user, I expect the modules be available in yum and apt repos, compiled and ready, not in some repo as a half-baked source code, for which I have to scrape patches from random places. There not even a possibility to open an issue at bitbucket.

    This is almost as unprofessional as it gets.

    1. There not even a possibility to open an issue at bitbucket.

      We use JIRA for tracking issues with the Crowd Apache connector, but I just noticed there was no pointer to it from the Bitbucket repository. Sorry about that; I've added that to the project's readme.