Skip to content

Latest commit

 

History

History
296 lines (212 loc) · 13.1 KB

chapter-crowd.asciidoc

File metadata and controls

296 lines (212 loc) · 13.1 KB

Atlassian Crowd Support

{inrmonly}

Atlassian Crowd is a single sign-on and identity management product that many organizations use to consolidate user accounts and control which users and groups have access to which applications. {pro} contains a security realm that allows you to configure the repository manager to authenticate against an Atlassian Crowd instance.

The following steps are necessary to configure Crowd-based authentication:

Note
Atlassian Crowd support is a {pro} feature.

Prepare Nexus for Atlassian Crowd

Atlassian Crowd support is preinstalled and ready to configure in {pro} 2.7+.

In older versions, Crowd support is implemented as an optional plugin that comes as part of any {pro} download. The directory containing the plugin code is called either enterprise-crowd-plugin-X.Y.Z or nexus-crowd-plugin-X.Y.Z. Install the plugin following the instructions in [install-additional-plugins].

Warning
Using LDAP and Crowd Realms together in the repository manager may work, but this is not supported. If you already use LDAP support, we recommend adding your LDAP server as a Crowd directory accessible to the Crowd 'nexus' application instead of using both LDAP and Crowd realms in the repository manager.

Prepare Atlassian Crowd

Compatibility

Always use the latest version of Crowd available at the time your version of {pro} was released. When upgrading to a newer Crowd server, carefully review the Crowd server release notes for REST API backwards compatibility issues.

Crowd support in {pro} 2.7 and greater only works in Crowd versions (2.1+) that support the Crowd REST API. Older versions use a deprecated SOAP-based API and are less reliable and performant.

Crowd support is actively tested with the highest available version of Crowd at the time {pro} is released.

Configure a {pro} Application in the Atlassian Crowd Server

Note
These instructions are a general guide to adding an application to Crowd. For current detailed instructions, visit the official Crowd documentation.

To connect {pro} to Atlassian’s Crowd, you will need to configure {pro} as an application in Crowd.

  1. Login to Crowd as a user with administrative rights.

  2. Click on the 'Applications' tab.

  3. Click 'Add Application' to display the form shown in Creating a Nexus Crowd Application, and create a new application with the following values in the 'Details' tab of the Add Application form:

    • Application Type: Generic Application

    • Name: nexus

    • Description: {pro}

  4. Choose a password for this application. Nexus will use this password to authenticate with the Crowd server. Click on the Next button.

crowd new app
Figure 1. Creating a Nexus Crowd Application

Clicking on 'Next' will advance the form to the 'Connection' tab shown in Creating a Nexus Crowd Application Connection. In this tab you need to supply the URL of your application instance and the remote IP address for {pro}. Creating a Nexus Crowd Application Connection, shows the Connection form configured for a local instance of {pro}. If you were configuring Crowd and {pro} in a production environment, you would supply the URL that users would use to load the repository manager user interface in a web browser and you would supply the IP address that the repository manager will be connecting from. Once you have completed the 'Connection' form, click on 'Next' to advance to the 'Directories' form shown in Choosing Atlassian Crowd Application Directories.

crowd new app connection
Figure 2. Creating a Nexus Crowd Application Connection

The 'Directories' form allows you to select the user directory used for Nexus authentication. In this example, the default 'User Management' directory will be used.

crowd new app directories
Figure 3. Choosing Atlassian Crowd Application Directories

Clicking on the 'Next' button in the 'Directories' form advances to the 'Authorisation' form shown in Creating a Nexus Crowd Application Authorization. If any of the directories selected in the previous form contain groups, each group is displayed on this form next to a checkbox. You can select 'Allow all users' for a directory or you can select specific groups that are allowed to authenticate to {pro} via Crowd. This option would be used if you wanted to limit repository manager access to specific subgroups within a larger Crowd directory. If your entire organization is stored in a single Crowd directory, you may want to limit repository manager access to a group that contains only developers and administrators.

crowd new app authorization
Figure 4. Creating a Nexus Crowd Application Authorization

Configure {pro} Crowd Integration

Configure {pro} to Trust Crowd’s Secure URL (Optional)

Although optional, we advise the connection from {pro} to your Crowd server to use the HTTPS protocol.

If the Crowd Server certificate is not signed by a public certificate authority, you may have to explicitly trust the server certificate using SSL support. A common symptom observed are peer not authenticated messages, when trying to connect to the Crowd server.

Steps to explicitly trust the Crowd Server URL certificate in {pro} are:

Note
The 'SSL: Crowd' capability is only available in {pro} 2.7+. Older versions must manually configure trust using an explicit truststore specified with JRE system properties.
Enabling the SSL: Crowd Capability
  1. Login to Nexus as an Administrator.

  2. In the sidebar menu, click 'Administration' → 'Capabilities' to open the 'Capabilities' panel.

  3. Click the 'Add' button in the panel toolbar. Select 'SSL: Crowd' in the 'Type' field. Make sure the 'Enabled' checkbox is checked, and click the 'Save' button.

crowd capability ssl
Figure 5. SSL: Crowd Capability
Adding the Crowd Server Certificate to the Truststore

