Example Identity Provider configurations

This section provides details for several hosted identity providers, but is not an exhaustive list of supported identity providers.

Auth0

You can use a single app registration for both OIDC and SAML.

OpenID Connect

1. From the admin dashboard, navigate to Applications > Application > click the CREATE APPLICATION button.
2. Enter a meaningful name for the application.
3. Select the Regular Web Applications button, then click Create.
4. On the Settings tab, scroll down to Advanced Settings, and click the Endpoints tab.
5. Click the copy button next to OpenId Configuration.
6. Open a new tab, and paste the URL that you copied in the previous step.
7.  Copy the URL associated with the Issuer field.
8. In a text editor with your .env file, paste that value to OIDC_ISSUER_URI in the service config, as shown in the snippet below.
9. On the Settings tab, scroll up to Basic Information, and copy the value of Client ID, as shown in the snippet below.
10. On the Settings tab, scroll up to Basic Information, and copy the value of Client Secret, as shown in the snippet below.
11. On the Settings tab, scroll down to the Allowed Callback URLs text field, and enter the SVC_BASE_URI/oidc/callback value.
12. At the bottom of the page, click the SAVE CHANGES button.

You can now add a user and test the ability to authenticate with this HAS URL: SVC_BASE_URI/requests/new/test

snippet of .env file

OIDC_ISSUER_URI="https://example.auth0.com/"
OIDC_CLIENT_ID="WPHyLwfz_not.valid-4Kmqn0iIGJ3"
OIDC_CLIENT_SECRET="qfvb7G8Wiinf_not.valid-sKdh0Ri7PUWDFzQ"

SAML 2.0

1. From the admin dashboard, navigate to Applications > Application > click the CREATE APPLICATION button.
2. Enter a meaningful name for the application.
3. Select the Regular Web Applications button, then click Create.
4. On the application Settings screen, add SVC_BASE_URI/saml/sso to the Allowed Callback URLs field.
5. At the bottom of the page, click the SAVE CHANGES button.
6. Click the Addons tab near the top of the application page.
7. Click the SAML2 WEB APP button to enable SAML 2.0. A modal dialog pops up.
8. Click the Settings tab.
9. Enter SVC_BASE_URI/saml/sso for the Application Callback URL
10. Ensure the Settings block looks something like the following:

{
   "signatureAlgorithm": "rsa-sha256",
   "digestAlgorithm": "sha256",
   "nameIdentifierProbes": [
      "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
   ]
}

11. Click the ENABLE button at the bottom of the page.
12. On the Usage tab of the Addon screen, copy the Identity Provider Metadata to the SAML_IDP_METADATA_URL setting in the .env file.
13. In the .env file, make sure to set SAML_WANT_RESPONSE_SIGNED=false because there is no way to configure this IdP to enforce that both the assertion and the response are signed.

You can now add a user and test the ability to authenticate with this HAS URL: SVC_BASE_URI/requests/new/test

snippet of .env file

SAML_IDP_METADATA_URL="https://example.auth0.com/samlp/metadata/WPHyLwfz_not.valid-4Kmqn0iIGJ3"
SAML_WANT_RESPONSE_SIGNED=false

Microsoft Entra ID

For Microsoft Entra ID (formerly known as Azure Active Directory), you can use a single app registration for both OIDC and SAML.

OpenID Connect

1. Visit the Microsoft Azure portal.
2. Navigate to Azure Active Directory.
3. Click the Add button, then App Registration.
4. Provide a Name, then click Register.
5. Click Add a Redirect URI.
6. Click Add a Platform.
7. For redirect URIs, enter SVC_BASE_URI/oidc/callback, and click Configure.
8. For App registrations > Overview, click Certificates & secrets, then click New client secret.
9. In the Add a client secret dialog, provide a Description and choose an Expires date, then click Add.
10. Copy the Value and paste it into the .env file as OIDC_CLIENT_SECRET
11. From the Overview page, copy the value of Application (client) ID to the OIDC_CLIENT_ID variable of the .env file.
12. From the Overview page, click the Endpoints button.
13. Copy the value for the OpenID Connect metadata document.
14. Open a new browser tab, and paste that value that you copied in the previous step. (In Firefox, the text appears with proper JSON formatting.)
    
