diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 000000000..6f69e5f3e --- /dev/null +++ b/.editorconfig @@ -0,0 +1,23 @@ +root = true + +[*] +insert_final_newline = true +end_of_line = lf +charset = utf-8 +trim_trailing_whitespace = true +indent_style = space +indent_size = 4 + +[{*.js,*.jsx,*.json,*.yml,*.yaml,*.md,.babelrc,.stylelintrc,*.proto}] +indent_size = 2 + +[*.md] +trim_trailing_whitespace = false + +[{*.sh, *.bash}] +indent_style = space +indent_size = 2 +switch_case_indent = true + +[**/node_modules/**] +ignore = true diff --git a/docs/admin/auth/index.mdx b/docs/admin/auth/index.mdx index 7bce17bf7..07529bfda 100644 --- a/docs/admin/auth/index.mdx +++ b/docs/admin/auth/index.mdx @@ -102,7 +102,6 @@ Leave the `url` field empty for GitHub.com. Once you've configured GitHub as a sign-on provider, you may also want to [add GitHub repositories to Sourcegraph](/admin/code_hosts/github#repository-syncing). - ### How to control user sign-up and sign-in with GitHub auth provider You can use the following filters to control how users will create accounts and sign in to your Sourcegraph instance via the GitHub auth provider. @@ -116,7 +115,6 @@ The new user email, during their account creation, should match one of their Git > WARNING: If `allowSignup` is set to `true`, anyone with internet access to both your Sourcegraph instance and your GitHub url are able to sign up and login to your instance. In particular, if url is set to `https://github.com`, this means that anyone with a Github account could log in to your Sourcegraph instance and search your indexed code. Make sure to also configure the `allowOrgs` field described below to limit sign-ups to your org, or limit public access to your Sourcegraph instance via IP restrictions / VPN. For assistance, contact support. - ```json { "type": "github", @@ -533,3 +531,11 @@ Usernames from authentication providers are normalized before being used in Sour For example, a user whose external username (according the authentication provider) is `alice_smith@example.com` would have the Sourcegraph username `alice-smith`. If multiple accounts normalize into the same username, separate accounts are still created, but Sourcegraph will add a randomized suffix to the username to ensure uniqueness. +<<<<<<< Updated upstream +======= + +## Remind users to connect external accounts + +When repository permissions are enabled, users must link their external code host accounts with their Sourcegraph accounts to access private repositories. +To ensure users are aware of any unlinked accounts, users will be prompted to connect any missing external accounts upon visiting Sourcegraph for the first time, or when the provider configuration changes. +>>>>>>> Stashed changes diff --git a/docs/admin/auth/saml/azure_ad.mdx b/docs/admin/auth/saml/azure_ad.mdx index 2223a68b9..587a1de52 100644 --- a/docs/admin/auth/saml/azure_ad.mdx +++ b/docs/admin/auth/saml/azure_ad.mdx @@ -4,15 +4,16 @@ 1. In Microsoft Entra ID, create an unlisted (non-gallery) application [following the official documentation](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/add-non-gallery-app). 1. Once the application is created, follow [these instructions to enable SAML SSO](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/configure-single-sign-on-non-gallery-applications). Use these configuration values (replacing "sourcegraph.example.com" with your Sourcegraph instance URL): - * **Identifier (Entity ID):** `https://sourcegraph.example.com/.auth/saml/metadata` - * **Reply URL (Assertion Consumer Service URL):** `https://sourcegraph.example.com/.auth/saml/acs` - * **Sign-on URL, Relay State, and Logout URL** can be left empty. - * **User Attributes & Claims:** Add the following attributes. - - `emailaddress`: user.mail (required) - - `name`: user.userprincipalname (optional) - - `login`: user.userprincipalname (optional) - * **Name ID**: `email` - * You can leave the other configuration values set to their defaults. + - **Identifier (Entity ID):** `https://sourcegraph.example.com/.auth/saml/metadata` + - **Reply URL (Assertion Consumer Service URL):** `https://sourcegraph.example.com/.auth/saml/acs` + - **Sign-on URL** `https://sourcegraph.example.com/.auth/saml/login?pc=azure` + - **Relay State, and Logout URL** can be left empty. + - **User Attributes & Claims:** Add the following attributes. + - `emailaddress`: user.mail + - `name`: user.userprincipalname + - `login`: user.userprincipalname + - `Unique user identifier`: `user.objectid` + - You can leave the other configuration values set to their defaults. 1. Record the value of the "App Federation Metadata Url". You'll need this in the next section. ## 2. Add the SAML auth provider to Sourcegraph site config @@ -27,10 +28,11 @@ { "type": "saml", "configID": "azure", - "identityProviderMetadataURL": "https://login.microsoftonline.com/7d2a00ed-73e8-4920-bbfa-ef68effe2d1e/federationmetadata/2007-06/federationmetadata.xml?appid=eff20ae4-145b-4bd3-ff3f-21edab43fe99" + "identityProviderMetadataURL": "https://login.microsoftonline.com/7d2a00ed-73e8-4920-bbfa-ef68effe2d1e/federationmetadata/2007-06/federationmetadata.xml?appid=eff20ae4-145b-4bd3-ff3f-21edab43fe99", + "allowSignup": true } ] } ``` -> NOTE: Optional, but recommended: [add automatic provisioning of users with SCIM](/admin/scim). +Optional, but recommended: [add automatic provisioning of users with SCIM](/admin/scim). diff --git a/docs/admin/auth/saml/okta.mdx b/docs/admin/auth/saml/okta.mdx index 8d48daf07..aa4d42320 100644 --- a/docs/admin/auth/saml/okta.mdx +++ b/docs/admin/auth/saml/okta.mdx @@ -11,12 +11,13 @@ - For “Single sign on URL”, set the value to ``/.auth/saml/acs - Under this box, there should be a checkbox labeled “Use this for Recipient URL and Destination URL”. Check the box if it is not already selected. - For “Audience URI (SP Entity ID)”, set the value to ``/.auth/saml/metadata - - For "Name ID format", choose "EmailAddress" + - For "Name ID format", choose "Persistent" + - For "Application username", choose "Custom" and insert `user.getInternalProperty("id")`. - In the section titled “Attribute Statements (optional)”: - Set the following Name and Values, leaving the Name format to “Unspecified” - - Email: user.email (This one is required) - - Login: user.login (This one is optional) - - displayName: user.firstName (This one is optional) + - `email`: `user.email` + - `login`: `user.login` + - `displayName`: `user.firstName` or an alternative field 6. Click Next. 7. Now you should be on the “Feedback” step. Select the radio button for “I’m an Okta customer adding an internal app”, and provide feedback if you wish. Click "Finish". 8. You should now be on the Application page for Sourcegraph, where you can view the settings and configurations you have just set. You will want to grant users or groups sign-in access before moving on. @@ -52,4 +53,4 @@ } ``` -> NOTE: Optional, but recommended: [add automatic provisioning of users with SCIM](/admin/scim). +Optional, but recommended: [add automatic provisioning of users with SCIM](/admin/scim). diff --git a/docs/admin/code_hosts/gitlab.mdx b/docs/admin/code_hosts/gitlab.mdx index 1d09a130d..ef48928d5 100644 --- a/docs/admin/code_hosts/gitlab.mdx +++ b/docs/admin/code_hosts/gitlab.mdx @@ -98,38 +98,6 @@ Then, [add or edit a GitLab connection](#repository-syncing) and include the `au In this case, a user's OAuth token will be used to get a list of repositories that the user can access. [Repository-centric permissions syncing](/admin/permissions/syncing) will be disabled. -### Administrator (sudo-level) access token - -This method requires administrator access to GitLab so that Sourcegraph can access the [admin GitLab Users API endpoint](https://docs.gitlab.com/ee/api/users.html#for-admins). For each GitLab user, this endpoint provides the user ID that comes from the authentication provider, so Sourcegraph can associate a user in its system to a user in GitLab. - -Prerequisite: Add the [SAML](/admin/auth/#saml) or [OpenID Connect](/admin/auth/#openid-connect) -authentication provider you use to sign into GitLab. - -Then, [add or edit a GitLab connection](#repository-syncing) using an administrator (sudo-level) personal access token, and include the `authorization` field: - -```json -{ - "url": "https://gitlab.com", - "token": "$PERSONAL_ACCESS_TOKEN", - // ... - "authorization": { - "identityProvider": { - "type": "external", - "authProviderID": "$AUTH_PROVIDER_ID", - "authProviderType": "$AUTH_PROVIDER_TYPE", - "gitlabProvider": "$AUTH_PROVIDER_GITLAB_ID" - } - } -} -``` - -`$AUTH_PROVIDER_ID` and `$AUTH_PROVIDER_TYPE` identify the authentication provider to use and should -match the fields specified in the authentication provider config -(`auth.providers`). The authProviderID can be found in the `configID` field of the auth provider config. - -`$AUTH_PROVIDER_GITLAB_ID` should match the `identities.provider` returned by -[the admin GitLab Users API endpoint](https://docs.gitlab.com/ee/api/users.html#for-admins). - ### Username Prerequisite: Ensure that `http-header` is the *only* authentication provider type configured for @@ -296,7 +264,7 @@ See [Internal rate limits](/admin/code_hosts/rate_limits#internal-rate-limits). // It is important that the Sourcegraph repository name generated with this pattern be unique to this code host. If different code hosts generate repository names that collide, Sourcegraph's behavior is undefined. "repositoryPathPattern": "{host}/{pathWithNamespace}", - // A GitLab access token with "api" scope. Can be a personal access token (PAT) or an OAuth token. If you are enabling permissions with identity provider type "external", this token should also have "sudo" scope. + // A GitLab access token with "api" scope. Can be a personal access token (PAT) or an OAuth token. If you are enabling permissions with identity provider type "username", this token should also have "sudo" scope. "token": null, // The OAuth token expiry (Unix timestamp in seconds) diff --git a/docs/admin/config/authorization_and_authentication.mdx b/docs/admin/config/authorization_and_authentication.mdx index 3f4597593..774bef5a6 100644 --- a/docs/admin/config/authorization_and_authentication.mdx +++ b/docs/admin/config/authorization_and_authentication.mdx @@ -68,48 +68,13 @@ Once authentication with GitHub via OAuth is configured, follow [these steps to ### GitLab Enterprise or GitLab Cloud authentication and authorization -We support both authentication and permissions syncing (through OAuth) for GitLab. If you use GitLab as your code host, you have two available authentication flows: - -#### Option 1 +We support both authentication and permissions syncing (through OAuth) for GitLab. 1. Use SAML (or another auth mechanism) to log in to GitLab 2. Use GitLab OAuth to log in to Sourcegraph In this way, access to Sourcegraph will still be managed by your identity provider, using the code host as a middle step. This option is the simplest to configure. To do so, [set up GitLab as an authentication option](/admin/auth/#gitlab), and then [enable permissions syncing](/admin/code_hosts/gitlab#oauth-application). -#### Option 2 - -Alternatively, you can configure SAML authentication in Sourcegraph, and use GitLab permissions syncing in the background to control access permissions. To implement this method, you will need to make sure that GitLab is able to return a value in `identities.provider` for the `GET /users` endpoint ([GitLab documentation](https://docs.gitlab.com/ee/api/users.html#for-admins)) that your identity provider is able to pass as the `nameID` in the SAML response. If that isn’t possible, you will need to use the first option. - -To configure SAML auth with GitLab permissions, you will need to first [configure permissions from GitLab](/admin/code_hosts/gitlab#administrator-sudo-level-access-token). Then, [configure SAML authentication](/admin/auth/saml/). The `nameID` passed by the identity provider will need to match the value of `identities.provider`. - -For example, if the GitLab API returns: - -```json -{ - "identities": [{ "provider": "saml", "extern_uid": "email@domain.com" }] -} -``` - -Then you will need to configure permission in Sourcegraph as: - -```json -{ - "url": "https://gitlab.com", - "token": "$PERSONAL_ACCESS_TOKEN", - "authorization": { - "identityProvider": { - "type": "external", - "authProviderID": "$AUTH_PROVIDER_ID", - "authProviderType": "$AUTH_PROVIDER_TYPE", - "gitlabProvider": "saml" - } - } -} -``` - -And configure the identity provider to pass the email address as the `nameID`. - ### Bitbucket Server / Bitbucket Data Center authorization We do not currently support OAuth for Bitbucket Server or Bitbucket Data Center. You will need to combine permissions syncing from Bitbucket Server / Bitbucket Data Center with another authentication mechanism (SAML, built-in auth, HTTP authentication proxies). Bitbucket Server and Bitbucket Data Center only pass usernames to Sourcegraph, so you’ll need to make sure that those usernames are matched by whatever mechanism you choose to use for access. diff --git a/docs/admin/config/email.mdx b/docs/admin/config/email.mdx index 9593b4df4..bed581911 100644 --- a/docs/admin/config/email.mdx +++ b/docs/admin/config/email.mdx @@ -7,7 +7,7 @@ Sourcegraph uses an SMTP server of your choosing to send emails for: - Important updates to a user accounts (for example, creation of API keys) - For [`builtin` authentication](/admin/auth/#builtin-password-authentication), password resets and email verification -> NOTE: Sourcegraph Cloud customers can take advantage of mananged SMTP servers - [learn more](/cloud/#managed-smtp). +Sourcegraph Cloud customers can take advantage of mananged SMTP servers - [learn more](/cloud/#managed-smtp). ## User email verification @@ -82,8 +82,8 @@ Make sure that `test@example.com` in both places of the configuration matches th Other providers such as Mailchimp and Sendgrid may also be used with Sourcegraph. Any valid SMTP server account should do. For those two providers in specific, you may follow their documentation: -* https://mailchimp.com/developer/transactional/docs/smtp-integration/ -* https://docs.sendgrid.com/for-developers/sending-email/getting-started-smtp +- [https://mailchimp.com/developer/transactional/docs/smtp-integration/](https://mailchimp.com/developer/transactional/docs/smtp-integration/) +- [https://docs.sendgrid.com/for-developers/sending-email/getting-started-smtp](https://docs.sendgrid.com/for-developers/sending-email/getting-started-smtp) Once you have an SMTP account, simply navigate to your site configuration (e.g. `https://sourcegraph.com/site-admin/configuration`) and fill in the configuration: diff --git a/docs/admin/config/webhooks/outgoing.mdx b/docs/admin/config/webhooks/outgoing.mdx index 71bb15842..bea32eb5e 100644 --- a/docs/admin/config/webhooks/outgoing.mdx +++ b/docs/admin/config/webhooks/outgoing.mdx @@ -1,6 +1,10 @@ # Outgoing webhooks +<<<<<<< Updated upstream This feature is supported on Sourcegraph versions 5.0 or more. +======= + This feature is currently in beta and supported on Sourcegraph versions 5.0 or later. +>>>>>>> Stashed changes Outgoing webhooks can be configured on a Sourcegraph instance in order to send Sourcegraph events to external tools and services. This allows for deeper integrations between Sourcegraph and other applications. diff --git a/docs/admin/permissions/index.mdx b/docs/admin/permissions/index.mdx index 5fcecf8aa..2a0e5e27e 100644 --- a/docs/admin/permissions/index.mdx +++ b/docs/admin/permissions/index.mdx @@ -124,6 +124,7 @@ of `alice` are the following union set: [`horsegraph/global`, `horsegraph/hay-v1 ### Configuration **Prerequisites:** + 1. Sourcegraph version 5.0+ 1. Go to **Site Admin > Migrations** page. There is a migration called `Migrate data from user_permissions table to unified user_repo_permissions.`. Make sure that it finished migrating all the data (it reports as 100%). Contact support if the migration does not seem to complete for a long time (multiple days). @@ -150,8 +151,8 @@ permission sync, it will replace the existing set of synced permissions for that **Example**: -Let's follow the example from above, `alice` has existing synced permissions to repositories `horsegraph/global` and `horsegraph/hay-v1` -and explicit permissions to `horsegraph/hay-dev`, meaning a unioned set of effective permissions of [`horsegraph/global`, `horsegraph-hay-v1`, `horsegraph/hay-dev`]. +Let's follow the example from above. `alice` has existing synced permissions for the repositories `horsegraph/global` and `horsegraph/hay-v1` +and explicit permissions set for `horsegraph/hay-dev`, meaning a unioned set of effective permissions of [`horsegraph/global`, `horsegraph/hay-v1`, `horsegraph/hay-dev`]. An update comes in from permission sync, now returning `alice` permissions as [`horsegraph/global`, `horsegraph/hay-v2`]. Notice the removal of `horsegraph-v1` from the set. diff --git a/docs/admin/permissions/syncing.mdx b/docs/admin/permissions/syncing.mdx index 575f35f4e..a4e077bc3 100644 --- a/docs/admin/permissions/syncing.mdx +++ b/docs/admin/permissions/syncing.mdx @@ -10,6 +10,7 @@ permissions. Both are on by default, resulting in double polling: Sourcegraph collects this information and stores it in internal database. To see which code hosts support permission syncing, please refer to [Supported code hosts table](/admin/#supported-code-hosts). + ## How it works ### Periodic sync @@ -27,6 +28,7 @@ Besides periodic schedule of jobs, we also have a way to request permission sync or repository on-demand. This is useful for example when a new user is added to Sourcegraph. To do that, the following GraphQL request needs to be made: + ```graphql mutation { scheduleUserPermissionsSync(user: "user") { @@ -36,6 +38,7 @@ mutation { ``` Or in the case of adding a repository, the following request is made: + ```graphql mutation { scheduleRepositoryPermissionsSync(repository: "repository") { @@ -45,6 +48,7 @@ mutation { ``` **Example**: + - User `bob` is added to Sourcegraph. - `bob` has access to repositories `horsegraph/global` and `horsegraph/bob` on the code host - an on-demand request is made to sync repository permissions of `bob`, this job is added to the queue with high priority, so it will be processed @@ -69,6 +73,7 @@ processed. To avoid overloading the code host a sync job [might not be processed and depending on the code host, might be heavily rate limited. Priority queue is needed to process the sync jobs in the order of most important first. E.g.: + - on-demand sync is high priority - sync of entities with no permissions is high priority - sync of oldest permissions is normal priority, since we already do have some permissions in the system @@ -230,13 +235,14 @@ mentioned above. Even if we let permission sync consume all the rate limit and w is rarely the case. Depending on the code host, the rate limit might be much higher, but then we might be firing huge amounts of requests to the code host. -> IMPORTANT: For permission syncing to be quicker, the code host needs to be able to handle big amounts of requests per hour. +IMPORTANT: For permission syncing to be quicker, the code host needs to be able to handle big amounts of requests per hour. -> IMPORTANT: Depending on the customer scale, the amount of users, repositories and the distribution of permissions accross them, the time it takes to fully sync will vary. +IMPORTANT: Depending on the customer scale, the amount of users, repositories and the distribution of permissions accross them, the time it takes to fully sync will vary. -> IMPORTANT: We recommend **configuring webhooks for permissions on GitHub** which makes lag time much smaller. +IMPORTANT: We recommend **configuring webhooks for permissions on GitHub** which makes lag time much smaller. ## Configuration + There are variety of options in the site configuration to tune how the permissions sync requests are scheduled. Default values are shown below: @@ -268,7 +274,9 @@ Internal rate limiter settings are described on each code host configuration pag ### Recommendations #### Less users than repositories + If there are a lot less users, than repositories, it is better to rely on user-centric perms sync instead of repo-centric sync. In that case, we recommend: + ```json { // ... @@ -288,6 +296,7 @@ a minute. `5000/(4 * 60) = 20.8`, so the scheduler needs to schedule 21 users on The rate limit for the code host would need to be changed to support the load. In that case the recommendation is to set it to 2x of the amount of [requests expected from permission syncing](#request-count). + #### More users than repositories If the situation is reversed, it is recommended to do the opposite than above. Prefer repo-centric diff --git a/docs/admin/permissions/webhooks.mdx b/docs/admin/permissions/webhooks.mdx index f0e9f3d99..b23d68f8d 100644 --- a/docs/admin/permissions/webhooks.mdx +++ b/docs/admin/permissions/webhooks.mdx @@ -4,7 +4,11 @@ Sourcegraph allows customers to use webhooks to react to events that modify user on the code host. Currently the only supported code host for webhooks is [Github](/admin/code_hosts/github). +<<<<<<< Updated upstream > NOTE: Using webhooks is the *recommended* way to get code host permissions to Sourcegraph. It's important to also note that when you have webhooks configured, it override Sourcegraph's default heuristics for fetching repository permissions. This is because webhooks and explicit configurations are intended to enforce specific permissions from external services, while the default heuristics act as a fallback when no explicit permissions are provided. +======= +> NOTE: Using webhooks is the *recommended* way to get code host permissions to Sourcegraph. +>>>>>>> Stashed changes ## How it works @@ -23,6 +27,7 @@ when the permissions are changed on the code host, it takes at most 5 minutes fo - the eventual consistency time is really low, see [SLA](#sla) above. - least amount of resource usage (bandwidth, code host rate limit), as we only ask code host for permission data when there is an actual change + ## Disadvantages Webhooks are best effort and there is no 100% guarantee that a webhook will be diff --git a/docs/admin/repo/update_frequency.mdx b/docs/admin/repo/update_frequency.mdx index 74bbca485..3d660cd08 100644 --- a/docs/admin/repo/update_frequency.mdx +++ b/docs/admin/repo/update_frequency.mdx @@ -1,6 +1,11 @@ # Repository update frequency -By default, Sourcegraph polls code hosts to keep repository contents up to date, effectively running `git pull` periodically. You can also configure Sourcegraph to use [repository webhooks](/admin/repo/webhooks), but this is usually not necessary. +Repositories in Sourcegraph are updated automatically by default. There are two processes making sure all the code that has been configured in code host connections is available: + +1. The code host connection syncing. This process takes the configuration of the code host connection and talks to the code host to determine the final set of repositories that should be on the instance. This process will discover newly added repositories, and remove repositories that have been removed from the code host. +2. The git repository syncing. This process takes the set of repositories that were determined by the above process and ensures that they are all cloned into Sourcegraph and up-to-date with the code host. + +You can also configure Sourcegraph to use [repository webhooks](/admin/repo/webhooks), if you want Sourcegraph to detect changes faster. The frequency at which Sourcegraph polls the code host for updates is determined by a smart heuristic based on past commit frequency in the repository. For example, if a repository's last commit was 8 hours ago, then the next sync will be scheduled 4 hours from now. If after 4 hours, there are still no new commits, then the next sync will be scheduled 6 hours from then. @@ -9,6 +14,7 @@ Repositories will never be updated more frequently than 45 seconds, and no less After Sourcegraph has updated a repository's Git data, the global search index will automatically update a short while after (usually a few minutes). ## Rate Limiting + If you wish to control how frequently repositories are discovered or how frequently Sourcegraph polls your code host for updates, the following options are available: ### Limiting the number of Code host API requests diff --git a/docs/admin/repo/webhooks.mdx b/docs/admin/repo/webhooks.mdx index 957b9bcdb..bb6eaa5f8 100644 --- a/docs/admin/repo/webhooks.mdx +++ b/docs/admin/repo/webhooks.mdx @@ -1,3 +1,5 @@ +TODO OVERHAUL THIS PAGE + # Repository webhooks ## Webhook for manually telling Sourcegraph to update a repository diff --git a/docs/admin/scim.mdx b/docs/admin/scim.mdx index 86f8ea20a..657c9b350 100644 --- a/docs/admin/scim.mdx +++ b/docs/admin/scim.mdx @@ -1,66 +1,54 @@ # SCIM -This feature is in beta while we're testing it with more IdPs. Our implementation complies with the SCIM 2.0 specification, and passes the validator for Okta and Microsoft Entra ID. But implementations might differ on the side of IdPs and validators don't give a 100% coverage, so we can't guarantee that our solution works with all IdPs in every case. +This feature is in beta while we're testing it with more IdPs. Reach out if you're running into trouble. -SCIM (System for Cross-domain Identity Management) is a standard for provisioning and deprovisioning users and groups in an organization. IdPs (identity providers) like Okta, OneLogin, and Microsoft Entra ID support provisioning users through SCIM. +SCIM (System for Cross-domain Identity Management) is a standard for provisioning and deprovisioning users and groups in an organization. Identity providers like Okta, OneLogin, and Microsoft Entra ID support provisioning users through SCIM. -Sourcegraph supports SCIM 2.0 for provisioning and de-provisioning _users_. +Sourcegraph supports SCIM 2.0 for provisioning and de-provisioning users, groups are currently not supported. +<<<<<<< Updated upstream > SCIM integration requires your SCIM provider to have network connectivity to your Sourcegraph instance. For example, using Okta's SCIM service with a private Sourcegraph instance, you will need to implement an [Okta privisioning agent](https://help.okta.com/en-us/content/topics/provisioning/opp/opp-main.htm) within a network that can connect to both your Sourcegraph instance and Okta's cloud services before continuing this setup. > While our implementation of SCIM 2.0 is compliant with the specification, we’ve only tested it against two IdPs: Okta and Microsoft Entra ID. We can't guarantee it works with every IdP if the provider doesn't fully comply with the specification. > Currently, there is a known issue where Microsoft Entra ID [validator](https://scimvalidator.microsoft.com/) will fail; however, this does not impact the ability to provision users. +======= +While our implementation of SCIM 2.0 is compliant with the specification, we’ve only tested it against two IdPs: Okta and Microsoft Entra ID. We can't guarantee it works with every IdP if the provider doesn't fully comply with the specification. +>>>>>>> Stashed changes -## How to use +## How to configure SCIM -To use SCIM, you must have an existing IdP configured as an auth provider on your Sourcegraph instance. For authenticating SCIM requests, we currently support Bearer token authentication. We have a guide for Okta setup [below](#setting-up-okta-as-the-idp). +To use SCIM, you must have an existing IdP configured as an auth provider on your Sourcegraph instance. For authenticating SCIM requests, we currently support Bearer token authentication. -To configure: -1. Generate a random alphanumeric bearer token of maximum 255 characters. +To configure SCIM, follow these steps: + +1. Generate a random alphanumeric bearer token for the SCIM client to use when talking to Sourcegraph of maximum 255 characters. To do this in a terminal, run: - ``` + ```bash openssl rand -base64 342 | tr -dc 'a-zA-Z0-9' | cut -c -255 ``` - (This command generates a random base64 string with more characters than required (342 characters) and then filters out non-alphanumeric characters. Finally, it trims the output to 255 characters. The reason we generate a longer string is to account for the fact that the base64 encoding has non-alphanumeric characters, which are removed by the tr command.) - 2. Add the following line to your [site configuration](/admin/config/site_config): - ``` + ```json "scim.authToken": "{your token}" ``` + 3. If you use Microsoft Entra ID, add the following setting to your site config: - ``` + ```json "scim.identityProvider": "Azure AD" ``` -4. Set up your IdP to use our SCIM API. The API is at - ``` +4. Set up your IdP to use our SCIM API. The API endpoint is at + + ```txt https://sourcegraph.company.com/.api/scim/v2 ``` -## Configuring SCIM for Okta - -To set up user provisioning in [Okta](https://help.okta.com/en-us/Content/Topics/Apps/Apps_App_Integration_Wizard_SCIM.htm), you must first set up a new app integration of the "SAML 2.0" type, then configure it to use SCIM. Here are the steps to do this: - -1. Follow our [SAML guide](/admin/auth/saml/okta) to set up a new app integration with SAML, then open the integration you just created. - - If you already have the integration, just open your existing app integration. -1. Go to the "General" tab and click "Edit" in the "App Settings" section. -1. Set "Provisioning" to "SCIM". This creates a new tab called "Provisioning". -1. Go to the "Provisioning" tab, and click "Edit" -1. Set "SCIM connector base URL" to `{yourSourcegraphUrl}/.api/scim/v2` -1. Set "Unique identifier field for users" to `userName` -1. Check the first three items in `Supported provisioning actions`: "Import New Users and Profile Updates", "Push New Users", and "Push Profile Updates". -1. Set "Authentication mode" to "HTTP Header" -1. Under "HTTP Header", paste the same alphanumeric bearer token you used in your site config. -1. Click "Test Connection Configuration" (first four items should be green—the user-related ones), then "Save". -1. Switch to "Provisioning" → "To App" and click "Edit". Enable "Create Users", "Update User Attributes" and "Deactivate Users". - -> NOTE: You can also use our [SAML](/admin/auth/saml/okta) and [OpenID Connect](/admin/auth#openid-connect) integrations with Okta. +See further down for [Okta specific setup](#setting-up-okta-as-the-idp). ## Features and limitations @@ -100,3 +88,22 @@ We support the following SCIM 2.0 features: - ❌ Entity tags (ETags) - ❌ Multi-tenancy – you can only have 1 SCIM client configured at a time. - ❌ Tests with many IdPs – we’ve only validated the endpoint with Okta and Microsoft Entra ID. + +## Configuring SCIM for Okta + +To set up user provisioning in [Okta](https://help.okta.com/en-us/Content/Topics/Apps/Apps_App_Integration_Wizard_SCIM.htm), you must first set up a new app integration of the "SAML 2.0" type. Only SAML 2.0 supports SCIM provisioning in Okta today. Here are the steps to do this: + +1. Follow our [SAML guide](/admin/auth/saml/okta) to set up an app integration with SAML, then open the integration you just created in Okta. + - If you already have the integration, just open your existing app integration. +1. Go to the "General" tab and click "Edit" in the "App Settings" section. +1. Set "Provisioning" to "SCIM". This creates a new tab called "Provisioning". +1. Go to the "Provisioning" tab, and click "Edit" +1. Set "SCIM connector base URL" to `{yourSourcegraphUrl}/.api/scim/v2` +1. Set "Unique identifier field for users" to `userName` +1. Check the first three items in `Supported provisioning actions`: "Push New Users", and "Push Profile Updates". +1. Set "Authentication mode" to "HTTP Header" +1. Under "HTTP Header", paste the same alphanumeric bearer token you used in your site config. +1. Click "Test Connection Configuration" ("Create Users", and "Update User Attributes" should be green), then "Save". +1. Switch to "Provisioning" → "To App" and click "Edit". Enable "Create Users", "Update User Attributes" and "Deactivate Users", and "Save" again. + +> NOTE: You can also use our [SAML](/admin/auth/saml/okta) and [OpenID Connect](/admin/auth#openid-connect) integrations with Okta. diff --git a/docs/integration/phabricator.mdx b/docs/integration/phabricator.mdx index c2af8b6af..af3aba444 100644 --- a/docs/integration/phabricator.mdx +++ b/docs/integration/phabricator.mdx @@ -1,8 +1,8 @@ # Phabricator integration with Sourcegraph -> ⚠️ NOTE: Sourcegraph support of Phabricator is limited, and not expected to evolve due to the [announced](https://admin.phacility.com/phame/post/view/11/phacility_is_winding_down_operations/) cease of support for Phabricator. +Sourcegraph support of Phabricator is limited, and not expected to evolve due to the [announced](https://admin.phacility.com/phame/post/view/11/phacility_is_winding_down_operations/) cease of support for Phabricator. -This Phabricator integration does not support listing and mirroring Phabricator repositories (as it does for repositories on other code hosts). It is intended for use when your repositories are hosted somewhere else (such as GitHub), and Phabricator mirrors repositories from that code host. If your repositories are hosted on Phabricator, you must follow the steps in "[Other Git repository hosts](/admin/code_hosts/other)" to add the repositories so that they are mirrored to Sourcegraph in addition to the steps outlined here to power the integration. Sourcegraph does not currently support using the repository permissions you've set in Phabricator for repositories hosted on Phabricator. +This Phabricator integration does not support listing and mirroring Phabricator repositories (as it does for repositories on other code hosts). It is intended for use when your repositories are hosted somewhere else (such as GitHub), and Phabricator mirrors repositories from that code host. If your repositories are hosted on Phabricator, you must follow the steps in "[Other Git repository hosts](/admin/external_service/other)" to add the repositories so that they are mirrored to Sourcegraph in addition to the steps outlined here to power the integration. Sourcegraph does not support mirroring the repository permissions you've set in Phabricator for repositories hosted on Phabricator. Feature | Supported? ------- | ----------