From 0ea24d1678ad8f5aad9cb096fbbc2ab9d9b6155b Mon Sep 17 00:00:00 2001 From: Nora MA-01 Date: Wed, 22 Jan 2025 01:28:37 +0300 Subject: [PATCH] Add Task Planning functions, Conversational Memories, and Single Sign-On (#1208) --- docs/4-Authentication/github.md | 43 ++++++++++++++++++++ docs/4-Authentication/google.md | 63 ++++++++++++++++++++++++++++++ docs/4-Authentication/microsoft.md | 61 +++++++++++++++++++++++++++++ 3 files changed, 167 insertions(+) create mode 100644 docs/4-Authentication/github.md create mode 100644 docs/4-Authentication/google.md create mode 100644 docs/4-Authentication/microsoft.md diff --git a/docs/4-Authentication/github.md b/docs/4-Authentication/github.md new file mode 100644 index 0000000..237e659 --- /dev/null +++ b/docs/4-Authentication/github.md @@ -0,0 +1,43 @@ +# GitHub Single Sign-On Implementation + +This documentation details how to implement GitHub Single Sign-On (SSO) in your application using the provided `GitHubSSO` class and related functions. + +## Required Environment Variables + +To use the `GitHubSSO` class, you need to have the following environment variables set: + +- `GITHUB_CLIENT_ID`: GitHub OAuth client ID +- `GITHUB_CLIENT_SECRET`: GitHub OAuth client secret + +## Required Scopes for GitHub OAuth + +Ensure your GitHub OAuth application requests the following scopes to access the necessary user information: + +- `user:email` +- `read:user` + +## How to Acquire GitHub OAuth Client ID and Client Secret + +1. **Register a new OAuth application on GitHub:** + - Go to GitHub's developer settings: [GitHub Developer Settings](https://github.com/settings/developers) + - Click on `New OAuth App`. + - Fill in the required fields: + - **Application name**: Your application�s name. + - **Homepage URL**: The URL to your application's homepage. + - **Authorization callback URL**: The redirect URI where users will be sent after authorization. This should match the `redirect_uri` parameter in your authorization request. + - Click `Register application`. + +2. **Get the client credentials:** + - After registering, you will see your new application listed on the OAuth Apps page. + - Click on the application to see its details. + - Copy the `Client ID` and `Client Secret` to use as environment variables in your application. + +3. **Set Environment Variables:** + - Add the `Client ID` and `Client Secret` to your environment variables. This can be done in your `.env` file like so: + + ```env + GITHUB_CLIENT_ID=your_client_id + GITHUB_CLIENT_SECRET=your_client_secret + ``` + + - Replace `your_client_id` and `your_client_secret` with the actual values you copied from GitHub. diff --git a/docs/4-Authentication/google.md b/docs/4-Authentication/google.md new file mode 100644 index 0000000..59bf3e0 --- /dev/null +++ b/docs/4-Authentication/google.md @@ -0,0 +1,63 @@ +# Google SSO Module Documentation + +This module allows you to implement Google Single Sign-On (SSO) and send emails using the Gmail API. + +## Setup Instructions + +### Prerequisites + +Ensure you have the following prerequisites before proceeding: + +1. Python environment with necessary dependencies. +2. Google Cloud project with the required APIs enabled. + +### Step-by-Step Guide + +#### 1. Enable Required APIs + +To use this module, you need to enable two APIs in your Google Cloud project: + +- **People API:** This API is required to fetch user information such as names and email addresses. Enable it [here](https://console.cloud.google.com/marketplace/product/google/people.googleapis.com). +- **Gmail API:** This API is needed to send emails using Gmail. Enable it [here](https://console.cloud.google.com/marketplace/product/google/gmail.googleapis.com). + +#### 2. Obtain OAuth 2.0 Credentials + +Follow these steps to get your OAuth 2.0 credentials: + +1. **Create a Google Cloud Project:** + - Go to the [Google Cloud Console](https://console.cloud.google.com/). + - Click on the project dropdown and select **New Project**. + - Enter the project name and other required information and click **Create**. + +2. **Configure OAuth Consent Screen:** + - In the [Google Cloud Console](https://console.cloud.google.com/), navigate to **APIs & Services > OAuth consent screen**. + - Select **External** for user type if you are making it publicly accessible. + - Fill in the required fields like App name, User support email, Authorized domains, etc. + - Save the details. + +3. **Create OAuth 2.0 Client ID:** + - Go to **APIs & Services > Credentials**. + - Click on **Create Credentials** and choose **OAuth 2.0 Client ID**. + - Configure the application type. For web applications, you need to specify the **Authorized redirect URIs**. + - Save the credentials and note down the **Client ID** and **Client Secret**. + +#### 3. Set Environment Variables + +Add the obtained credentials to your environment variables. Create a `.env` file in your project root directory with the following content: + +```dotenv +GOOGLE_CLIENT_ID=your_google_client_id +GOOGLE_CLIENT_SECRET=your_google_client_secret +``` + +Replace `your_google_client_id` and `your_google_client_secret` with the values you obtained in the previous step. + +### Required Scopes + +The following OAuth 2.0 scopes are required for the module to function correctly: + +- `https://www.googleapis.com/auth/userinfo.profile` +- `https://www.googleapis.com/auth/userinfo.email` +- `https://www.googleapis.com/auth/gmail.send` + +Ensure these scopes are specified when requesting user consent. diff --git a/docs/4-Authentication/microsoft.md b/docs/4-Authentication/microsoft.md new file mode 100644 index 0000000..3f15266 --- /dev/null +++ b/docs/4-Authentication/microsoft.md @@ -0,0 +1,61 @@ +# Microsoft Single Sign-On (SSO) Integration + +## Overview + +This module provides an integration with Microsoft's Single Sign-On (SSO) to allow your application to authenticate users through their Microsoft accounts and send emails using Microsoft's Graph API. + +## Required Environment Variables + +To use the Microsoft SSO integration, you'll need to set up the following environment variables: + +- `MICROSOFT_CLIENT_ID`: Microsoft OAuth client ID +- `MICROSOFT_CLIENT_SECRET`: Microsoft OAuth client secret + +These values can be obtained by registering your application in the Microsoft Azure portal. + +## Setting Up Microsoft SSO + +### Step 1: Register Your Application + +1. Go to the [Azure portal](https://portal.azure.com/). +2. Select **Azure Active Directory**. +3. In the left-hand navigation pane, select **App registrations**. +4. Select **New registration**. +5. Enter a name for your application. +6. Under **Redirect URI**, enter a redirect URI where the authentication response can be sent. This should match the `MAGIC_LINK_URL` environment variable in your `.env` file. +7. Click **Register**. + +### Step 2: Configure API Permissions + +1. Go to the **API permissions** section of your app's registration page. +2. Click on **Add a permission**. +3. Select **Microsoft Graph**. +4. Choose **Delegated permissions** and add the following permissions: + - `User.Read` + - `Mail.Send` + - `Calendars.ReadWrite.Shared` + +### Step 3: Obtain Client ID and Client Secret + +1. In the **Overview** section of your app registration, you will find the **Application (client) ID**. This is your `MICROSOFT_CLIENT_ID`. +2. Go to the **Certificates & secrets** section. +3. Under **Client secrets**, click on **New client secret**. +4. Add a description and choose an expiry period. Click on **Add**. +5. Copy the value of the client secret. This is your `MICROSOFT_CLIENT_SECRET`. Be sure to store it securely. + +### Step 4: Add Environment Variables + +Add the following environment variables to your `.env` file: + +```sh +MICROSOFT_CLIENT_ID=your_client_id +MICROSOFT_CLIENT_SECRET=your_client_secret +``` + +## Required Scopes for Microsoft OAuth + +- `https://graph.microsoft.com/User.Read` +- `https://graph.microsoft.com/Mail.Send` +- `https://graph.microsoft.com/Calendars.ReadWrite.Shared` + +These scopes are requested when obtaining access tokens, allowing your application to read user profile information, send emails on behalf of the user, and access shared calendars.