In order to add the server certificate of your Crowd server to the truststore, locate the HTTPS 'Crowd Server URL' and follow the 'Load from server' instructions in [ssl-sect-client-cert-mgt].

Configure Nexus Crowd Connection

The Crowd Configuration screen displayed in Crowd Configuration Panel can be accessed by users with administrative privileges in {pro} by selecting 'Crowd' in the 'Security' section of the main menu.

crowd server config
Figure 6. Crowd Configuration Panel

This panel contains the following fields:

Application Name

This field contains the application name of a Crowd application. This value should match the value in the Name field of the form shown in Creating a Nexus Crowd Application.

Application Password

This field contains the application password of a Crowd application. This value should match the value in the Password field of the form shown in Creating a Nexus Crowd Application.

Crowd Server URL

This is the URL used to connect to the Crowd Server. Both 'http://' and 'https://' URLs are accepted. You may need to trust the crowd server certificate if a 'https://' URL is used.

HTTP Timeout

The HTTP Timeout specifies the number of milliseconds the repository manager will wait for a response from Crowd. A value of zero indicates that there is no timeout limit. Leave the field blank to use the default HTTP timeout.

You can use the 'Test Connection' button to validate if your connection to Crowd is working. Once you have a working connection, do not forget to 'Save' your configuration. Use 'Cancel' to abort saving any changes.

Configure {pro} Crowd Security

There are two approaches available to manage what privileges a Crowd user has when they login to {pro}.

Note
Mapping Crowd Groups to {pro} Roles is preferable because there is less configuration is involved overall in {pro} and assigning users to Crowd groups can be centrally managed inside of Crowd by your security team after the initial repository manager setup.

Mapping a Crowd Group to {pro} Role

When mapping a Crowd group to a {pro} role, you are specifying the permissions ( via roles ) that users within the Crowd group will have after they authenticate.

To map a Crowd group to a {pro} role, open the 'Roles' panel by clicking on the 'Roles' link under the 'Security' section of the sidebar menu. Click on the 'Add…​' button and select 'External Role Mapping' as shown in Adding an External Role Mapping and the Map External Role dialog.

crowd add ext role mapping
Figure 7. Adding an External Role Mapping
crowd map ext role
Figure 8. Mapping an External Crowd Group to a {pro} Role

After choosing the 'Crowd' realm, the 'Role' drop-down should list all the Crowd groups the 'nexus' crowd application has access to. Select the group to would like to map in the 'Role' field and click 'Create Mapping'.

Note
If you have two or more groups in Crowd accessible to the 'nexus' application with the same name but in different directories, the repository manager will only list the first one that Crowd finds. Therefore, Crowd administrators should avoid identically named groups in Crowd directories.

Before saving the group-to-role mapping, you 'must' add at least one {pro} role to the mapped group. After you have added the roles using the 'Add' button, click the 'Save' button.

crowd ext role mapping unsaved
Figure 9. Unsaved Mapping of External Crowd 'dev' Group to Developers Role

Saved mappings will appear in the list of roles with a mapping value of 'Crowd', as shown in Mapped External Crowd 'dev' Group to Nexus Developers Role.

crowd ext role mapped
Figure 10. Mapped External Crowd 'dev' Group to Nexus Developers Role

Mapping a Crowd User to Nexus Role

To illustrate this feature, consider the Crowd server user with an id of brian. As visible in the Crowd administrative interface in Crowd Groups for User "brian", the user is a member of the dev group.

crowd view user groups brian
Figure 11. Crowd Groups for User "brian"

To add an 'External User Role Mapping', open the 'Users' panel in the repository manager by clicking 'Users' in the 'Security' section of the sidebar menu.

Click on the 'Add…​' button and select 'External User Role Mapping' from the drop-down as shown in Adding an External User Role Mapping.

crowd add ext user role mapping
Figure 12. Adding an External User Role Mapping

Selecting 'External User Role Mapping' will show a mapping panel where you can locate a user by Crowd user id.

crowd find external user
Figure 13. Locate a Crowd User by User ID

Typing the Crowd user id - for example brian - in the 'Enter a User ID' field and clicking the magnifying glass icon, will cause the repository manager to search for a user ID brian in all known realms, including Crowd.

Once you locate the Crowd user, use 'Add' button to add roles to the Crowd User. You must map at least one role to the Crowd managed user in order to 'Save'. Mapped External Crowd User Example displays the 'brian' Crowd realm user as a member of the 'dev' Crowd group and the mapped role called 'Nexus Administator Role'. External groups like dev are bolded in the 'Role Managment' list.

crowd ext user mapped
Figure 14. Mapped External Crowd User Example

Activate {pro} Crowd Realm

The final step to allow Crowd users to authenticate against {pro} is to activate the Crowd authorization realm in the 'Security Settings' displayed in Activating the Crowd Realm.

crowd activate realm
Figure 15. Activating the Crowd Realm
  1. Select 'Administration' → 'Server' from the sidebar menu.

  2. Scroll down to the 'Security Settings' section.

  3. Drag 'Crowd Realm' from the list of 'Available Realms' to the end of the 'Selected Realms' list.

  4. 'Save' the server settings.