summaryrefslogtreecommitdiff
path: root/doc/administration/auth/cognito.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/administration/auth/cognito.md')
-rw-r--r--doc/administration/auth/cognito.md53
1 files changed, 30 insertions, 23 deletions
diff --git a/doc/administration/auth/cognito.md b/doc/administration/auth/cognito.md
index db8cdd3e7bb..bb06d5d1a58 100644
--- a/doc/administration/auth/cognito.md
+++ b/doc/administration/auth/cognito.md
@@ -2,41 +2,42 @@
type: concepts, howto
stage: Manage
group: Authentication and Authorization
-info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
---
# Amazon Web Services Cognito **(FREE SELF)**
Amazon Cognito lets you add user sign-up, sign-in, and access control to your GitLab instance.
-The following documentation enables Cognito as an OAuth2 provider.
+The following documentation enables Cognito as an OAuth 2.0 provider.
## Configure AWS Cognito
-To enable the [AWS Cognito](https://aws.amazon.com/cognito/) OAuth2 OmniAuth provider, register your application with Cognito. This process generates a Client ID and Client Secret for your application.
-Any settings you configure in the following procedure can be modified later.
-The following steps enable AWS Cognito as an authentication provider:
+To enable the [AWS Cognito](https://aws.amazon.com/cognito/) OAuth 2.0 OmniAuth provider, register your application with Cognito. This process generates a Client ID and Client Secret for your application.
+To enable AWS Cognito as an authentication provider, complete the following steps. You can modify any settings you configure later.
1. Sign in to the [AWS console](https://console.aws.amazon.com/console/home).
-1. Select **Cognito** from the **Services** menu.
-1. Select **Manage User Pools**, and select the **Create a user pool** button in the top right corner.
-1. Enter the pool name and then select the **Step through settings** button.
+1. From the **Services** menu, select **Cognito**.
+1. Select **Manage User Pools** and then select **Create a user pool** in the top right corner.
+1. Enter the user pool name and then select **Step through settings**.
1. Under **How do you want your end users to sign in?**, select **Email address or phone number** and **Allow email addresses**.
1. Under **Which standard attributes do you want to require?**, select **email**.
-1. Go to the next steps of configuration and set the rest of the settings to suit your needs - in the basic setup they are not related to GitLab configuration.
-1. In the **App clients** settings, select **Add an app client**, add **App client name** and select the **Enable username password based authentication** checkbox.
+1. Configure the remaining settings to suit your needs. In the basic setup, these settings do not affect GitLab configuration.
+1. In the **App clients** settings:
+ 1. Select **Add an app client**.
+ 1. Add the **App client name**.
+ 1. Select the **Enable username password based authentication** checkbox.
1. Select **Create app client**.
-1. In the next step, you can set up AWS Lambda functions for sending emails. You can then finish creating the pool.
+1. Set up the AWS Lambda functions for sending emails and finish creating the user pool.
1. After creating the user pool, go to **App client settings** and provide the required information:
- **Enabled Identity Providers** - select all
- - **Callback URL** - `https://gitlab.example.com/users/auth/cognito/callback`
- - Substitute the URL of your GitLab instance for `gitlab.example.com`
+ - **Callback URL** - `https://<your_gitlab_instance_url>/users/auth/cognito/callback`
- **Allowed OAuth Flows** - Authorization code grant
- **Allowed OAuth2 Scopes** - `email`, `openid`, and `profile`
1. Save changes for the app client settings.
-1. Under **Domain name** include the AWS domain name for your AWS Cognito application.
-1. Under **App Clients**, find your app client ID and app client secret. These values correspond to the OAuth2 Client ID and Client Secret. Save these values.
+1. Under **Domain name**, include the AWS domain name for your AWS Cognito application.
+1. Under **App Clients**, find your app client ID. Select **Show details* to display the app client secret. These values correspond to the OAuth 2.0 Client ID and Client Secret. Save these values.
## Configure GitLab
@@ -49,8 +50,13 @@ The following steps enable AWS Cognito as an authentication provider:
sudo editor /etc/gitlab/gitlab.rb
```
-1. In the following code block, substitute the Client ID (`app_id`), Client Secret (`app_secret`), and the Amazon domain name (`site`) for your AWS Cognito application.
-Include the code block in the `/etc/gitlab/gitlab.rb` file:
+1. In the following code block, enter your AWS Cognito application information in the following parameters:
+
+ - `app_id`: Your client ID.
+ - `app_secret`: Your client secret.
+ - `site`: Your Amazon domain and region.
+
+ Include the code block in the `/etc/gitlab/gitlab.rb` file:
```ruby
gitlab_rails['omniauth_allow_single_sign_on'] = ['cognito']
@@ -59,12 +65,12 @@ Include the code block in the `/etc/gitlab/gitlab.rb` file:
name: "cognito",
label: "Provider name", # optional label for login button, defaults to "Cognito"
icon: nil, # Optional icon URL
- app_id: "CLIENT ID",
- app_secret: "CLIENT SECRET",
+ app_id: "<client_id>",
+ app_secret: "<client_secret>",
args: {
scope: "openid profile email",
client_options: {
- site: "https://your_domain.auth.your_region.amazoncognito.com",
+ site: "https://<your_domain>.auth.<your_region>.amazoncognito.com",
authorize_url: "/oauth2/authorize",
token_url: "/oauth2/token",
user_info_url: "/oauth2/userInfo"
@@ -84,8 +90,9 @@ Include the code block in the `/etc/gitlab/gitlab.rb` file:
1. Save the configuration file.
1. Save the file and [reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) GitLab for the changes to take effect.
-Your sign-in page should now display a Cognito button below the regular sign-in form.
-To begin the authentication process, select the icon, and AWS Cognito asks the user to sign in and authorize the GitLab application.
-If successful, the user is redirected and signed in to your GitLab instance.
+Your sign-in page should now display a Cognito option below the regular sign-in form.
+Select this option to begin the authentication process.
+AWS Cognito then asks you to sign in and authorize the GitLab application.
+If the authorization is successful, you're redirected and signed in to your GitLab instance.
For more information, see [Configure initial settings](../../integration/omniauth.md#configure-initial-settings).