15. Copy the issuer URI and enter it as the OIDC_ISSUER_URI variable in the .env file.
    

You can now add a user and test the ability to authenticate with this HAS URL: SVC_BASE_URI/requests/new/test

snippet of .env file

OIDC_ISSUER_URI="https://login.microsoftonline.com/46710B8B-6742-4BBF-8B80-9C26004E6F99/v2.0"
OIDC_CLIENT_ID="DF2D9BC2-B249-412C-A053-9498E89D039D"
OIDC_CLIENT_SECRET="hmn8Q~OXqvM_not.valid-B2Q96X4mdoso8da-7"

SAML 2.0

1. Visit the Microsoft Azure portal.
2. Click the Add button, then Enterprise application.
3. Click Create your own application.
4. On the Set up single sign on button, click Get started.
5. Click the SAML button.
   
6. For Identifier (Entity ID), enter https://has.example.com
7. Add SVC_BASE_URI/saml/sso to the Reply URL text field.
8. Click the Save button at the top.
9. For SAML Certificates, copy the value of the App Federation Metadata Url.
10. Paste that value to the .env file's SAML_IDP_METADATA_URL as shown in the snippet.
11. In the .env file, set the SAML_NAMEID_FORMAT environment variable to the value "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
12. In the .env file, det the SAML_AUTHN_CONTEXT environment variable to the value "urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified"
13. Make sure the user email address matches the user in Azure Active Directory.
14. From Single sign-on, Step 3 SAML Certificates > Edit > Signing Option > choose Sign SAML response and assertion, then Save.

You can now add a user and test the ability to authenticate with this HAS URL: SVC_BASE_URI/requests/new/test

snippet of .env file

SAML_IDP_METADATA_URL="https://login.microsoftonline.com/46...99/federationmetadata/2007-06/federationmetadata.xml?appid=56...FCD"
SAML_NAMEID_FORMAT="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
SAML_AUTHN_CONTEXT="urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified"

SAML via Azure's Active Directory Gallery

These steps involve a template that might make configuration easier.

1. Visit the Microsoft Azure portal.
2. Select Azure Active Directory.
3. Under Enterprise applications, click New Application.
4. In the Browse Azure AD Gallery page, enter Perforce and select the Perforce Helix Core - Helix Authentication Service.
5. Shorten the Name, if you want, and click the Add button.
6. Wait for the application to be added.
7. In the Single sign-on page, click SAML.
8. In the Basic SAML Configuration section, configure the required fields:
   • For the Entity ID, enter the value of the SAML_SP_ENTITY_ID setting in the .env file.
   •  For the Reply URL, enter SVC_BASE_URI/saml/sso
   •  For the Sign on URL, enter SVC_BASE_URI
9. Click the Save button and close the Basic SAML Configuration window.
10. Click Single sign-on and navigate to the SAML Certificate area.
11. Copy the value in the field for App Federation Metadata Url to the SAML_IDP_METADATA_URL variable in the .env file.
12. From Single sign-on, Step 3 SAML Certificates > Edit > Signing Option > choose Sign SAML response and assertion, then Save.

You can now add a user and test the ability to authenticate with this HAS URL: SVC_BASE_URI/requests/new/test

Azure App Service

HAS supports Azure App Service, which is particularly easy if you deploy by using Docker.

1. From the Azure portal, navigate to App Services.

2. Select the app service that you created previously to run the auth service.

3. Select the Configuration item from the left-side panel

4. In the Application settings tab,

   • set CLIENT_CERT_HEADER to X-ARR-ClientCert

   • add either CLIENT_CERT_CN for the CommonName of the client certificate, or CLIENT_CERT_FP for the FingerPrint of the client certificate.

