100 lines
4.6 KiB
Markdown
100 lines
4.6 KiB
Markdown
---
|
|
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/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 OAuth 2.0 provider.
|
|
|
|
## Configure AWS Cognito
|
|
|
|
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. From the **Services** menu, select **Cognito**.
|
|
1. Select **Manage User Pools** and then in the upper-right corner, select **Create a user pool**.
|
|
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. 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. 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://<your_gitlab_instance_url>/users/auth/cognito/callback`
|
|
- **Allowed OAuth Flows** - Authorization code grant
|
|
- **Allowed OAuth 2.0 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. 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
|
|
|
|
1. Edit the [common configuration file settings](../../integration/omniauth.md#configure-common-settings)
|
|
to add `cognito` as a single sign-on provider. This enables Just-In-Time
|
|
account provisioning for users who do not have an existing GitLab account.
|
|
1. On your GitLab server, open the configuration file.
|
|
|
|
**For Omnibus installations**
|
|
|
|
```shell
|
|
sudo editor /etc/gitlab/gitlab.rb
|
|
```
|
|
|
|
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']
|
|
gitlab_rails['omniauth_providers'] = [
|
|
{
|
|
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>",
|
|
args: {
|
|
scope: "openid profile email",
|
|
client_options: {
|
|
site: "https://<your_domain>.auth.<your_region>.amazoncognito.com",
|
|
authorize_url: "/oauth2/authorize",
|
|
token_url: "/oauth2/token",
|
|
user_info_url: "/oauth2/userInfo"
|
|
},
|
|
user_response_structure: {
|
|
root_path: [],
|
|
id_path: ["sub"],
|
|
attributes: { nickname: "email", name: "email", email: "email" }
|
|
},
|
|
name: "cognito",
|
|
strategy_class: "OmniAuth::Strategies::OAuth2Generic"
|
|
}
|
|
}
|
|
]
|
|
```
|
|
|
|
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 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 common settings](../../integration/omniauth.md#configure-common-settings).
|