Configuring Authentication

• 1: Google
• 2: Microsoft Entra ID
• 3: Okta

1 - Google

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.

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

Configure Microsoft Entra ID as your identity provider for user authentication. This App Registration is specifically for authentication purposes and user/group identity mapping.

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 Authentication” 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 (replace search.example.com with your actual Atolio deployment URL - contact your Atolio onboarding support team if you need clarification on the correct URL).
   • 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. The certificate key algorithm must be RSA. 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. Add Microsoft Graph API Permissions:
   • In your App Registration, click “API permissions” in the left menu
   • Click “Add a permission”
   • Select “Microsoft Graph”
   • Click “Application permissions” (not Delegated permissions)
   • Add these permissions:

*Optional: You can omit Directory.Read.All and set disable_full_permissions: true in your configuration for more restrictive access.

⚠️ Important: This App Registration should only contain the directory permissions listed above. Do not add content source permissions (Files, Sites, Teams, etc.) to this registration.

8. Grant Admin Consent:

   • Click “Grant admin consent for [your tenant name]” at the top of the API permissions page
   • Confirm by clicking “Yes”
   • Verify all permissions show “Granted for [your tenant name]” with green checkmarks

9. 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 Entra ID authentication.

Sample Configuration

Here’s a complete YAML configuration example for Entra ID as an identity provider:

connector: microsoft
source: entraid
common:
  enabled: true
  identity-provider: true     # This is the identity provider
  cron-spec: "0 */1 * * *"   # Sync users/groups every hour
secrets:
  client_secret:
    value: "<CLIENT_SECRET_VALUE>"  # From step 5 above
  client_cert:
    value: "<BASE64_ENCODED_PFX_CONTENT>"  # From step 6 above
  client_cert_password:
    value: "<CERTIFICATE_PASSWORD>"  # Optional if no password set
configuration:
  client-id: "<APPLICATION_CLIENT_ID>"      # From step 7 above
  tenant-id: "<DIRECTORY_TENANT_ID>"        # From step 7 above
  disable_full_permissions: true           # Optional: reduces required permissions

Configuration Notes:

• identity-provider: true - Marks this as the identity provider source
• client_secret - Required for OIDC authentication flow
• client_cert - Required for Microsoft Graph API access to sync users/groups
• disable_full_permissions: true - Omits Directory.Read.All permission if you prefer more restrictive access

Important: Separate App Registrations for Content Sources

This App Registration is specifically for authentication and identity provider purposes.

For security and scalability best practices, create separate App Registrations for each Microsoft content source (SharePoint, Teams, OneDrive, Outlook) you plan to configure. Each content source should have its own dedicated App Registration with only the minimum permissions required.

See the individual connector documentation:

• SharePoint Connector
• Teams Connector
• OneDrive Connector
• Outlook Connector

3 - Okta

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.