5. In the General settings tab, change the Client certificate mode to Optional.

6. Click Save and restart the app.

Okta

OpenID Connect

1. On the Okta admin dashboard, navigate to the Applications screen and click the Create App Integration button.

2. Select the OIDC - OpenID Connect option, then select the Web Application option, then click Next.

3. Provide a meaningful App integration name.
4. For the Sign-in redirect URIs , enter SVC_BASE_URI/oidc/callback
5. For Assignments, select an option, then click Save.
6. On the next screen, copy the value of the Client ID, and paste it into the .env file for OIDC_CLIENT_ID
7. Copy the Client secret value OIDC_CLIENT_SECRET into the .env file.
8. From the Sign On tab, click the Edit button.
9. In the OpenID Connect ID Token section, change the Issuer to Okta URL, and click Save.
10. Copy the URL that appears inside the parentheses to OIDC_ISSUER_URI in the .env file.

You can now add a user and test the ability to authenticate with this HAS URL: SVC_BASE_URI/requests/new/test

snippet of .env file

OIDC_ISSUER_URI="https://example-123.okta.com"
OIDC_CLIENT_ID="0oa84gINVALIDLiPr357"
OIDC_CLIENT_SECRET="SChod80xb_VJINVALIDLGYVZCTdD1uchr1C"

SAML 2.0

1. On the Okta admin dashboard, navigate to the Applications screen and click the Create App Integration button.
2. Select the SAML 2.0 option, and click Next.
3. Provide a meaningful name.
4. Click Next.
5. For the Single sign on URL, enter SVC_BASE_URI/saml/sso
6. For the Audience URI (SP Entity ID), enter https://has.example.com
7. Click the Next button to save the changes.
8. There might be an additional screen to click through.
9. From the Sign On tab, copy the value metadata URL to the SAML_IDP_METADATA_URL variable in the .env file.
10. By default, Okta sets Signed for both Response and Assertion Signature, but it is a good practice to verify that the default has not been changed.

You can now add a user and test the ability to authenticate with this HAS URL: SVC_BASE_URI/requests/new/test

snippet of .env file

SAML_IDP_METADATA_URL="https://example-123.okta.com/app/exkinvalidFRgzb357/sso/saml/metadata"

OneLogin

OpenID Connect

1. From the administration dashboard, click Applications > Applications > Add App.
2. Search for "OIDC" and select OpenId Connect (OIDC) from the list.
3. On the Configuration screen, enter a name, such as HAS-your-IP-address-OIDC, and click Save.
4. Click Configuration, enter SVC_BASE_URI/oidc/callback for Redirect URI's
5. Click the Save button.
6. From the SSO tab, copy the Client ID value to the OIDC_CLIENT_ID variable in your .env file.
7. From the SSO tab, click Show Client Secret, and copy the Client Secret value to OIDC_CLIENT_SECRET.
8. From the SSO tab, copy the value of the Issuer URL to the OIDC_ISSUER_URI variable in your .env file.
9. Ensure the Application Type is set to Web.
10. Ensure the Token Endpoint is set to Basic.

You can now add a user and test the ability to authenticate with this HAS URL: SVC_BASE_URI/requests/new/test

snippet of .env file

OIDC_ISSUER_URI="https://example.onelogin.com/oidc/2"
OIDC_CLIENT_ID="209E053F-54D4-406D-AB22-6CC4B62BD263"
OIDC_CLIENT_SECRET="e015d14501928cc83-not-valid-f08bfacf09aae40de1b338"

SAML 2.0

1. From the administration dashboard, click Applications > Applications > Add App.
2. Search for "SAML" and select SAML Custom Connector (Advanced) from the list.
3. Enter a Display Name, such as HAS-YourIPAddress-Saml
4. On the Configuration screen, enter https://has.example.com for Audience (Entity ID)
5. For ACS (Consumer) URL Validator, enter .* to match any value.
6. For ACS (Consumer) URL, enter SVC_BASE_URI/saml/sso
7. For SAML initiator select Service Provider
8. For SAML signature element, set to Both
9. Click the Save button.
10. From the SSO tab, copy the Issuer URL value to the SAML_IDP_METADATA_URL variable in the .env file.

