Skip to main content

Auth0 Integration Documentation

The following document contains information on how to integrate Auth0 with Archipelo.

APIs​

In order to fully integrate Auth0 we need to create 2 APIs in the Applications menu in the APIs section:

  • Auth0 Management API of type System API
  • Archipelo API of type Custom API

Custom API​

The API of type Custom API should have the following options set:

  • Name: Archipelo API
  • Identifier:
    • QA: https://qa.app.archipelo.com
    • production: https://app.archipelo.com
  • Signing algorithm: RS256

Custom API Permissions​

The following permissions should be defined:

  • create:invitation
  • read:bitbucket-repos
  • read:commit-digest
  • read:events
  • read:github-repos
  • read:gitlab-repos
  • read:invitations
  • read:org
  • read:org-members
  • update:org
  • admin:slack
  • read:oauth
  • admin:oauth
  • read:policies
  • write:policies
  • delete:policies
  • read:policies-status

Custom API Additional Settings​

The following settings need to be set:

  • Enable RBAC
  • Add Permissions in the Access Token
  • Allow Skipping User Consent
  • Allow Offline Access

Social Login​

To enable users to log in via providers such as Google, and GitHub go to Authentication and the Social section and add the following providers:

  • Google
  • GitHub
  • BitBucket
  • GitLab

The first three ones are provided by Auth0 out of the box, while GitLab needs some manual work.

Integrating GitHub​

To integrate GitHub Social Login you need to add a new OAuth application in the Archipelo organization on GitHub and provide:

  • Application name - Auth0 - Prod for production, Auth0 - QA for QA
  • Homepage URL - https://app.archipelo.com
  • Description
  • Authorization Callback URL:
    • production: https://archipeloprod.us.auth0.com/login/callback
    • QA: https://dev-xbwsyf33zbu4e8dk.us.auth0.com/login/callback

The created OAuth application will allow to get the Client ID and Secret, which needs to be provided in Auth0 configuration.

In addition you need to check:

  • Email address in the Attributes section
  • read:user in the Permissions section

Integrating BitBucket​

To integrate BitBucket Social Login you need to add a new OAuth consumer in BitBucket in the Archipelo organization and provide:

  • Application name - Auth0 - Prod for production, Auth0 - QA for QA
  • Homepage URL - https://app.archipelo.com
  • Description
  • Authorization Callback URL:
    • production: https://archipeloprod.us.auth0.com/login/callback
    • QA: https://dev-xbwsyf33zbu4e8dk.us.auth0.com/login/callback

The created OAuth application will allow to get the Key and Secret, which needs to be provided in Auth0 configuration.

In addition you need to allow the following permissions:

  • Account - Email
  • Account - Read

Integrating GitLab​

To integrate GitLab Social Login you need to add a new Application in GitLab and provide:

  • Application name - Auth0 - Prod for production, Auth0 - QA for QA
  • Redirect URL:
    • production: https://archipeloprod.us.auth0.com/login/callback
    • QA: https://dev-xbwsyf33zbu4e8dk.us.auth0.com/login/callback

In addition you need to allow the following scopes:

  • read_user
  • openid
  • profile
  • email

Note down the Application ID and copy the Secret.

In Auth0 create a new Custom Social Connection and provide:

  • Name: GitLab
  • Authorization URL: https://gitlab.com/oauth/authorize
  • Token URL: https://gitlab.com/oauth/token
  • Scope: email read_user profile openid
  • Client ID - the Client ID from GitLab
  • Client Secret - the Secret from GitLab

Finally, the following script needs to be provided in the Fetch User Profile Script configuration section:

function(accessToken, ctx, cb) {
    request.get({
            url: 'https://gitlab.com/oauth/userinfo',
            headers: {
                'Authorization': 'Bearer ' + accessToken,
            }
        },
        (err, resp, body) => {
            if (err) {
                return cb(err);
            }
            if (resp.statusCode !== 200) {
                return cb(new Error(body));
            }
            let bodyParsed;
            try {
                bodyParsed = JSON.parse(body);
            } catch (jsonError) {
                return cb(new Error(body));
            }
            const profile = {
                user_id: bodyParsed.sub,
                email: bodyParsed.email,
                picture: bodyParsed.picture,
                name: bodyParsed.name,
            };
            cb(null, profile);
        }
    );
}

Roles​

We need to pre-create the roles in Auth0. You do that by creating the following roles:

  • Account Owner
    • Name: Account Owner
    • Description: Account owner role
  • Code Contributor
    • Name: Code Contributor
    • Description: Code contributor role
  • Digest Reviewer
    • Name: Digest Reviewer
    • Description: Digest reviewer role

Account Owner Permissions​

The Account Owner role should have the following permissions defined:

  • create:invitation
  • read:bitbucket-repos
  • read:commit-digest
  • read:events
  • read:github-repos
  • read:gitlab-repos
  • read:invitations
  • read:org
  • read:org-members
  • update:org
  • admin:slack
  • admin:oauth
  • read:policies
  • write:policies
  • delete:policies
  • read:policies-status

Code Contributor Permissions​

The Code Contributor role should have the following permissions defined:

  • read:bitbucket-repos
  • read:commit-digest
  • read:events
  • read:github-repos
  • read:gitlab-repos
  • read:invitations
  • read:org
  • read:org-members
  • read:oauth
  • read:policies
  • read:policies-status

Digest Reviewer Permissions​

The Digest Reviewer role should have the following permissions defined:

  • read:bitbucket-repos
  • read:commit-digest
  • read:github-repos
  • read:gitlab-repos
  • read:invitations
  • read:org
  • read:org-members
  • read:oauth
  • read:policies
  • read:policies-status

