This document describes how to set up multi-factor authentication (MFA) for Perforce with AuthPoint as an identity provider. Perforce must already be configured and deployed before you set up MFA with AuthPoint.
Perforce can be configured to support MFA in several modes. For this integration, we set up SAML with AuthPoint.
This integration was tested with Helix Core server (P4D) 2019.2 v1918134 on CentOS 7.
Perforce Authentication Data Flow with AuthPoint
AuthPoint communicates with various cloud-based services and service providers with the SAML protocol. This diagram shows the data flow of an MFA transaction for Perforce.
Before You Begin
Before you begin these procedures, make sure that:
- End-users can log in to Perforce
- A token is assigned to a user in AuthPoint
- You have an AuthPoint identity provider (IdP) certificate (see Certificate Management)
To start, you must download the metadata file from the Certificate Management page in the AuthPoint management UI. After you have that, you can configure Perforce.
- Log in to WatchGuard Cloud.
- From the navigation menu, select Configure > AuthPoint. If you have a Service Provider account, you must select an account from Account Manager.
- Select Resources.
- Click Certificate.
- Next to AuthPoint certificate you will associate with your resource, click and select Download Metadata. We recommend that you choose the certificate with the latest expiration date.
The AuthPoint metadata provides your resource, in this case Perforce, with information necessary to identify AuthPoint as a trusted identity provider.
- On your Perforce server, run this command to install the Git tool for Perforce authentication extensions:
yum install git
- Create a folder and navigate to it.
- Run this command to get Helix-Authentication-Service (HAS):
git clone https://github.com/perforce/helix-authentication-service.git
- Run this command to get Helix-Authentication-Extension (HAE):
git clone https://github.com/perforce/helix-authentication-extension.git
- You must replace the certificates in folders because they all expired. You must also assign new certificates by your CA (if you use private CA) or a trusted public CA (if you do not have private CA). In our example, we have a private CA on a Linux server, so we use self-signed certificates to replace the certificates in our folders.
- Copy your ca.crt and ca.key file to a new folder where you will generate all of the certificates. Navigate to the folder.
- Run this command to get the HAE client.key and client.csr files:
openssl req -newkey rsa:4096 -keyout client.key -out client.csr -nodes -days 365 -subj "/CN=LoginExtension"
- Run this command to generate client.crt:
openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -out client.crt -set_serial 01 -days 365
- Run this command to get HAS server.key and server.csr:
openssl req -newkey rsa:4096 -keyout server.key -out server.csr -nodes -days 365 -subj "/CN=AuthService"
- Run this command to generate server.crt:
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -out server.crt -set_serial 01 -days 365
- Delete the client.csr and server.csr files.
- Run this command to replace the expired certificates:
cp ca.* <your prepared folder path>/helix-authentication-service/certs/
- Run this command to replace the expired server certificates:
cp server.* <your prepared folder path>/helix-authentication-service/certs/
- Run this command to replace the expired CA certificates:
cp ca.crt <your prepared folder path>/helix-authentication-extension/loginhook
- Run this command to replace the expired client certificates:
cp client.* <your prepared folder path>/helix-authentication-extension/loginhook
- Navigate to the HAS folder and run this command to install the authentication service:
- To edit the ecosystem.config.js file, run
sudo vi ecosystem.config.js.
- Delete the OIDC_CLIENT_ID, OIDC_CLIENT_SECRET_FILE and OIDC_CLIENT_SECRET_FILE values. Leave the quotation marks and comma.
- Replace the SAML_IDP_SSO_URL value with the SingleSignOnService Location value from the AuthPoint metadata. This value should be 'https://sp.authpoint.usa.cloud.watchguard.com/saml/<WatchGuard Cloud account ID>/sso/spinit'.
- Replace the SAML_IDP_SLO_URL value with the SingleLogoutService Location value from the AuthPoint metadata file. This value should be 'https://sp.authpoint.usa.cloud.watchguard.com/saml/<WatchGuard Cloud account ID>/slo/spinit'.
- For the SAML_SP_ISSUER value, type '<your issuer name here>'. When you configure a SAML resource in AuthPoint, this value is the entityID.
- Replace the SVC_BASE_URI value with your AuthService URL. This value should be 'https://<perforce server instance name>:3000'. Add a comma at the end of this line.
- Comment out the DEFAULT_PROTOCOL line. Delete the comma at the end of this line.
- Save and quit.
- Run this command to reload the file and put your changes into effect:
pm2 startOrReload ecosystem.config.js
- Go to the HAE folder and run this commmand to get a zip file named loginhook.p4-extension:
p4 extension --package loginhook
- Run this command:
p4 extension --install loginhook.p4-extension -y
- You must configure a global configuration for your extension. Run
p4 extension --configure Auth::loginhook.
- Change the ExtP4USER value to super.
- Set the Auth-Protocol value to be saml. This value does not need quotes.
- Set the Service-URL value to be https://<your AuthService URL>/.
- Save and quit.
- You must configure a single instance for your environment. Run
p4 extension --configure Auth::loginhook --name <your instance name>.
- In the ExtConfig section, set enbale-logging to be true in case you need to troubleshoot an issue.
- Set the name-identifier value to be nameID.
- Delete the description for non-sso-groups and add your own group, which bypasses the SSO authentication.
- Set the non-sso-users value to be super. You can also add other users here.
- Set the user-identifier value to be email.
- Save and quit.
- Run this command to restart the service:
p4 admin restart
- If you use private CA certificate, you must trust your CA certificate on every client that will run P4V to connect to P4 server.
Before AuthPoint can receive authentication requests from Perforce, you must add a SAML resource in AuthPoint. You must also assign an access policy for the Perforce resource to the user group(s) that must authenticate to log in.
Add a SAML Resource in AuthPoint
From the AuthPoint management UI:
- From the navigation menu, select Resources.
- From the Choose a Resource Type drop-down list, select SAML. Click Add Resource.
- Type a name for this resource. In our example, we type Perforce.
- From the Application Type drop-down list, select Other.
- In the Service Provider Entity ID text box, type your Perforce issuer name. This should be the same value from the previous section.
- In the Assertion Consumer Service text box, type https://<your Perforce AuthService URL>/saml/sso.
- From the AuthPoint Certificate drop-down list, select the certificate to associate with your resource. This must be the same certificate that you downloaded the metadata for in the previous section.
- Click Save.
Add an Access Policy to AuthPoint
You must have at least one user group in AuthPoint for authentication with Perforce, and you must assign an access policy for the Perforce resource to that group. If you already have a group, you do not have to add another group.
In the AuthPoint management UI:
- From the navigation menu, select Groups.
- To add a new group, click Add Group. If you already have a group that you want to use, select the group to edit it.
- In the Name text box, type a descriptive name for the group.
- (Optional) In the Description text box, type a description of the group.
- In the Access Policy section, click Add Policy.
- In the Add Policy dialog box, from the Resource drop-down list, select the resource you want to add an access policy for.
- (Optional) To require that users type their password before they authenticate for this resource, enable the Require Password Authentication toggle.
- Select the authentication options that users in this group can select from when they authenticate.
For SAML resources, if you select more than one authentication option, users must select one of the available options when they authenticate. For example, if you select OTP and Push, users can choose to type their OTP or approve a push to authenticate. You cannot require that they do both.
- Click Add.
- (Optional) Add one or more safe locations to your group. For more information about safe locations and detailed instructions to add them, see About Safe Locations.
- Click Save.
Add Users to AuthPoint
Before you assign users to a group, you must add the users to AuthPoint. There are two ways to add AuthPoint user accounts:
- Sync users from an external user database
- Add local AuthPoint users
Each user must be a member of a group. You must add at least one group before you can add users to AuthPoint.
To import users from Active Directory, Azure Active Directory, or an LDAP database, you must add an external identity in the AuthPoint management UI. External identities connect to user databases to get user account information and validate passwords.
- To sync users from Active Directory or an LDAP database, you must add an LDAP external identity
- To sync users from Azure Active Directory, you must add an Azure AD external identity
When you sync users from an external user database, you can sync any number of users and they are all added to AuthPoint at one time. Users synced from an external user database use the password defined for their user account as their AuthPoint password.
You can create local AuthPoint users on the Users page in the AuthPoint management UI. Because you can create only one user at a time, you most commonly do this when you want to create test users or to add only a small number of users.
Unlike users synced from an external user database, local AuthPoint users define and manage their own AuthPoint password. When you add a local user account, the user receives an email that prompts them to set their password.
To learn how to add local AuthPoint user accounts, see Add Local AuthPoint Users.
Test the Integration
To test AuthPoint MFA with Perforce, you can authenticate with a mobile token on your mobile device. For SAML resources, you can choose any method (push, QR code, or one-time password).
In this example, we show the push authentication method (users receive a push notification in the mobile app that they must approve to authenticate).
- Open your P4V client.
- Type your server address and user name. Click OK.
A new window appears and redirects you to AuthPoint authentication page.
- Type your user name and password.
- For the authentication method, select Push.
- Click Send.
- Approve the authentication request that is sent to your mobile device.
You are logged in to Perforce.