You can now add a user and test the ability to authenticate with this HAS URL: SVC_BASE_URI/requests/new/test

snippet of .env file

SAML_IDP_METADATA_URL="https://app.onelogin.com/saml/metadata/209E053F-54D4-406D-AB22-6CC4B62BD263"

Google Workspace

SAML 2.0

1. Visit the Google Admin console.
2. Click the Apps icon.
3. Click the Web and mobile apps button.
4. Click the Add app > Add custom SAML app.
5. Enter an App name, such as HAS-your-IP-address, and click CONTINUE.
6. On the Google IdP Information screen, copy the SSO URL value to the SAML_IDP_SSO_URL in the .env file.
7. Copy the Entity ID value to the SAML_IDP_ENTITY_ID variable in the .env file.
8. Click the down arrow button associated with Certificate field to download the certificate file for the Google public key.
9. Copy this file to the system running HAS into the directory with the .env file.
10. Edit the .env file to add a new setting called IDP_CERT_FILE by providing the full path to the certificate file.
11. Click CONTINUE.
12. For the ACS URL enter SVC_BASE_URI/saml/sso
13. For the Entity ID enter https://has.example.com
14. Click CONTINUE, and then FINISH, and then OK to complete the initial setup.
15. On the Settings page for the new application, click the EDIT SERVICE button.
16. Change the Service status to ON to enable users to authenticate with this application.

You can now add a user and test the ability to authenticate with this HAS URL: SVC_BASE_URI/requests/new/test

snippet of .env file

SAML_IDP_SSO_URL="https://accounts.google.com/o/saml2/idp?idpid=Xochimilco"
SAML_IDP_ENTITY_ID="https://accounts.google.com/o/saml2?idpid=Xochimilco"
IDP_CERT_FILE="/opt/perforce/helix-auth-svc/google-saml.crt"
SAML_WANT_RESPONSE_SIGNED=false

Ingress NGINX controller in Kubernetes

To configure the ingress-nginx controller in Kubernetes to pass the client certificate to HAS:

Add these annotations to the ingress-nginx controller:

metadata:
    annotations:
        nginx.ingress.kubernetes.io/auth-tls-verify-client: "optional"
        nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: "true"

In the auth service configuration, add the following environment variables:

• CLIENT_CERT_HEADER which must be set to ssl-client-cert

• either CLIENT_CERT_CN for the CommonName of the client certificate, or CLIENT_CERT_FP for the FingerPrint of the client certificate.

Multiple providers

You can configure HAS to support any number of identity providers, each of which can be configured for OIDC, SAML, or both OIDC and SAML.

Each end user can choose the appropriate IdP to authenticate with.

For example, developers in User Group A might know how to authenticate against Auth0 using OIDC, contractors in User Group B might know how to authenticate against Azure using SAML, and the administrators in User Group C might not use SSO.

{
  "providers": [
    {
      "label": "Auth0",
      "protocol": "oidc",
      "issuerUri": "https://p4ever.auth0.com/",
      "clientId": "WPHyLwfzGHdC0g76CksZ4hKmqn0",
      "clientSecret": "qfvb7G8Wi6fCinf010lBXsO_PaSmtIYcwj0icUBPgWnz_sKlDOZdh0"
    },
    {
      "label": "Azure",
      "protocol": "saml",
      "metadataUrl": "https://login.microsoftonline.com/719d88f3/federationmetadata/2007-06/federationmetadata.xml?appid=0122a",
      "spEntityId": "urn:example:sp",
      "nameIdFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
      "authnContext": "urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified"
    }
  ]
}

Common provider settings

SAML provider settings

OIDC provider settings

Next

See After configuring and starting HAS