Auth Pipeline​

The Auth Pipeline needs to be adjusted by adding additonal actions.

Force email verification​

Click on the Build Custom in the Actions tab, the Library section and add the following action:

  • Name: Force Email Verification
  • Trigger: Login / Post Login
  • Runtime: Node 18

It should have the following content:

exports.onExecutePostLogin = async (event, api) => {
    if (!event.user.email_verified) {
        api.access.deny('Please verify your email before logging in');
    }
};

Once deployed go to Flows section, select the Login flow and add the newly created custom action to the Login flow after the Rules (legacy) action.

Add org name​

Click on the Build Custom in the Actions tab, the Library section and add the following action:

  • Name: Add org name
  • Trigger: Login / Post Login
  • Runtime: Node 18

It should have the following content:

exports.onExecutePostLogin = async (event, api) => {
    const orgID = event.organization?.id;
    if (orgID) {
        api.accessToken.setCustomClaim("orgID", orgID);
    }
};

Once deployed go to Flows section, select the Login flow and add the newly created custom action to the Login flow after the Add org name action.

Add Email To Access Token​

Click on the Build Custom in the Actions tab, the Library section and add the following action:

  • Name: Add Email To Access Token
  • Trigger: Login / Post Login
  • Runtime: Node 18

It should have the following content:

exports.onExecutePostLogin = async (event, api) => {
    var namespace = "https://app.archipelo.com/";

    api.accessToken.setCustomClaim(namespace + "email", event.user.email);
    api.accessToken.setCustomClaim("email", event.user.email);
    api.accessToken.setCustomClaim("authorization", event.authorization);
    api.idToken.setCustomClaim("user_metadata", event.user.user_metadata);

    const orgID = event.organization?.id;
    if (orgID) {
        api.accessToken.setCustomClaim(namespace + "org", orgID);
        api.accessToken.setCustomClaim("org", orgID);
    }
};

Once deployed go to Flows section, select the Login flow and add the newly created custom action to the Login flow after the Rules (legacy) action just above the Add org name action.

Account Linking Extension​

In the Extensions menu find the Auth0 Account Link and install it. Once it is installed, it should be visible in the Rules section of the Auth Pipeline menu.

Applications​

New Applications​

Start by deleting the Default App and creating additonal application:

  • WebApp of type Single Page Application

Application - WebApp​

The Archipelo application of type Regular Web Application should have the following settings:

Setup for QA​
  • Application Login URI set to https://qa.app.archipelo.com/login
  • Allowed Callback URLs set to https://qa.app.archipelo.com, https://qa.app.archipelo.com/auth, https://qa.app.archipelo.com/link
  • Allowed Logout URLs set to https://qa.app.archipelo.com, https://qa.app.archipelo.com/login
  • Allowed Web Origins set to https://qa.app.archipelo.com
  • Allow Cross-Origin Authentication turned on
  • Allowed Origins (CORS) set to https://qa.app.archipelo.com
Setup for Production​
  • Application Login URI set to https://app.archipelo.com/login
  • Allowed Callback URLs set to https://app.archipelo.com, https://app.archipelo.com/auth, https://app.archipelo.com/link
  • Allowed Logout URLs set to https://app.archipelo.com, https://app.archipelo.com/login
  • Allowed Web Origins set to https://app.archipelo.com
  • Allow Cross-Origin Authentication turned on
  • Allowed Origins (CORS) set to https://app.archipelo.com

In the Connections tab all the social connections should be turned on.

Set Up API Permissions​

Go to the Archipelo API (Test Application) and turn on the Auth0 Management API for that application.

In addition to that select the following permissions:

  • read:users
  • read:connections
  • read:roles
  • read:organizations
  • update:organizations
  • create:organizations
  • delete:organizations
  • create:organization_members
  • read:organization_members
  • delete:organization_members
  • create:organization_connections
  • create:organization_member_roles
  • read:organization_member_roles
  • delete:organization_member_roles
  • create:organization_invitations
  • read:organization_invitations
  • delete:organization_invitations

Set Up API Role Permissions​

The role permissions are per API - when adding an API you need to add the necessary permissions to it for each role. Otherwise the user with a given role will not be assigned permissions and won't be able to interact with majority of the features.

Web Application Variables​

In order to configure Archipelo web application to correclty use variables pointing to the correct values. The variables are located in the jsapps/apps/web/src/config.ts file and include:

  • AUTH0_AUDIENCE:
    • Production: https://app.archipelo.com
    • QA: https://qa.app.archipelo.com
  • AUTH0_CLIENT_ID:
    • Production: RtJhaqRLbDZ1XmKf8ACCzH1sQoFiKvkQ
    • QA: PAAzXvCVrCqQtjhqGWwDhDXuJ3QrKmjD
  • AUTH0_DOMAIN:
    • Production: archipeloprod.us.auth0.com
    • QA: dev-xbwsyf33zbu4e8dk.us.auth0.com'

Setting Up Chainloop​

In order to setup Chainloop with Auth0 we need to create a new application in the given Auth0 tenant (QA or Production) of type Regular Web Application and note the following properties:

  • Domain
  • Client ID
  • Client Secret

Once you have the values of the above properties add them to appropriate variables in Terraform Cloud:

  • chainloop_oidc_domain should be set to value of the Auth0 Domain property
  • chainloop_oidc_client_id should be set to value of the Auth0 Client ID property
  • chainloop_oidc_client_secret should be set to value of the Auth0 Client Secret property