This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Configuring Authentication

This document describes the necessary steps to setup authentication through your desired single sign-on (SSO) provider: Microsoft Entra ID, Okta, or Google.

Atolio requires a single sign-on (SSO) provider for two purposes:

  • To enable authentication using the OpenID Connect (OIDC) protocol, as outlined in this document.
  • To support user mappings, ensuring that a user’s identity is mapped correctly across the variety of sources where those users do their work. Refer to configuring sources for additional information.

Note: For particular connectors (e.g. Google Drive, Gmail), the steps outlined below for Google are also required even if your authentication provider is different (e.g. Okta).

Identity Provider Configuration

1 - Google

Use Google as your Identity Provider.

Create OAuth Client

Note: The instructions in this section are only needed when Google is used for authentication of the Atolio web application.

Create a new project in the Google Cloud Console by visiting https://console.cloud.google.com/cloud-resource-manager and clicking CREATE PROJECT. Provide a project name (e.g. Atolio) and select the correct Organization and Location. Note the Project ID field displayed below the Project name. You’ll need this value when setting up Terraform later. Click CREATE.

This project will be used to create credentials for the Google OAuth Client (for authenticating Atolio users) and to create necessary resources to (allow) access to the Google Workspace by the Atolio stack later on.

Create the Google OAuth Client using the following steps:

  1. Visit https://console.cloud.google.com/apis/credentials/consent to set up the OAuth consent screen.
  2. Select Internal for User Type and click CREATE.
  3. Provide Atolio for the App name and enter email addresses for both support and developer contact information.
  4. Press SAVE AND CONTINUE.
  5. In the next Scopes screen there is no need for changes, just click SAVE AND CONTINUE again.
  6. Review your changes in the next Summary screen and click BACK TO DASHBOARD.

The OAuth credentials (client ID and secret) can now be created by:

  1. Navigating to https://console.cloud.google.com/apis/credentials and clicking CREATE CREDENTIALS in the top menu bar.
  2. Then select OAuth client ID from the drop down menu.
  3. For application type on the next screen choose Web application and fill out the rest of the form as shown in the table below (using your own domain name instead of the example).
  4. Click CREATE. The OAuth client will be created providing you with a Client ID and Secret.
  5. Download the JSON file.
Field NameField Value
Application typeWeb application
Authorized JavaScript originshttps://search.example.com
Authorized redirect URIshttps://search.example.com/auth/_callback

The client ID and secret which will be needed later in the deployment process as described below. We recommend storing this information in a safe place (e.g. 1Password secure note) to be shared with your Deployment Engineer.

2 - Microsoft Entra ID

Use Microsoft Entra ID as your Identity Provider.

Create New App Registration

  1. Authenticate to the Azure Portal via your Microsoft Identity.
  2. Head over to App Registrations.
  3. Click “New Registration”:
    • Enter “Atolio” for the name.
    • Ensure “Accounts in this organizational directory only” is selected from Supported account types.
    • Add a redirect URI https://search.example.com/auth/_callback.
    • Click “Register”.
  4. You should now be on the page of your new app registration. In the Essentials blade, locate the “Add a certificate or secret” link.
  5. Create a Client Secret for use with OIDC:
    • Select the “Client Secrets (0)” tab.
    • Click “New Client Secret”.
    • Enter “Atolio OIDC Authentication” for the description.
    • Set desired expiry. Follow internal procedures for rotation.
    • Copy the newly created “Value” of the Client Secret and store it in a safe place (e.g. 1Password). This will be referenced later for OIDC configuration.
  6. Add a certificate for client authentication:
    • Obtain a .PFX file that includes the public and private keys. If you’re using the SharePoint connector, the certificate key algorithm must be RSA, as this is currently the only supported algorithm. A private key password is optional, but recommended.
    • Export the public key to a .CER file.
    • Select the “Certificates (0)” tab.
    • Click “Upload certificate”.
    • Enter “Atolio Client Authentication” for the description.
    • Select the .CER file and select “Add”.
    • Export the .PFX file contents to base 64 and store it in a safe place (e.g. 1Password). You can obtain the base 64 encoding from the command line with cat my-cert.pfx | base64. This value will be referenced later for source configuration.
  7. Finally, revisit the app registration Overview and copy the Directory (tenant) ID as well as the Application (client) ID. These will be used later when configuring Active Directory.

Note: If you are configuring the SharePoint connector later, this app registration will also require API Permissions. These can be found in Installing the Microsoft Connector (Entra ID & SharePoint).

3 - Okta

Use Okta as your Identity Provider.

Create OAuth Client

Note: The instructions in this section are only needed when Okta is used for authentication of the Atolio web application.

  1. Navigate to Applications in the Okta admin console (https://example.okta.com/admin/apps/active).
  2. Click “Create App Integration”.
  3. Select “OIDC - OpenID Connect” from the list of Sign-in methods.
  4. Select “Web Application” from the list of Application types and hit “Next” to create the app.
  5. (Optional) Edit the name and provide the Atolio logo for the app.
  6. Under “Grant type” –> “Client acting on behalf of a user”, ensure that “Authorization Code” is enabled.
  7. Under “Sign-in redirect URIs”, add the URL https://search.example.com/auth/_callback (note this is identical for Google).
  8. Under “Sign-out redirect URIs”, remove the default http://localhost:8080 URI.
  9. Under “Assignments”, choose who should have access to the Atolio app. This setting can be modified later. If you choose to “Skip group assignment for now”, remember to add yourself to the Assignments list in order to be able to sign-in.
  10. Click “Save”.
  11. Under “Client Credentials”, copy the “Client ID” & “Client Secret” and save them for later.

Setup Okta Connector

Once your Atolio infrastructure has been deployed, you will also need to setup the Okta Connector to enable users and user mappings using an API token.