> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genow.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# User Authentication & SSO

> Find out how users can log in to Genow and how to set up single sign-on (SSO).

**Generally we offer three different authentication methods:**

* Microsoft SSO (Setup steps also needed to later connect SharePoint sites)
* Google OAuth SSO
* Google SAML for the usage of Workspace Groups
* Login via E-Mail

You can find a detailed guide to set up the authentication methods below.

<Note>
  Please provide Genow with at least a support and development service user. Otherwise we will not be able to fully support you. Both users should be added to the groups of global platform admins to receive all necessary permissions.
</Note>

<Tabs>
  <Tab title="Google SSO">
    This guide will walk you through setting up Single Sign-On (SSO) with Google Workspace for Genow. This integration allows your users to sign in using their Google Workspace credentials.

    ## Prerequisites

    * A Google Workspace account
    * A Google Cloud Project (if self hosted)
    * Administrator access to your Genow instance (if self hosted)

    ## Step 1: Project Setup

    1. If Genow runs in a different tenant than your Google Workspace:
       * Go to the [Google Cloud Console](https://console.cloud.google.com)
       * Create a new project for oAuth Settings
    2. If Genow runs in the same tenant as your Google Workspace:
       * Use the existing Genow platform project

    ## Step 2: Configure OAuth Client

    1. In Google Cloud Console, navigate to **APIs & Services** > **Credentials**
    2. Click **Create Credentials** > **OAuth client ID**
    3. Configure the OAuth consent screen:
       * User Type: Internal
       * App name: "Genow SSO"
       * User support email: Your admin email
       * Developer contact information: Your contact email
    4. Create OAuth 2.0 Client ID:
       * Application type: Web application
       * Name: "Genow SSO"
       * Authorized JavaScript origins: Add your Genow platform's identity platform origins
       * Authorized redirect URIs: Add your Genow platform's identity platform redirect URIs
       > Note: The exact origins and redirect URIs will be provided by your Genow platform administrator
    5. Click **Create**
    6. Save the generated:
       * Client ID
       * Client Secret

    ## Step 3: Configure Genow

    1. Log in to your Genow instance as an administrator
    2. Add the following information to the Genow Platform's Secret Manager:
       * `FIREBASE_CLIENT_ID`: Your Google Client ID
       * `FIREBASE_CLIENT_SECRET`: Your Google Client Secret
             <Note>
               If the platform is hosted by Genow, please forward this information to Genow. The following steps will also be performed by Genow in this case.
             </Note>
    3. After adding the secrets, run the following commands to update the infrastructure:
       ```bash theme={null}
       # Update Terraform Configuration
       terraform apply
       # Run CI/CD pipeline to apply changes for your genow application
       ```
    4. Wait for the infrastructure updates to complete

    ## Step 4: Test the Integration

    1. Sign out of Genow
    2. Click the "Sign in with Google" button
    3. You should be redirected to Google's login page
    4. After successful authentication, you should be redirected back to Genow

    ## Important Notes

    * The authentication is handled through Google's OAuth 2.0 protocol
    * We recommend providing access to your Google Cloud project to our support team for better assistance
    * Additional documentation for application roles and user permissions will be provided separately

    ## Troubleshooting

    If you encounter any issues:

    1. Verify all configuration values are correct
    2. Ensure the authorized origins and redirect URIs match exactly
    3. Check that users exist in both systems
    4. Review the Genow logs for any error messages
    5. Verify that the OAuth consent screen is properly configured
    6. Confirm that the project has the necessary APIs enabled

    ## Security Considerations

    * Regularly rotate the client secret
    * Monitor sign-in logs for suspicious activity
    * Keep your Google Cloud project secure
    * Review and audit user access regularly
    * Consider implementing additional security measures like 2FA
  </Tab>

  <Tab title="Google SAML">
    This guide walks you through the process of setting up SAML authentication for the Genow AI Platform in your Google Workspace environment using the manual entry method. This allows you to create Workspace groups and assign permissions on group level.

    ## Prerequisites

    * You must have **Super Admin** access to the Google Workspace Admin Console.

    ***

    ## Part 1: SAML App Configuration

    <Steps>
      <Step title="Create the SAML Application" titleSize="h3">
        1. Log in to the **Google Admin Console** at [admin.google.com](https://admin.google.com).
        2. Navigate to **Apps > Web and mobile apps**.
        3. Click **Add app**, then select **Add custom SAML app**.
        4. Fill in the application details, such as the **App Name** and **Description**, and click **Continue**.
      </Step>

      <Step title="Retrieve Identity Provider (IdP) Information" titleSize="h3">
        You must now collect the Identity Provider data generated by Google to send back to Genow.

        1. Open your newly created **Genow AI Platform app** in Google Admin.
        2. Click on **Service provider details** (or **Download Metadata**).
        3. **Collect the Entity ID** (Format: `https://accounts.google.com/o/saml2?idpid=XXXXX`).
        4. **Collect the SSO URL** (Format: `https://accounts.google.com/o/saml2?idpid=XXXXX&spid=YYYYY`).
        5. **Download the Certificate file** OR copy the text content, making sure to keep the `BEGIN CERTIFICATE` and `END CERTIFICATE` headers.
        6. Navigate to the app settings to find the **SLO URL (Single Logout URL)** and copy it.
      </Step>

      <Step title="Configure Service Provider Details" titleSize="h3">
        On the Service Provider Details screen, enter the exact values listed below:

        * **ACS URL (Assertion Consumer Service):** `https://your-domain.com/api/core/saml/acs`
        * **Entity ID:** `https://your-domain.com/api/core/saml/metadata`

        > **Important:** Replace **"your-domain.com"** with your actual Genow instance domain in the URLs above.

        * Set the **Name ID Format** to `E-Mail`.
        * Set the **Name ID** to `basic information > primary email`.
      </Step>

      <Step title="Add Attribute Mapping for Primary Email" titleSize="h3">
        In the next screen, add an attribute mapping for the **Primary email** and map it to `"email"`.

        * **Note:** You can also add this mapping later on in the SAML app settings using the app configuration screen.
      </Step>

      <Step title="Assign Application to Users" titleSize="h3">
        By default, the newly created app is turned **OFF**.

        1. In the SAML app settings, click **User access**.
        2. Change the service status to **ON** for everyone or specific organizational units.
        3. Click **Save**.
      </Step>
    </Steps>

    ***

    ## Part 2: Group Integration

    <Steps>
      <Step title="Create Admin Account for Delegation (Optional)" stepNumber={6} titleSize="h3">
        You need a Google Workspace admin account to facilitate group syncing via domain-wide delegation.

        1. Navigate to **Users** in the Admin Console.
        2. Create a new user (e.g., `genow-service-admin@your-domain.com`) or identify an existing admin.
           * *If you do not want to create a new admin account, you can also provide the email address of an existing one.*
        3. Ensure this user has **Super Admin** or sufficient privileges to read group memberships via the Admin SDK.
        4. **Record the email address** of this account.
      </Step>

      <Step title="Provide Information to Genow" stepNumber={7} titleSize="h3">
        Send the following **5 items** to your Genow support team to complete the handshake:

        1. **IdP Entity ID** (From Step 2)
        2. **SSO URL** (From Step 2)
        3. **SLO URL** (From Step 2)
        4. **Certificate** (The X.509 content or file from Step 2)
        5. **Admin Account Email** (From Step 6)
      </Step>

      <Step title="Activate Domain-Wide Delegation" stepNumber={8} titleSize="h3">
        **Wait for Genow to provide you with a Client ID** (generated from their GCP project) before proceeding with this step. Once you have the Client ID:

        1. Navigate to **Security > API controls**.
        2. Scroll down to **Domain-wide delegation** and click **Manage Domain Wide Delegation**, then click **Add new**.
        3. **Client ID:** Enter the ID provided by Genow.
        4. **OAuth Scopes:** Add the following two scopes (comma-delimited):
           * `https://www.googleapis.com/auth/admin.directory.group.readonly`
           * `https://www.googleapis.com/auth/admin.directory.group.member.readonly`
        5. Click **Authorize**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Microsoft SSO">
    This guide will walk you through setting up Single Sign-On (SSO) with Microsoft Entra ID (formerly Azure AD) for Genow. This integration allows your users to sign in using their Microsoft Entra ID credentials.

    ## Prerequisites

    * A Microsoft Entra ID tenant
    * Administrator access to your Genow instance

    ## Step 1: Configure Microsoft Entra ID

    1. Sign in to the [Azure Portal](https://portal.azure.com)
    2. Navigate to **Microsoft Entra ID** > **App registrations**
    3. Click **New registration**
    4. Fill in the following details:
       * A name for the application, e.g.: "Genow - PRD"
       * Supported account types: "Accounts in this organizational directory only"
       * Redirect URI - Single-page application (SPA): `https://your-genow-instance.cloud`
    5. Click **Register**

    ## Step 2: Configure Application Settings

    1. In your new app registration, go to **Authentication**
    2. Under "Platform configurations":
       * Remove any existing "Web" platform configuration
       * Add "Single-page application" as platform configuration
       * Enter your application URLs:
         * Application URL: `https://your-genow-instance.cloud/login`
         * Redirect URIs:
           * `https://your-genow-instance.cloud/login`
           * `https://your-genow-instance.cloud`
         > Note: The URLs may differ based on your setup. Please ensure you add the correct URLs for your instance.
    3. Under "Implicit grant and hybrid flows", ensure that both are **disabled**:
       * Access tokens (used for implicit flows)
       * ID tokens (used for implicit and hybrid flows)
    4. Go to **API permissions and select "Application permissions".**
    5. Add the following Microsoft Graph permissions:
       * `User.Read`
       * `email`
       * `profile`
       * `openid`
    6. Click **Grant admin consent**

    ## Step 3: Configure API Scopes

    1. In your app registration, go to **Expose an API**
    2. Add a new scope:
       * Scope name: `genow`
       * Base URI: `api://your-application-id`
       > Note: Replace `your-application-id` with your actual application ID

    ## Step 4: Get Required Information & Hand It Over

    1. In your app registration, note down:
       * Application (client) ID
       * Directory (tenant) ID
    2. Assign the information to the Genow platform:
       * Self-hosted: Navigate to the GCP and save these information in Certificates & secrets
       * Genow-hosted:  Provide Genow with these credentials as well as:
         * `AZURE_CLIENT_ID`: Your application (client) ID
         * `AZURE_CLIENT_SECRET`: Your client secret
         * `AZURE_TENANT_ID`: Your directory (tenant) ID

    <Card title="Handover to Genow" type="note">
      Please securely hand over these information to Genow. We will set up the rest for you. 
    </Card>
  </Tab>

  <Tab title="Login via E-Mail">
    Finally, there is the option for users to log in with their email address and password. Either we or you can set up the users via Firebase. In this case, specific permissions are assigned via the Genow platform.
  </Tab>
</Tabs>