External authentication with SAML and GSuite

Users authentication with SAML and GSuite

If you are going to implement this type of authentication this action implies you clearly understand what you are doing.

Prerequisites

  1. You need to have administrative access to GSuite or an admin near you.
  2. You need the access to Allure TestOps configuration files.
  3. You need to be able to apply the changes in the configuration, which could require some downtime.
  4. Allure TestOps needs work behind HTTPS, i.e. there must be something like reverse proxy between Allure TestOps and GSuite servers. Please consult your network administrator or DevOps to ensure proper configuration on the network side.

Integration of Allure TestOps and GSuite

Given

  1. Allure TestOps is deployed and accessible on http://allure.local your URLs will be different.
  2. GSuite administration is accessible on https://admin.google.com.

Creating new application in GSuite

In GSuite (https://admin.google.com):

  1. Go to Web and mobile apps.

if you see this text, report to support.qameta.io

  1. Click Add app then Add custom SAML app.

if you see this text, report to support.qameta.io

  1. Add a name (we prefer Allure TestOps) and an icon for the application if you want, then press Continue.
  2. In the next screen click Download metadata and save metadata to a file to your local PC (say, it’ll be metadata.xml).

if you see this text, report to support.qameta.io

  1. Add all the needed information as follows:
    • ACS URL: https://allure.local/api/login/saml2/sso/gsuite
    • Entity ID: https://allure.local/api/login/saml2/service-provider-metadata/gsuite
    • Name ID format: EMAIL
    • Name ID: Basic Information > Primary email
  2. Then press Continue and finally Finish.

Configuring Allure TestOps

Making metadata file available via some URL

We downloaded metadata.xml, remember?

Now, you need to make this file available for Allure TestOps gateway service. This will be required for all the deployment options.

A few options here:

  1. File can be added to gateway’s volume and it will be added to gateway parameters like file file:///path/to/metadata.xml
  2. File can be provided via some URL, and it will be added to gateway parameters like URL https://some.url/metadata.xml.

Deployment in Kubernetes

For k8s deployment you need to add the parameters to open environment of gateway service of values.yaml file used to pass user’s configuration to Helm.

<snip>
gateway:
  env:
    secret:
      # security
      SPRING_SECURITY_SAML2_RELYINGPARTY_REGISTRATION_GSUITE_ACS_LOCATION: https://allure-local/api/login/saml2/sso/gsuite
      SPRING_SECURITY_SAML2_RELYINGPARTY_REGISTRATION_GSUITE_ENTITYID: https://allure.local/api/login/saml2/service-provider-metadata/gsuite
      SPRING_SECURITY_SAML2_RELYINGPARTY_REGISTRATION_GSUITE_IDENTITYPROVIDER_METADATAURI: https:///some.url/metadata.xml
<snip>

Now, to use GSuite as Identity provider, you need to update your Allure TestOps configuration as usual for Kubernetes installation using Helm’s commands.

Deployment via docker-compose

For the deployment done via docker-compose you need to update docker-compose.yaml configuration file by adding the parameters to gateway service.

Updating of the configuration requires downtime to properly stop and run the application.

  gateway:
    <snip>
    environment:
      SPRING_SECURITY_SAML2_RELYINGPARTY_REGISTRATION_GSUITE_ACS_LOCATION: https://allure.local/api/login/saml2/sso/gsuite
      SPRING_SECURITY_SAML2_RELYINGPARTY_REGISTRATION_GSUITE_ENTITYID: https://allure.local/api/login/saml2/service-provider-metadata/gsuite
      SPRING_SECURITY_SAML2_RELYINGPARTY_REGISTRATION_GSUITE_IDENTITYPROVIDER_METADATAURI: https:///some.url/metadata.xml

<snip>

To update Allure TestOps for the usage GSuite as identity provider you need to perform the same actions you do for updating Allure TestOps using docker-compose commands. , i.e. 1) down, 2) then start the application using up -d

Deployment via packages

Update properties file /opt/allure-ee/gateway/conf/allure-gateway.properties with the following string:

spring.security.saml2.relyingparty.registration.gsuite.acs.location=https://allure.local/api/login/saml2/sso/gsuite
spring.security.saml2.relyingparty.registration.gsuite.entityId=https://allure.local/api/login/saml2/service-provider-metadata/gsuite
spring.security.saml2.relyingparty.registration.gsuite.identityprovider=https:///some.url/metadata.xml

Setting the default authentication way

When you’ve updated the settings and these were successfully applied, you need to check the authentication by trying to log in using the following URL:

https://allure.local/login/oauth2,

Your URL will differ, you remember, right? Only this part you need to take for test from this guide: /login/oauth2

When you’ve successfully tested the authentication, you can switch to SAML2 as main authentication method.

Deployment in Kubernetes

uaa:
<snip>
  env:
    open:
      ALLURE_LOGIN_PRIMARY:saml2
<snip>

Deployment via docker-compose

  uaa:
  <snip>
    environment:
      ALLURE_LOGIN_PRIMARY: saml2

Deployment via packages

Update properties file /opt/allure-ee/uaa/conf/allure-uaa.properties with the following string:

allure.login.primary=saml2

Setting the default role for new user registering via saml/gsuite

Why

If no additional setting made all new users will have ROLE_USER by default and will consume 1 license.

What

To prevent new users consuming the licenses you need to define the default role for them as ROLE_AUDITOR, when they register in the system using saml/gsuite. This will ensure they will have read only access by default and won’t consume any licenses in the system.

How

The following parameter should be set for UAA service:

For docker-compose and Kubernetes deployment

ALLURE_LOGIN_SAML2_DEFAULTROLE: ROLE_AUDITOR

For the deployment using packages

allure.login.saml2s.defaultRole: ROLE_AUDITOR