Octomerger Bot
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
@@ -50,9 +50,7 @@ You can configure a {% data variables.product.prodname_actions %} _workflow_ to
|
||||
|
||||
### Workflows
|
||||
|
||||
A workflow is a configurable automated process that will run one or more jobs. Workflows are defined by a YAML file checked in to your repository and will run when triggered by an event in your repository, or they can be triggered manually, or at a defined schedule.
|
||||
|
||||
You can have multiple workflows in a repository, each of which can perform a different set of steps. For example, you can have one workflow to build and test pull requests, another workflow to deploy your application every time a release is created, and still another workflow that adds a label every time someone opens a new issue.
|
||||
{% data reusables.actions.about-workflows-long %}
|
||||
|
||||
{% ifversion fpt or ghes > 3.3 or ghae-issue-4757 or ghec %}You can reference a workflow within another workflow, see "[Reusing workflows](/actions/learn-github-actions/reusing-workflows)."{% endif %}
|
||||
|
||||
@@ -86,173 +84,7 @@ For more information, see "[Creating actions](/actions/creating-actions)."
|
||||
|
||||
{% data reusables.actions.about-runners %} Each runner can run a single job at a time. {% ifversion ghes or ghae %} You must host your own runners for {% data variables.product.product_name %}. {% elsif fpt or ghec %}{% data variables.product.company_short %} provides Ubuntu Linux, Microsoft Windows, and macOS runners to run your workflows; each workflow run executes in a fresh, newly-provisioned virtual machine. If you need a different operating system or require a specific hardware configuration, you can host your own runners.{% endif %} For more information{% ifversion fpt or ghec %} about self-hosted runners{% endif %}, see "[Hosting your own runners](/actions/hosting-your-own-runners)."
|
||||
|
||||
## Create an example workflow
|
||||
|
||||
{% data variables.product.prodname_actions %} uses YAML syntax to define the workflow. Each workflow is stored as a separate YAML file in your code repository, in a directory called `.github/workflows`.
|
||||
|
||||
You can create an example workflow in your repository that automatically triggers a series of commands whenever code is pushed. In this workflow, {% data variables.product.prodname_actions %} checks out the pushed code, installs the software dependencies, and runs `bats -v`.
|
||||
|
||||
1. In your repository, create the `.github/workflows/` directory to store your workflow files.
|
||||
1. In the `.github/workflows/` directory, create a new file called `learn-github-actions.yml` and add the following code.
|
||||
|
||||
```yaml
|
||||
name: learn-github-actions
|
||||
on: [push]
|
||||
jobs:
|
||||
check-bats-version:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: {% data reusables.actions.action-checkout %}
|
||||
- uses: {% data reusables.actions.action-setup-node %}
|
||||
with:
|
||||
node-version: '14'
|
||||
- run: npm install -g bats
|
||||
- run: bats -v
|
||||
```
|
||||
1. Commit these changes and push them to your {% data variables.product.prodname_dotcom %} repository.
|
||||
|
||||
Your new {% data variables.product.prodname_actions %} workflow file is now installed in your repository and will run automatically each time someone pushes a change to the repository. For details about a workflow's execution history, see "[Viewing the workflow's activity](/actions/learn-github-actions/introduction-to-github-actions#viewing-the-workflows-activity)."
|
||||
|
||||
## Understanding the workflow file
|
||||
|
||||
To help you understand how YAML syntax is used to create a workflow file, this section explains each line of the introduction's example:
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
```yaml
|
||||
name: learn-github-actions
|
||||
```
|
||||
</td>
|
||||
<td>
|
||||
<em>Optional</em> - The name of the workflow as it will appear in the Actions tab of the {% data variables.product.prodname_dotcom %} repository.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
```yaml
|
||||
on: [push]
|
||||
```
|
||||
</td>
|
||||
<td>
|
||||
Specifies the trigger for this workflow. This example uses the <code>push</code> event, so a workflow run is triggered every time someone pushes a change to the repository or merges a pull request. This is triggered by a push to every branch; for examples of syntax that runs only on pushes to specific branches, paths, or tags, see <a href="https://docs.github.com/actions/reference/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore">"Workflow syntax for {% data variables.product.prodname_actions %}."</a>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
```yaml
|
||||
jobs:
|
||||
```
|
||||
</td>
|
||||
<td>
|
||||
Groups together all the jobs that run in the <code>learn-github-actions</code> workflow.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
```yaml
|
||||
check-bats-version:
|
||||
```
|
||||
</td>
|
||||
<td>
|
||||
Defines a job named <code>check-bats-version</code>. The child keys will define properties of the job.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
```yaml
|
||||
runs-on: ubuntu-latest
|
||||
```
|
||||
</td>
|
||||
<td>
|
||||
Configures the job to run on the latest version of an Ubuntu Linux runner. This means that the job will execute on a fresh virtual machine hosted by GitHub. For syntax examples using other runners, see <a href="https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idruns-on">"Workflow syntax for {% data variables.product.prodname_actions %}."</a>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
```
|
||||
</td>
|
||||
<td>
|
||||
Groups together all the steps that run in the <code>check-bats-version</code> job. Each item nested under this section is a separate action or shell script.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
```yaml
|
||||
- uses: {% data reusables.actions.action-checkout %}
|
||||
```
|
||||
</td>
|
||||
<td>
|
||||
The <code>uses</code> keyword specifies that this step will run <code>v3</code> of the <code>actions/checkout</code> action. This is an action that checks out your repository onto the runner, allowing you to run scripts or other actions against your code (such as build and test tools). You should use the checkout action any time your workflow will run against the repository's code.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
```yaml
|
||||
- uses: {% data reusables.actions.action-setup-node %}
|
||||
with:
|
||||
node-version: '14'
|
||||
```
|
||||
</td>
|
||||
<td>
|
||||
This step uses the <code>{% data reusables.actions.action-setup-node %}</code> action to install the specified version of the Node.js (this example uses v14). This puts both the <code>node</code> and <code>npm</code> commands in your <code>PATH</code>.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
```yaml
|
||||
- run: npm install -g bats
|
||||
```
|
||||
</td>
|
||||
<td>
|
||||
The <code>run</code> keyword tells the job to execute a command on the runner. In this case, you are using <code>npm</code> to install the <code>bats</code> software testing package.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
```yaml
|
||||
- run: bats -v
|
||||
```
|
||||
</td>
|
||||
<td>
|
||||
Finally, you'll run the <code>bats</code> command with a parameter that outputs the software version.
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
### Visualizing the workflow file
|
||||
|
||||
In this diagram, you can see the workflow file you just created and how the {% data variables.product.prodname_actions %} components are organized in a hierarchy. Each step executes a single action or shell script. Steps 1 and 2 run actions, while steps 3 and 4 run shell scripts. To find more prebuilt actions for your workflows, see "[Finding and customizing actions](/actions/learn-github-actions/finding-and-customizing-actions)."
|
||||
|
||||
|
||||
|
||||
## Viewing the workflow's activity
|
||||
|
||||
Once your workflow has started running, you can see a visualization graph of the run's progress and view each step's activity on {% data variables.product.prodname_dotcom %}.
|
||||
|
||||
{% data reusables.repositories.navigate-to-repo %}
|
||||
1. Under your repository name, click **Actions**.
|
||||
|
||||
1. In the left sidebar, click the workflow you want to see.
|
||||
|
||||
1. Under "Workflow runs", click the name of the run you want to see.
|
||||
|
||||
1. Under **Jobs** or in the visualization graph, click the job you want to see.
|
||||
|
||||
1. View the results of each step.
|
||||
|
||||
{% data reusables.actions.workflow-basic-example-and-explanation %}
|
||||
|
||||
## Next steps
|
||||
|
||||
@@ -268,7 +100,8 @@ To understand how billing works for {% data variables.product.prodname_actions %
|
||||
|
||||
{% data reusables.actions.contacting-support %}
|
||||
|
||||
{% ifversion ghec or ghes or ghae %}
|
||||
## Further reading
|
||||
|
||||
{% ifversion ghec or ghes or ghae %}
|
||||
- "[About {% data variables.product.prodname_actions %} for enterprises](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/about-github-actions-for-enterprises)"{% endif %}
|
||||
- "[About {% data variables.product.prodname_actions %} for enterprises](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/about-github-actions-for-enterprises)"
|
||||
{% endif %}
|
||||
|
||||
@@ -1,32 +1,67 @@
|
||||
---
|
||||
title: Advanced workflow features
|
||||
shortTitle: Advanced workflow features
|
||||
intro: 'This guide shows you how to use the advanced features of {% data variables.product.prodname_actions %}, with secret management, dependent jobs, caching, build matrices, environments, and labels.'
|
||||
redirect_from:
|
||||
- /actions/learn-github-actions/managing-complex-workflows
|
||||
title: About workflows
|
||||
shortTitle: About workflows
|
||||
intro: 'Get a high level overview {% data variables.product.prodname_actions %} workflows, including triggers, syntax, and advanced features.'
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghes: '*'
|
||||
ghae: '*'
|
||||
ghec: '*'
|
||||
type: how_to
|
||||
type: overview
|
||||
redirect_from:
|
||||
- /actions/learn-github-actions/managing-complex-workflows
|
||||
- /actions/using-workflows/advanced-workflow-features
|
||||
topics:
|
||||
- Workflows
|
||||
miniTocMaxHeadingLevel: 4
|
||||
miniTocMaxHeadingLevel: 3
|
||||
---
|
||||
|
||||
{% data reusables.actions.enterprise-beta %}
|
||||
{% data reusables.actions.enterprise-github-hosted-runners %}
|
||||
## About workflows
|
||||
|
||||
## Overview
|
||||
{% data reusables.actions.about-workflows-long %}
|
||||
|
||||
This article describes some of the advanced features of {% data variables.product.prodname_actions %} that help you create more complex workflows.
|
||||
## Workflow basics
|
||||
|
||||
## Storing secrets
|
||||
A workflow must contain the following basic components:
|
||||
|
||||
If your workflows use sensitive data, such as passwords or certificates, you can save these in {% data variables.product.prodname_dotcom %} as _secrets_ and then use them in your workflows as environment variables. This means that you will be able to create and share workflows without having to embed sensitive values directly in the YAML workflow.
|
||||
1. One or more _events_ that will trigger the workflow.
|
||||
1. One or more _jobs_, each of which will execute on a _runner_ machine and run a series of one or more _steps_.
|
||||
1. Each step can either run a script that you define or run an action, which is a reusable extension that can simplify your workflow.
|
||||
|
||||
This example action demonstrates how to reference an existing secret as an environment variable, and send it as a parameter to an example command.
|
||||
For more information these basic components, see "[Understanding GitHub Actions](/actions/learn-github-actions/understanding-github-actions#the-components-of-github-actions)."
|
||||
|
||||
|
||||
|
||||
## Triggering a workflow
|
||||
|
||||
{% data reusables.actions.about-triggers %}
|
||||
|
||||
For more information, see "[Triggering a workflow](/actions/using-workflows/triggering-a-workflow)", and for a full list of events, see "[Events that trigger workflows](/actions/using-workflows/events-that-trigger-workflows)."
|
||||
|
||||
## Workflow syntax
|
||||
|
||||
Workflow are defined using YAML. For the full reference of the YAML syntax for authoring workflows, see "[Workflow syntax for GitHub Actions](/actions/using-workflows/workflow-syntax-for-github-actions#about-yaml-syntax-for-workflows)."
|
||||
|
||||
|
||||
{% data reusables.actions.workflow-basic-example-and-explanation %}
|
||||
|
||||
For more on managing workflow runs, such as re-running, cancelling, or deleting a workflow run, see "[Managing workflow runs](/actions/managing-workflow-runs)."
|
||||
|
||||
## Using starter workflows
|
||||
|
||||
{% data reusables.actions.workflow-template-overview %}
|
||||
|
||||
For more information on using and creating starter workflows, see "[Using starter workflows](/actions/using-workflows/using-starter-workflows)" and "[Creating starter workflows for your organization](/actions/using-workflows/creating-starter-workflows-for-your-organization)."
|
||||
|
||||
## Advanced workflow features
|
||||
|
||||
This section briefly describes some of the advanced features of {% data variables.product.prodname_actions %} that help you create more complex workflows.
|
||||
|
||||
### Storing secrets
|
||||
|
||||
If your workflows use sensitive data, such as passwords or certificates, you can save these in {% data variables.product.prodname_dotcom %} as _secrets_ and then use them in your workflows as environment variables. This means that you will be able to create and share workflows without having to embed sensitive values directly in the workflow's YAML source.
|
||||
|
||||
This example job demonstrates how to reference an existing secret as an environment variable, and send it as a parameter to an example command.
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
@@ -42,11 +77,11 @@ jobs:
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
For more information, see "[Creating and storing encrypted secrets](/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets)."
|
||||
For more information, see "[Encrypted secrets](/actions/security-guides/encrypted-secrets)."
|
||||
|
||||
## Creating dependent jobs
|
||||
### Creating dependent jobs
|
||||
|
||||
By default, the jobs in your workflow all run in parallel at the same time. So if you have a job that must only run after another job has completed, you can use the `needs` keyword to create this dependency. If one of the jobs fails, all dependent jobs are skipped; however, if you need the jobs to continue, you can define this using the [`if`](/actions/using-jobs/using-conditions-to-control-job-execution) conditional statement.
|
||||
By default, the jobs in your workflow all run in parallel at the same time. If you have a job that must only run after another job has completed, you can use the `needs` keyword to create this dependency. If one of the jobs fails, all dependent jobs are skipped; however, if you need the jobs to continue, you can define this using the `if` conditional statement.
|
||||
|
||||
In this example, the `setup`, `build`, and `test` jobs run in series, with `build` and `test` being dependent on the successful completion of the job that precedes them:
|
||||
|
||||
@@ -70,9 +105,9 @@ jobs:
|
||||
|
||||
For more information, see "[Defining prerequisite jobs](/actions/using-jobs/using-jobs-in-a-workflow#defining-prerequisite-jobs)."
|
||||
|
||||
## Using a build matrix
|
||||
### Using a build matrix
|
||||
|
||||
You can use a build matrix if you want your workflow to run tests across multiple combinations of operating systems, platforms, and languages. The build matrix is created using the `strategy` keyword, which receives the build options as an array. For example, this build matrix will run the job multiple times, using different versions of Node.js:
|
||||
You can use a build matrix if you want your workflow to run tests across multiple combinations of parameters, such as operating systems, platforms, and languages. The build matrix is created using the `strategy` keyword, which receives the build options as an array. For example, this build matrix will run the job multiple times, using different versions of Node.js:
|
||||
|
||||
```yaml
|
||||
jobs:
|
||||
@@ -90,7 +125,7 @@ jobs:
|
||||
For more information, see "[Using a build matrix for your jobs](/actions/using-jobs/using-a-build-matrix-for-your-jobs)."
|
||||
|
||||
{% ifversion fpt or ghec %}
|
||||
## Caching dependencies
|
||||
### Caching dependencies
|
||||
|
||||
{% data variables.product.prodname_dotcom %}-hosted runners are started as fresh environments for each job, so if your jobs regularly reuse dependencies, you can consider caching these files to help improve performance. Once the cache is created, it is available to all workflows in the same repository.
|
||||
|
||||
@@ -111,10 +146,10 @@ jobs:
|
||||
{% raw %}${{ runner.os }}-build-${{ env.cache-name }}-{% endraw %}
|
||||
```
|
||||
|
||||
For more information, see "<a href="/actions/guides/caching-dependencies-to-speed-up-workflows" class="dotcom-only">Caching dependencies to speed up workflows</a>."
|
||||
For more information, see "[Caching dependencies to speed up workflows](/actions/using-workflows/caching-dependencies-to-speed-up-workflows)."
|
||||
{% endif %}
|
||||
|
||||
## Using databases and service containers
|
||||
### Using databases and service containers
|
||||
|
||||
If your job requires a database or cache service, you can use the [`services`](/actions/using-jobs/running-jobs-in-a-container) keyword to create an ephemeral container to host the service; the resulting container is then available to all steps in that job and is removed when the job has completed. This example demonstrates how a job can use `services` to create a `postgres` container, and then use `node` to connect to the service.
|
||||
|
||||
@@ -138,11 +173,11 @@ jobs:
|
||||
POSTGRES_PORT: 5432
|
||||
```
|
||||
|
||||
For more information, see "[Using databases and service containers](/actions/configuring-and-managing-workflows/using-databases-and-service-containers)."
|
||||
For more information, see "[Using containerized services](/actions/using-containerized-services)."
|
||||
|
||||
## Using labels to route workflows
|
||||
### Using labels to route workflows
|
||||
|
||||
This feature helps you assign jobs to a specific hosted runner. If you want to be sure that a particular type of runner will process your job, you can use labels to control where jobs are executed. You can assign labels to a self-hosted runner in addition to their default label of `self-hosted`. Then, you can refer to these labels in your YAML workflow, ensuring that the job is routed in a predictable way.{% ifversion not ghae %} {% data variables.product.prodname_dotcom %}-hosted runners have predefined labels assigned.{% endif %}
|
||||
If you want to be sure that a particular type of runner will process your job, you can use labels to control where jobs are executed. You can assign labels to a self-hosted runner in addition to their default label of `self-hosted`. Then, you can refer to these labels in your YAML workflow, ensuring that the job is routed in a predictable way.{% ifversion not ghae %} {% data variables.product.prodname_dotcom %}-hosted runners have predefined labels assigned.{% endif %}
|
||||
|
||||
This example shows how a workflow can use labels to specify the required runner:
|
||||
|
||||
@@ -152,34 +187,19 @@ jobs:
|
||||
runs-on: [self-hosted, linux, x64, gpu]
|
||||
```
|
||||
|
||||
A workflow will only run on a runner that has all the labels in the `runs-on` array. The job will preferentially go to an idle self-hosted runner with the specified labels. If none are available and a {% data variables.product.prodname_dotcom %}-hosted runner with the specified labels exists, the job will go to a {% data variables.product.prodname_dotcom %}-hosted runner.
|
||||
A workflow will only run on a runner that has all the labels in the `runs-on` array. The job will preferentially go to an idle self-hosted runner with the specified labels. {% ifversion fpt or ghec %}If none are available and a {% data variables.product.prodname_dotcom %}-hosted runner with the specified labels exists, the job will go to a {% data variables.product.prodname_dotcom %}-hosted runner.{% endif %}
|
||||
|
||||
To learn more about self-hosted runner labels, see ["Using labels with self-hosted runners](/actions/hosting-your-own-runners/using-labels-with-self-hosted-runners)."
|
||||
To learn more about self-hosted runner labels, see "[Using labels with self-hosted runners](/actions/hosting-your-own-runners/using-labels-with-self-hosted-runners)."
|
||||
|
||||
{% ifversion fpt or ghes %}
|
||||
To learn more about {% data variables.product.prodname_dotcom %}-hosted runner labels, see ["Supported runners and hardware resources"](/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources).
|
||||
{% ifversion fpt or ghec %}
|
||||
To learn more about {% data variables.product.prodname_dotcom %}-hosted runner labels, see "[Supported runners and hardware resources](/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources)."
|
||||
{% endif %}
|
||||
|
||||
{% ifversion fpt or ghes > 3.3 or ghae-issue-4757 or ghec %}
|
||||
## Reusing workflows
|
||||
### Reusing workflows
|
||||
{% data reusables.actions.reusable-workflows %}
|
||||
{% endif %}
|
||||
|
||||
## Using environments
|
||||
### Using environments
|
||||
|
||||
You can configure environments with protection rules and secrets. Each job in a workflow can reference a single environment. Any protection rules configured for the environment must pass before a job referencing the environment is sent to a runner. For more information, see "[Using environments for deployment](/actions/deployment/using-environments-for-deployment)."
|
||||
|
||||
## Using starter workflows
|
||||
|
||||
{% data reusables.actions.workflow-template-overview %}
|
||||
|
||||
{% data reusables.repositories.navigate-to-repo %}
|
||||
{% data reusables.repositories.actions-tab %}
|
||||
1. If your repository already has existing workflows: In the upper-left corner, click **New workflow**.
|
||||
|
||||
1. Under the name of the starter workflow you'd like to use, click **Set up this workflow**.
|
||||
|
||||
|
||||
## Next steps
|
||||
|
||||
To continue learning about {% data variables.product.prodname_actions %}, see "[Sharing workflows, secrets, and runners with your organization](/actions/learn-github-actions/sharing-workflows-secrets-and-runners-with-your-organization)."
|
||||
You can configure environments with protection rules and secrets to control the execution of jobs in a workflow. Each job in a workflow can reference a single environment. Any protection rules configured for the environment must pass before a job referencing the environment is sent to a runner. For more information, see "[Using environments for deployment](/actions/deployment/using-environments-for-deployment)."
|
||||
@@ -21,12 +21,12 @@ versions:
|
||||
ghae: '*'
|
||||
ghec: '*'
|
||||
children:
|
||||
- /about-workflows
|
||||
- /triggering-a-workflow
|
||||
- /events-that-trigger-workflows
|
||||
- /workflow-syntax-for-github-actions
|
||||
- /workflow-commands-for-github-actions
|
||||
- /reusing-workflows
|
||||
- /advanced-workflow-features
|
||||
- /creating-starter-workflows-for-your-organization
|
||||
- /using-starter-workflows
|
||||
- /sharing-workflows-secrets-and-runners-with-your-organization
|
||||
|
||||
@@ -20,14 +20,7 @@ miniTocMaxHeadingLevel: 3
|
||||
|
||||
## About workflow triggers
|
||||
|
||||
Workflow triggers are events that cause a workflow to run. These events can be:
|
||||
|
||||
- Events that occur in your workflow's repository
|
||||
- Events that occur outside of {% data variables.product.product_name %} and trigger a `repository_dispatch` event on {% data variables.product.product_name %}
|
||||
- Scheduled times
|
||||
- Manual
|
||||
|
||||
For example, you can configure your workflow to run when a push is made to the default branch of your repository, when a release is created, or when an issue is opened.
|
||||
{% data reusables.actions.about-triggers %}
|
||||
|
||||
Workflow triggers are defined with the `on` key. For more information, see "[Workflow syntax for {% data variables.product.prodname_actions %}](/articles/workflow-syntax-for-github-actions#on)."
|
||||
|
||||
|
||||
@@ -39,8 +39,10 @@ Anyone with write permission to a repository can set up {% data variables.produc
|
||||
{% data reusables.repositories.navigate-to-repo %}
|
||||
{% data reusables.repositories.actions-tab %}
|
||||
1. If you already have a workflow in your repository, click **New workflow**.
|
||||
1. Find the starter workflow that you want to use, then click **Set up this workflow**.{% if actions-starter-template-ui %} To help you find the starter workflow that you want, you can search for keywords or filter by category.{% endif %}
|
||||
1. If the starter workflow contains comments detailing additional setup steps, follow these steps. Many of the starter workflow have corresponding guides. For more information, see [the {% data variables.product.prodname_actions %} guides](/actions/guides)."
|
||||
1. The "{% if actions-starter-template-ui %}Choose a workflow{% else %}Choose a workflow template{% endif %}" page shows a selection of recommended starter workflows. Find the starter workflow that you want to use, then click {% if actions-starter-template-ui %}**Configure**{% else %}**Set up this workflow**{% endif %}.{% if actions-starter-template-ui %} To help you find the starter workflow that you want, you can search for keywords or filter by category.{% endif %}
|
||||
|
||||
{% if actions-starter-template-ui %}{% else %}{% endif %}
|
||||
1. If the starter workflow contains comments detailing additional setup steps, follow these steps. Many of the starter workflow have corresponding guides. For more information, see the [{% data variables.product.prodname_actions %} guides](/actions/guides).
|
||||
1. Some starter workflows use secrets. For example, {% raw %}`${{ secrets.npm_token }}`{% endraw %}. If the starter workflow uses a secret, store the value described in the secret name as a secret in your repository. For more information, see "[Encrypted secrets](/actions/reference/encrypted-secrets)."
|
||||
1. Optionally, make additional changes. For example, you might want to change the value of `on` to change when the workflow runs.
|
||||
1. Click **Start commit**.
|
||||
|
||||
@@ -1,38 +1,50 @@
|
||||
---
|
||||
title: GitHub Enterprise Server releases
|
||||
intro: 'Documentation for the currently supported and previously deprecated versions of {{ site.data.variables.product.prodname_ghe_server }}.'
|
||||
intro: "{% data variables.product.company_short %} releases new versions of {% data variables.product.product_name %} regularly. You can review supported versions, see deprecation dates, and browse documentation for the release you've deployed."
|
||||
allowTitleToDifferFromFilename: true
|
||||
versions:
|
||||
ghes: '*'
|
||||
topics:
|
||||
- Enterprise
|
||||
- Upgrades
|
||||
shortTitle: Releases
|
||||
---
|
||||
|
||||
## Currently supported
|
||||
## About releases of {% data variables.product.product_name %}
|
||||
|
||||
See [{% data variables.product.prodname_enterprise %}](https://github.com/enterprise) for information about the latest release.
|
||||
{% data reusables.enterprise.constantly-improving %} {% data variables.product.company_short %} supports the four most recent feature releases. For more information, see "[About upgrades to new releases](/admin/overview/about-upgrades-to-new-releases)."
|
||||
|
||||
{% for supportedRelease in enterpriseServerReleases.supported %}
|
||||
- [{% data variables.product.prodname_ghe_server %} {{supportedRelease}}](/enterprise-server@{{supportedRelease}})
|
||||
{% endfor %}
|
||||
You can see what's new for each release in the [release notes](/admin/release-notes), and you can view administrator and user documentation for all releases here on {% data variables.product.prodname_docs %}. When you read the documentation, make sure to select the version that reflects your product. For more information, see "[About versions of {% data variables.product.prodname_docs %}](/get-started/learning-about-github/about-versions-of-github-docs)."
|
||||
|
||||
## Deprecated
|
||||
## Currently supported releases
|
||||
|
||||
Documentation for deprecated versions remains available but is no longer maintained.
|
||||
{% data variables.product.company_short %} supports the following releases of {% data variables.product.product_name %}. For more information about the latest release, see the [{% data variables.product.prodname_enterprise %}](https://github.com/enterprise) website.
|
||||
|
||||
{% for deprecatedRelease in enterpriseServerReleases.deprecatedReleasesWithNewFormat %}
|
||||
- [Enterprise Server {{deprecatedRelease}}](/enterprise-server@{{deprecatedRelease}})
|
||||
{% endfor %}
|
||||
| Version | Release | Deprecation | Release notes | Documentation |
|
||||
| :- | :- | :- | :- | :- |
|
||||
{%- for version in enterpriseServerReleases.supported %}
|
||||
| {{version}} | {{enterpriseServerReleases.dates[version].releaseDate}} | {{enterpriseServerReleases.dates[version].deprecationDate}} | [{{version}} release notes](/enterprise-server@{{version}}/admin/release-notes) | [{{version}} documentation](/enterprise-server@{{version}}) |
|
||||
{%- endfor %}
|
||||
|
||||
{% for deprecatedReleaseLegacyFormat in enterpriseServerReleases.deprecatedReleasesWithLegacyFormat %}
|
||||
- [Enterprise Server {{deprecatedReleaseLegacyFormat}}](/enterprise/{{deprecatedReleaseLegacyFormat}})
|
||||
{% endfor %}
|
||||
## Deprecated releases
|
||||
|
||||
## Deprecated developer documentation
|
||||
{% data variables.product.company_short %} provides documentation for deprecated versions, but does not maintain or update the documentation.
|
||||
|
||||
Developer documentation for deprecated versions remains available but is no longer maintained.
|
||||
| Version | Release | Deprecation | Release notes | Documentation |
|
||||
| :- | :- | :- | :- | :- |
|
||||
{%- for version in enterpriseServerReleases.deprecatedReleasesWithNewFormat %}
|
||||
| {{version}} | {{enterpriseServerReleases.dates[version].releaseDate}} | {{enterpriseServerReleases.dates[version].deprecationDate}} | [{{version}} release notes](/enterprise-server@{{version}}/admin/release-notes) | [{{version}} documentation](/enterprise-server@{{version}}) |
|
||||
{%- endfor %}
|
||||
{%- for version in enterpriseServerReleases.deprecatedReleasesWithLegacyFormat %}
|
||||
| {{version}} | {{enterpriseServerReleases.dates[version].releaseDate}} | {{enterpriseServerReleases.dates[version].deprecationDate}} | [{{version}} release notes](https://enterprise.github.com/releases/series/{{version}}) | [{{version}} documentation](/enterprise/{{version}}) |
|
||||
{%- endfor %}
|
||||
|
||||
{% for deprecatedDevRelease in enterpriseServerReleases.deprecatedReleasesOnDeveloperSite %}
|
||||
- [Enterprise Server {{deprecatedDevRelease}}](https://developer.github.com/enterprise/{{deprecatedDevRelease}})
|
||||
{% endfor %}
|
||||
### Deprecated developer documentation
|
||||
|
||||
{% data variables.product.company_short %} hosted developer documentation for {% data variables.product.product_name %} on a separate site until the 2.17 release. {% data variables.product.company_short %} continues to provide developer documentation for version 2.16 and earlier, but does not maintain or update the documentation.
|
||||
|
||||
| Version | Release | Deprecation | Developer documentation |
|
||||
| :- | :- | :- | :- |
|
||||
{%- for version in enterpriseServerReleases.deprecatedReleasesOnDeveloperSite %}
|
||||
| {{version}} | {{enterpriseServerReleases.dates[version].releaseDate}} | {{enterpriseServerReleases.dates[version].deprecationDate}} | [{{version}} developer documentation](https://developer.github.com/enterprise/{{version}}) |
|
||||
{%- endfor %}
|
||||
|
||||
@@ -27,7 +27,7 @@ topics:
|
||||
|
||||
As an enterprise owner, you can allow end users to send anonymized contribution counts for their work from {% data variables.product.product_location %} to their {% data variables.product.prodname_dotcom_the_website %} contribution graph.
|
||||
|
||||
After you enable {% data variables.product.prodname_unified_contributions %}, before individual users can send contribution counts from {% data variables.product.product_location %} to {% data variables.product.prodname_dotcom_the_website %}, each user must also connect their personal account on {% data variables.product.product_name %} with a personal account on {% data variables.product.prodname_dotcom_the_website %}. For more information, see "[Sending enterprise contributions to your {% data variables.product.prodname_dotcom_the_website %} profile](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-graphs-on-your-profile/sending-enterprise-contributions-to-your-githubcom-profile)."
|
||||
After you enable {% data variables.product.prodname_unified_contributions %}, before individual users can send contribution counts from {% data variables.product.product_location %} to {% data variables.product.prodname_dotcom_the_website %}, each user must also connect their user account on {% data variables.product.product_name %} with a personal account on {% data variables.product.prodname_dotcom_the_website %}. For more information, see "[Sending enterprise contributions to your {% data variables.product.prodname_dotcom_the_website %} profile](/account-and-profile/setting-up-and-managing-your-github-profile/managing-contribution-graphs-on-your-profile/sending-enterprise-contributions-to-your-githubcom-profile)."
|
||||
|
||||
{% data reusables.github-connect.sync-frequency %}
|
||||
|
||||
|
||||
@@ -32,7 +32,7 @@ You can choose to allow search results for public repositories on {% data variab
|
||||
|
||||
Users will never be able to search {% data variables.product.product_location %} from {% data variables.product.prodname_dotcom_the_website %}, even if they have access to both environments.
|
||||
|
||||
After you enable unified search for {% data variables.product.product_location %}, before individual users can see search results from {% data variables.product.prodname_dotcom_the_website %} on {% data variables.product.product_location %}, each user must also connect their personal account on {% data variables.product.product_name %} with a personal account on {% data variables.product.prodname_dotcom_the_website %}. For more information, see "[Enabling {% data variables.product.prodname_dotcom_the_website %} repository search in your private enterprise account](/search-github/getting-started-with-searching-on-github/enabling-githubcom-repository-search-from-your-private-enterprise-environment)."
|
||||
After you enable unified search for {% data variables.product.product_location %}, before individual users can see search results from {% data variables.product.prodname_dotcom_the_website %} on {% data variables.product.product_location %}, each user must also connect their user account on {% data variables.product.product_name %} with a personal account on {% data variables.product.prodname_dotcom_the_website %}. For more information, see "[Enabling {% data variables.product.prodname_dotcom_the_website %} repository search in your private enterprise account](/search-github/getting-started-with-searching-on-github/enabling-githubcom-repository-search-from-your-private-enterprise-environment)."
|
||||
|
||||
Searching via the REST and GraphQL APIs does not include {% data variables.product.prodname_dotcom_the_website %} search results. Advanced search and searching for wikis in {% data variables.product.prodname_dotcom_the_website %} are not supported.
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ topics:
|
||||
- Privacy
|
||||
- Security
|
||||
---
|
||||
You must enable private mode if {% data variables.product.product_location %} is publicly accessible over the Internet. In private mode, users cannot anonymously clone repositories over `git://`. If built-in authentication is also enabled, an administrator must invite new users to create an account on the instance. For more information, see "[Using built-in authentication](/enterprise/{{ currentVersion }}/admin/guides/user-management/using-built-in-authentication)."
|
||||
You must enable private mode if {% data variables.product.product_location %} is publicly accessible over the Internet. In private mode, users cannot anonymously clone repositories over `git://`. If built-in authentication is also enabled, an administrator must invite new users to create an account on the instance. For more information, see "[Configuring built-in authentication](/admin/identity-and-access-management/using-built-in-authentication/configuring-built-in-authentication)."
|
||||
|
||||
{% data reusables.enterprise_installation.image-urls-viewable-warning %}
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Configuring GitHub Enterprise
|
||||
shortTitle: Configuring GitHub Enterprise
|
||||
shortTitle: Configure GitHub Enterprise
|
||||
intro: You can configure your enterprise to suit your organization's needs.
|
||||
redirect_from:
|
||||
- /enterprise/admin/configuration
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Using a staging environment
|
||||
intro: 'Learn about using {% data variables.product.prodname_actions %} with {% data variables.product.prodname_ghe_server %} staging environments.'
|
||||
intro: 'Learn about using {% data variables.product.prodname_actions %} with {% data variables.product.prodname_ghe_server %} staging instances.'
|
||||
versions:
|
||||
ghes: '*'
|
||||
type: how_to
|
||||
@@ -11,17 +11,34 @@ topics:
|
||||
- Upgrades
|
||||
redirect_from:
|
||||
- /admin/github-actions/using-a-staging-environment
|
||||
shortTitle: Use a staging area
|
||||
shortTitle: Use staging environment
|
||||
---
|
||||
It can be useful to have a staging or testing environment for {% data variables.product.product_location %}, so that you can test updates or new features before implementing them in your production environment.
|
||||
|
||||
A common way to create the staging environment is to use a backup of your production instance and restore it to the staging environment.
|
||||
## About staging environments for {% data variables.product.product_name %}
|
||||
|
||||
When setting up a {% data variables.product.prodname_ghe_server %} staging environment that has {% data variables.product.prodname_actions %} enabled, you must use a different external storage configuration for {% data variables.product.prodname_actions %} storage than your production environment uses. Otherwise, your staging environment will write to the same external storage as production.
|
||||
It can be useful to have a staging or testing environment for {% data variables.product.product_location %}, so that you can test updates or new features before implementing them in your production environment. For more information, see "[Setting up a staging instance](/admin/installation/setting-up-a-github-enterprise-server-instance/setting-up-a-staging-instance)."
|
||||
|
||||
Expect to see `404` errors in your staging environment when trying to view logs or artifacts from existing {% data variables.product.prodname_actions %} workflow runs, because that data will be missing from your staging storage location.
|
||||
## Using a staging environment with {% data variables.product.prodname_actions %}
|
||||
|
||||
Although it is not required for {% data variables.product.prodname_actions %} to be functional in your staging environment, you can optionally copy the files from the production storage location to the staging storage location.
|
||||
A common way to create the staging environment is to restore a backup of your production {% data variables.product.product_name %} instance to a new virtual machine in the staging environment. If you use a staging instance and plan to test {% data variables.product.prodname_actions %} functionality, you should review your storage configuration in the staging environment.
|
||||
|
||||
After you restore a {% data variables.product.prodname_ghe_server %} backup to the staging instance, if you try to view logs or artifacts from existing {% data variables.product.prodname_actions %} workflow runs on your staging instance, you will see `404` errors, because this data will be missing from your staging storage location. To work around the `404` errors, you can copy data from production to use in your staging environment.
|
||||
|
||||
### Configuring storage
|
||||
|
||||
When you set up a staging environment that includes a {% data variables.product.product_name %} instance with {% data variables.product.prodname_actions %} enabled, you must use a different external storage configuration for {% data variables.product.prodname_actions %} storage than your production environment.
|
||||
|
||||
{% warning %}
|
||||
|
||||
**Warning**: If you don't change the storage configuration, your staging instance may be able to write to the same external storage that you use for production, which could result in loss of data.
|
||||
|
||||
{% endwarning %}
|
||||
|
||||
For more information about storage configuration for {% data variables.product.prodname_actions %}, see "[Getting started with {% data variables.product.prodname_actions %} for {% data variables.product.prodname_ghe_server %}](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-enterprise-server#enabling-github-actions-with-your-storage-provider)."
|
||||
|
||||
### Copying files from production to staging
|
||||
|
||||
To more accurately mirror your production environment, you can optionally copy files from your production storage location for {% data variables.product.prodname_actions %} to the staging storage location.
|
||||
|
||||
* For an Azure storage account, you can use [`azcopy`](https://docs.microsoft.com/en-us/azure/storage/common/storage-use-azcopy-blobs#copy-all-containers-directories-and-blobs-to-another-storage-account). For example:
|
||||
|
||||
|
||||
@@ -1,24 +0,0 @@
|
||||
---
|
||||
title: Disabling unauthenticated sign-ups
|
||||
redirect_from:
|
||||
- /enterprise/admin/articles/disabling-sign-ups
|
||||
- /enterprise/admin/user-management/disabling-unauthenticated-sign-ups
|
||||
- /enterprise/admin/authentication/disabling-unauthenticated-sign-ups
|
||||
- /admin/authentication/disabling-unauthenticated-sign-ups
|
||||
- /enterprise/admin/authentication/authenticating-users-for-your-github-enterprise-server-instance/disabling-unauthenticated-sign-ups
|
||||
intro: 'If you''re using built-in authentication, you can block unauthenticated people from being able to create an account.'
|
||||
versions:
|
||||
ghes: '*'
|
||||
type: how_to
|
||||
topics:
|
||||
- Accounts
|
||||
- Authentication
|
||||
- Enterprise
|
||||
shortTitle: Block account creation
|
||||
---
|
||||
{% data reusables.enterprise_site_admin_settings.access-settings %}
|
||||
{% data reusables.enterprise_site_admin_settings.management-console %}
|
||||
{% data reusables.enterprise_management_console.privacy %}
|
||||
3. Unselect **Enable sign-up**.
|
||||
|
||||
{% data reusables.enterprise_management_console.save-settings %}
|
||||
@@ -1,25 +0,0 @@
|
||||
---
|
||||
title: Authenticating users for your GitHub Enterprise Server instance
|
||||
intro: 'You can use {% data variables.product.prodname_ghe_server %}''s built-in authentication, or choose between CAS, LDAP, or SAML to integrate your existing accounts and centrally manage user access to {% data variables.product.product_location %}.'
|
||||
redirect_from:
|
||||
- /enterprise/admin/categories/authentication
|
||||
- /enterprise/admin/guides/installation/user-authentication
|
||||
- /enterprise/admin/articles/inviting-users
|
||||
- /enterprise/admin/guides/migrations/authenticating-users-for-your-github-enterprise-instance
|
||||
- /enterprise/admin/user-management/authenticating-users-for-your-github-enterprise-server-instance
|
||||
- /enterprise/admin/authentication/authenticating-users-for-your-github-enterprise-server-instance
|
||||
versions:
|
||||
ghes: '*'
|
||||
topics:
|
||||
- Enterprise
|
||||
children:
|
||||
- /using-built-in-authentication
|
||||
- /disabling-unauthenticated-sign-ups
|
||||
- /using-cas
|
||||
- /using-saml
|
||||
- /using-ldap
|
||||
- /allowing-built-in-authentication-for-users-outside-your-identity-provider
|
||||
- /changing-authentication-methods
|
||||
shortTitle: Authenticate users
|
||||
---
|
||||
|
||||
@@ -1,53 +0,0 @@
|
||||
---
|
||||
title: Using CAS
|
||||
redirect_from:
|
||||
- /enterprise/admin/articles/configuring-cas-authentication
|
||||
- /enterprise/admin/articles/about-cas-authentication
|
||||
- /enterprise/admin/user-management/using-cas
|
||||
- /enterprise/admin/authentication/using-cas
|
||||
- /admin/authentication/using-cas
|
||||
- /enterprise/admin/authentication/authenticating-users-for-your-github-enterprise-server-instance/using-cas
|
||||
intro: 'CAS is a single sign-on (SSO) protocol for multiple web applications. A CAS user account does not take up a {% ifversion ghes %}user license{% else %}seat{% endif %} until the user signs in.'
|
||||
versions:
|
||||
ghes: '*'
|
||||
type: how_to
|
||||
topics:
|
||||
- Accounts
|
||||
- Authentication
|
||||
- Enterprise
|
||||
- Identity
|
||||
- SSO
|
||||
---
|
||||
{% data reusables.enterprise_user_management.built-in-authentication %}
|
||||
|
||||
## Username considerations with CAS
|
||||
|
||||
{% data reusables.enterprise_management_console.username_normalization %}
|
||||
|
||||
{% data reusables.enterprise_management_console.username_normalization_sample %}
|
||||
|
||||
{% data reusables.enterprise_user_management.two_factor_auth_header %}
|
||||
{% data reusables.enterprise_user_management.external_auth_disables_2fa %}
|
||||
|
||||
## CAS attributes
|
||||
|
||||
The following attributes are available.
|
||||
|
||||
| Attribute name | Type | Description |
|
||||
|--------------------------|----------|-------------|
|
||||
| `username` | Required | The {% data variables.product.prodname_ghe_server %} username. |
|
||||
|
||||
## Configuring CAS
|
||||
{% warning %}
|
||||
|
||||
**Warning:** Before configuring CAS on {% data variables.product.product_location %}, note that users will not be able to use their CAS usernames and passwords to authenticate API requests or Git operations over HTTP/HTTPS. Instead, they will need to [create an access token](/enterprise/{{ currentVersion }}/user/articles/creating-an-access-token-for-command-line-use).
|
||||
|
||||
{% endwarning %}
|
||||
|
||||
{% data reusables.enterprise_site_admin_settings.access-settings %}
|
||||
{% data reusables.enterprise_site_admin_settings.management-console %}
|
||||
{% data reusables.enterprise_management_console.authentication %}
|
||||
3. Select **CAS**.
|
||||
|
||||
4. {% data reusables.enterprise_user_management.built-in-authentication-option %} 
|
||||
5. In the **Server URL** field, type the full URL of your CAS server. If your CAS server uses a certificate that can't be validated by {% data variables.product.prodname_ghe_server %}, you can use the `ghe-ssl-ca-certificate-install` command to install it as a trusted certificate.
|
||||
@@ -1,319 +0,0 @@
|
||||
---
|
||||
title: Using SAML
|
||||
redirect_from:
|
||||
- /enterprise/admin/articles/configuring-saml-authentication
|
||||
- /enterprise/admin/articles/about-saml-authentication
|
||||
- /enterprise/admin/user-management/using-saml
|
||||
- /enterprise/admin/authentication/using-saml
|
||||
- /admin/authentication/using-saml
|
||||
- /enterprise/admin/authentication/authenticating-users-for-your-github-enterprise-server-instance/using-saml
|
||||
intro: 'You can configure SAML single sign-on (SSO) for {% data variables.product.product_name %}, which allows users to authenticate through a SAML identity provider (IdP) to access your instance.'
|
||||
versions:
|
||||
ghes: '*'
|
||||
type: how_to
|
||||
topics:
|
||||
- Accounts
|
||||
- Authentication
|
||||
- Enterprise
|
||||
- Identity
|
||||
- SSO
|
||||
---
|
||||
|
||||
## About SAML for {% data variables.product.product_name %}
|
||||
|
||||
SAML SSO allows people to authenticate and access {% data variables.product.product_location %} through an external system for identity management.
|
||||
|
||||
SAML is an XML-based standard for authentication and authorization. When you configure SAML for {% data variables.product.product_location %}, the external system for authentication is called an identity provider (IdP). Your instance acts as a SAML service provider (SP). For more information, see [Security Assertion Markup Language](https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language) on Wikipedia.
|
||||
|
||||
{% data reusables.enterprise_user_management.built-in-authentication %}
|
||||
|
||||
## Supported SAML services
|
||||
|
||||
{% data reusables.saml.saml-supported-idps %}
|
||||
|
||||
{% ifversion ghes > 3.3 %}
|
||||
|
||||
If your IdP supports encrypted assertions, you can configure encrypted assertions on {% data variables.product.product_name %} for increased security during the authentication process.
|
||||
|
||||
{% endif %}
|
||||
|
||||
{% data reusables.saml.saml-single-logout-not-supported %}
|
||||
|
||||
## Username considerations with SAML
|
||||
|
||||
Each {% data variables.product.prodname_ghe_server %} username is determined by one of the following assertions in the SAML response, ordered by priority:
|
||||
|
||||
- The custom username attribute, if defined and present
|
||||
- An `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` assertion, if present
|
||||
- An `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` assertion, if present
|
||||
- The `NameID` element
|
||||
|
||||
The `NameID` element is required even if other attributes are present.
|
||||
|
||||
A mapping is created between the `NameID` and the {% data variables.product.prodname_ghe_server %} username, so the `NameID` should be persistent, unique, and not subject to change for the lifecycle of the user.
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note**: If the `NameID` for a user does change on the IdP, the user will see an error message when they try to sign into {% data variables.product.product_location %}. To restore the user's access, you'll need to update the user account's `NameID` mapping. For more information, see "[Updating a user's SAML `NameID`](#updating-a-users-saml-nameid)."
|
||||
|
||||
{% endnote %}
|
||||
|
||||
{% data reusables.enterprise_management_console.username_normalization %}
|
||||
|
||||
{% data reusables.enterprise_management_console.username_normalization_sample %}
|
||||
|
||||
{% data reusables.enterprise_user_management.two_factor_auth_header %}
|
||||
{% data reusables.enterprise_user_management.external_auth_disables_2fa %}
|
||||
|
||||
## SAML metadata
|
||||
|
||||
The service provider metadata for {% data variables.product.product_location %} is available at `http(s)://[hostname]/saml/metadata`.
|
||||
|
||||
To configure your identity provider manually, the Assertion Consumer Service (ACS) URL is `http(s)://[hostname]/saml/consume`. It uses the `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST` binding.
|
||||
|
||||
## SAML attributes
|
||||
|
||||
These attributes are available. You can change the attribute names in the [management console](/enterprise/{{ currentVersion }}/admin/guides/installation/accessing-the-management-console/), with the exception of the `administrator` attribute.
|
||||
|
||||
| Default attribute name | Type | Description |
|
||||
|-----------------|----------|-------------|
|
||||
| `NameID` | Required | A persistent user identifier. Any persistent name identifier format may be used. The `NameID` element will be used for a {% data variables.product.prodname_ghe_server %} username unless one of the alternative assertions is provided. |
|
||||
| `administrator` | Optional | When the value is 'true', the user will automatically be promoted as an administrator. Any other value or a non-existent value will demote the user to a normal user account. |
|
||||
| `username` | Optional | The {% data variables.product.prodname_ghe_server %} username. |
|
||||
| `full_name` | Optional | The name of the user displayed on their profile page. Users may change their names after provisioning. |
|
||||
| `emails` | Optional | The email addresses for the user. More than one can be specified. |
|
||||
| `public_keys` | Optional | The public SSH keys for the user. More than one can be specified. |
|
||||
| `gpg_keys` | Optional | The GPG keys for the user. More than one can be specified. |
|
||||
|
||||
To specify more than one value for an attribute, use multiple `<saml2:AttributeValue>` elements.
|
||||
|
||||
```
|
||||
<saml2:Attribute FriendlyName="public_keys" Name="urn:oid:1.2.840.113549.1.1.1" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
|
||||
<saml2:AttributeValue>ssh-rsa LONG KEY</saml2:AttributeValue>
|
||||
<saml2:AttributeValue>ssh-rsa LONG KEY 2</saml2:AttributeValue>
|
||||
</saml2:Attribute>
|
||||
```
|
||||
|
||||
## Configuring SAML settings
|
||||
|
||||
You can enable or disable SAML authentication for {% data variables.product.product_location %}, or you can edit an existing configuration. You can view and edit authentication settings for {% data variables.product.product_name %} in the {% data variables.enterprise.management_console %}. For more information, see "[Accessing the management console](/admin/configuration/configuring-your-enterprise/accessing-the-management-console)."
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note**: {% data reusables.enterprise.test-in-staging %}
|
||||
|
||||
{% endnote %}
|
||||
|
||||
{% data reusables.enterprise_site_admin_settings.access-settings %}
|
||||
{% data reusables.enterprise_site_admin_settings.management-console %}
|
||||
{% data reusables.enterprise_management_console.authentication %}
|
||||
1. Select **SAML**.
|
||||
|
||||
|
||||
1. {% data reusables.enterprise_user_management.built-in-authentication-option %}
|
||||
|
||||
|
||||
1. Optionally, to enable unsolicited response SSO, select **IdP initiated SSO**. By default, {% data variables.product.prodname_ghe_server %} will reply to an unsolicited Identity Provider (IdP) initiated request with an `AuthnRequest` back to the IdP.
|
||||
|
||||
|
||||
|
||||
{% tip %}
|
||||
|
||||
**Note**: We recommend keeping this value **unselected**. You should enable this feature **only** in the rare instance that your SAML implementation does not support service provider initiated SSO, and when advised by {% data variables.contact.enterprise_support %}.
|
||||
|
||||
{% endtip %}
|
||||
|
||||
1. Select **Disable administrator demotion/promotion** if you **do not** want your SAML provider to determine administrator rights for users on {% data variables.product.product_location %}.
|
||||
|
||||
|
||||
{%- ifversion ghes > 3.3 %}
|
||||
1. Optionally, to allow {% data variables.product.product_location %} to receive encrypted assertions from your SAML IdP, select **Require encrypted assertions**. You must ensure that your IdP supports encrypted assertions and that the encryption and key transport methods in the management console match the values configured on your IdP. You must also provide {% data variables.product.product_location %}'s public certificate to your IdP. For more information, see "[Enabling encrypted assertions](#enabling-encrypted-assertions)."
|
||||
|
||||
|
||||
{%- endif %}
|
||||
1. In the **Single sign-on URL** field, type the HTTP or HTTPS endpoint on your IdP for single sign-on requests. This value is provided by your IdP configuration. If the host is only available from your internal network, you may need to [configure {% data variables.product.product_location %} to use internal nameservers](/enterprise/{{ currentVersion }}/admin/guides/installation/configuring-dns-nameservers/).
|
||||
|
||||
|
||||
1. Optionally, in the **Issuer** field, type your SAML issuer's name. This verifies the authenticity of messages sent to {% data variables.product.product_location %}.
|
||||
|
||||
|
||||
1. In the **Signature Method** and **Digest Method** drop-down menus, choose the hashing algorithm used by your SAML issuer to verify the integrity of the requests from {% data variables.product.product_location %}. Specify the format with the **Name Identifier Format** drop-down menu.
|
||||
|
||||
|
||||
1. Under **Verification certificate**, click **Choose File** and choose a certificate to validate SAML responses from the IdP.
|
||||
|
||||
|
||||
1. Modify the SAML attribute names to match your IdP if needed, or accept the default names.
|
||||
|
||||
|
||||
|
||||
{% ifversion ghes > 3.3 %}
|
||||
|
||||
## Enabling encrypted assertions
|
||||
|
||||
To enable encrypted assertions, your SAML IdP must also support encrypted assertions. You must provide {% data variables.product.product_location %}'s public certificate to your IdP, and configure encryption settings that match your IdP.
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note**: {% data reusables.enterprise.test-in-staging %}
|
||||
|
||||
{% endnote %}
|
||||
|
||||
1. Optionally, enable SAML debugging. SAML debugging records verbose entries in {% data variables.product.product_name %}'s authentication log, and may help you troubleshoot failed authentication attempts. For more information, see "[Configuring SAML debugging](#configuring-saml-debugging)."
|
||||
{% data reusables.enterprise_site_admin_settings.access-settings %}
|
||||
{% data reusables.enterprise_site_admin_settings.management-console %}
|
||||
{% data reusables.enterprise_management_console.authentication %}
|
||||
1. Select **Require encrypted assertions**.
|
||||
|
||||
|
||||
1. To the right of "Encryption Certificate", click **Download** to save a copy of {% data variables.product.product_location %}'s public certificate on your local machine.
|
||||
|
||||
|
||||
1. Sign into your SAML IdP as an administrator.
|
||||
1. In the application for {% data variables.product.product_location %}, enable encrypted assertions.
|
||||
- Note the encryption method and key transport method.
|
||||
- Provide the public certificate you downloaded in step 7.
|
||||
1. Return to the management console on {% data variables.product.product_location %}.
|
||||
1. To the right of "Encryption Method", select the encryption method for your IdP from step 9.
|
||||
|
||||
|
||||
1. To the right of "Key Transport Method", select the key transport method for your IdP from step 9.
|
||||
|
||||
|
||||
1. Click **Save settings**.
|
||||
{% data reusables.enterprise_site_admin_settings.wait-for-configuration-run %}
|
||||
|
||||
If you enabled SAML debugging to test authentication with encrypted assertions, disable SAML debugging when you're done testing. For more information, see "[Configuring SAML debugging](#configuring-saml-debugging)."
|
||||
|
||||
{% endif %}
|
||||
|
||||
## Updating a user's SAML `NameID`
|
||||
|
||||
{% data reusables.enterprise_site_admin_settings.access-settings %}
|
||||
2. In the left sidebar, click **All users**.
|
||||
|
||||
3. In the list of users, click the username you'd like to update the `NameID` mapping for.
|
||||
|
||||
{% data reusables.enterprise_site_admin_settings.security-tab %}
|
||||
5. To the right of "Update SAML NameID", click **Edit** .
|
||||
|
||||
6. In the "NameID" field, type the new `NameID` for the user.
|
||||
|
||||
7. Click **Update NameID**.
|
||||
|
||||
|
||||
## Revoking access to {% data variables.product.product_location %}
|
||||
|
||||
If you remove a user from your identity provider, you must also manually suspend them. Otherwise, they'll continue to be able to authenticate using access tokens or SSH keys. For more information, see "[Suspending and unsuspending users](/enterprise/admin/guides/user-management/suspending-and-unsuspending-users)".
|
||||
|
||||
## Response message requirements
|
||||
|
||||
The response message must fulfill the following requirements:
|
||||
|
||||
- The `<Destination>` element must be provided on the root response document and match the ACS URL only when the root response document is signed. If the assertion is signed, it will be ignored.
|
||||
- The `<Audience>` element must always be provided as part of the `<AudienceRestriction>` element. It must match the `EntityId` for {% data variables.product.prodname_ghe_server %}. This is the URL to the {% data variables.product.prodname_ghe_server %} instance, such as `https://ghe.corp.example.com`.
|
||||
- Each assertion in the response **must** be protected by a digital signature. This can be accomplished by signing each individual `<Assertion>` element or by signing the `<Response>` element.
|
||||
- A `<NameID>` element must be provided as part of the `<Subject>` element. Any persistent name identifier format may be used.
|
||||
- The `Recipient` attribute must be present and set to the ACS URL. For example:
|
||||
|
||||
```xml
|
||||
<samlp:Response ...>
|
||||
<saml:Assertion ...>
|
||||
<saml:Subject>
|
||||
<saml:NameID ...>...</saml:NameID>
|
||||
<saml:SubjectConfirmation ...>
|
||||
<saml:SubjectConfirmationData Recipient="https://ghe.corp.example.com/saml/consume" .../>
|
||||
</saml:SubjectConfirmation>
|
||||
</saml:Subject>
|
||||
<saml:AttributeStatement>
|
||||
<saml:Attribute FriendlyName="USERNAME-ATTRIBUTE" ...>
|
||||
<saml:AttributeValue>monalisa</saml:AttributeValue>
|
||||
</saml:Attribute>
|
||||
</saml:AttributeStatement>
|
||||
</saml:Assertion>
|
||||
</samlp:Response>
|
||||
```
|
||||
|
||||
## Troubleshooting SAML authentication
|
||||
|
||||
{% data variables.product.prodname_ghe_server %} logs error messages for failed SAML authentication in the authentication log at _/var/log/github/auth.log_. For more information about SAML response requirements, see "[Response message requirements](#response-message-requirements)."
|
||||
|
||||
### Error: "Another user already owns the account"
|
||||
|
||||
When a user signs in to {% data variables.product.prodname_ghe_server %} for the first time with SAML authentication, {% data variables.product.prodname_ghe_server %} creates a user account on the instance and maps the SAML `NameID` to the account.
|
||||
|
||||
When the user signs in again, {% data variables.product.prodname_ghe_server %} compares the account's `NameID` mapping to the IdP's response. If the `NameID` in the IdP's response no longer matches the `NameID` that {% data variables.product.prodname_ghe_server %} expects for the user, the sign-in will fail. The user will see the following message.
|
||||
|
||||
> Another user already owns the account. Please have your administrator check the authentication log.
|
||||
|
||||
The message typically indicates that the person's username or email address has changed on the IdP. Ensure that the `NameID` mapping for the user account on {% data variables.product.prodname_ghe_server %} matches the user's `NameID` on your IdP. For more information, see "[Updating a user's SAML `NameID`](#updating-a-users-saml-nameid)."
|
||||
|
||||
### Error: Recipient in SAML response was blank or not valid
|
||||
|
||||
If the `Recipient` does not match the ACS URL for {% data variables.product.product_location %}, one of the following two error messages will appear in the authentication log when a user attempts to authenticate.
|
||||
|
||||
```
|
||||
Recipient in the SAML response must not be blank.
|
||||
```
|
||||
|
||||
```
|
||||
Recipient in the SAML response was not valid.
|
||||
```
|
||||
|
||||
Ensure that you set the value for `Recipient` on your IdP to the full ACS URL for {% data variables.product.product_location %}. For example, `https://ghe.corp.example.com/saml/consume`.
|
||||
|
||||
### Error: "SAML Response is not signed or has been modified"
|
||||
|
||||
If your IdP does not sign the SAML response, or the signature does not match the contents, the following error message will appear in the authentication log.
|
||||
|
||||
```
|
||||
SAML Response is not signed or has been modified.
|
||||
```
|
||||
|
||||
Ensure that you configure signed assertions for the {% data variables.product.prodname_ghe_server %} application on your IdP.
|
||||
|
||||
### Error: "Audience is invalid" or "No assertion found"
|
||||
|
||||
If the IdP's response has a missing or incorrect value for `Audience`, the following error message will appear in the authentication log.
|
||||
|
||||
```shell
|
||||
Audience is invalid. Audience attribute does not match https://<em>YOUR-INSTANCE-URL</em>
|
||||
```
|
||||
|
||||
Ensure that you set the value for `Audience` on your IdP to the `EntityId` for {% data variables.product.product_location %}, which is the full URL to {% data variables.product.product_location %}. For example, `https://ghe.corp.example.com`.
|
||||
|
||||
### Configuring SAML debugging
|
||||
|
||||
You can configure {% data variables.product.product_name %} to write verbose debug logs to _/var/log/github/auth.log_ for every SAML authentication attempt. You may be able to troubleshoot failed authentication attempts with this extra output.
|
||||
|
||||
{% warning %}
|
||||
|
||||
**Warnings**:
|
||||
|
||||
- Only enable SAML debugging temporarily, and disable debugging immediately after you finish troubleshooting. If you leave debugging enabled, the size of your log may increase much faster than usual, which can negatively impact the performance of {% data variables.product.product_name %}.
|
||||
- Test new authentication settings for {% data variables.product.product_location %} in a staging environment before you apply the settings in your production environment. For more information, see "[Setting up a staging instance](/admin/installation/setting-up-a-github-enterprise-server-instance/setting-up-a-staging-instance)."
|
||||
|
||||
{% endwarning %}
|
||||
|
||||
{% data reusables.enterprise-accounts.access-enterprise %}
|
||||
{% data reusables.enterprise-accounts.policies-tab %}
|
||||
{% data reusables.enterprise-accounts.options-tab %}
|
||||
1. Under "SAML debugging", select the drop-down and click **Enabled**.
|
||||
|
||||
|
||||
|
||||
1. Attempt to sign into {% data variables.product.product_location %} through your SAML IdP.
|
||||
|
||||
1. Review the debug output in _/var/log/github/auth.log_ on {% data variables.product.product_location %}.
|
||||
|
||||
1. When you're done troubleshooting, select the drop-down and click **Disabled**.
|
||||
|
||||
|
||||
|
||||
### Decoding responses in _auth.log_
|
||||
|
||||
Some output in _auth.log_ may be Base64-encoded. You can access the administrative shell and use the `base64` utility on {% data variables.product.product_location %} to decode these responses. For more information, see "[Accessing the administrative shell (SSH)](/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh)."
|
||||
|
||||
```shell
|
||||
$ base64 --decode <em>ENCODED OUTPUT</em>
|
||||
```
|
||||
@@ -1,14 +0,0 @@
|
||||
---
|
||||
title: Configuring authentication and provisioning with your identity provider
|
||||
intro: You can configure user authentication and provisioning by integrating with an identity provider (IdP) that supports SAML single sign-on (SSO) and SCIM.
|
||||
versions:
|
||||
ghae: '*'
|
||||
redirect_from:
|
||||
- /admin/authentication/configuring-authentication-and-provisioning-with-your-identity-provider
|
||||
children:
|
||||
- /configuring-authentication-and-provisioning-for-your-enterprise-using-azure-ad
|
||||
- /configuring-authentication-and-provisioning-for-your-enterprise-using-okta
|
||||
- /mapping-okta-groups-to-teams
|
||||
shortTitle: Use an IdP for SSO & SCIM
|
||||
---
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Identity and access management
|
||||
intro: You can configure how users access your enterprise.
|
||||
intro: You can configure how people access {% ifversion ghec or ghae %}your enterprise on {% data variables.product.product_name %}{% elsif ghes %}{% data variables.product.product_location %}{% endif %}.
|
||||
redirect_from:
|
||||
- /enterprise/admin/authentication
|
||||
- /admin/authentication
|
||||
@@ -14,10 +14,12 @@ topics:
|
||||
- Enterprise
|
||||
- SSO
|
||||
children:
|
||||
- /authenticating-users-for-your-github-enterprise-server-instance
|
||||
- /managing-iam-for-your-enterprise
|
||||
- /managing-iam-with-enterprise-managed-users
|
||||
- /using-built-in-authentication
|
||||
- /using-cas-for-enterprise-iam
|
||||
- /using-ldap-for-enterprise-iam
|
||||
- /using-saml-for-enterprise-iam
|
||||
- /using-enterprise-managed-users-and-saml-for-iam
|
||||
- /managing-recovery-codes-for-your-enterprise
|
||||
- /configuring-authentication-and-provisioning-with-your-identity-provider
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,97 @@
|
||||
---
|
||||
title: About authentication for your enterprise
|
||||
shortTitle: About authentication
|
||||
intro: You {% ifversion ghae %}must configure SAML single sign-on (SSO) so people can{% else %}can choose how people{% endif %} authenticate to access {% ifversion ghec %}your enterprise's resources on {% data variables.product.product_name %}{% elsif ghes %}{% data variables.product.product_location %}{% elsif ghae %}your enterprise on {% data variables.product.product_name %}{% endif %}.
|
||||
versions:
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
ghae: '*'
|
||||
type: overview
|
||||
topics:
|
||||
- Accounts
|
||||
- Authentication
|
||||
- Enterprise
|
||||
- Identity
|
||||
- SSO
|
||||
---
|
||||
|
||||
## About authentication for your enterprise
|
||||
|
||||
{% ifversion ghec %}
|
||||
|
||||
Enterprise owners on {% data variables.product.product_name %} can control the requirements for authentication and access to the enterprise's resources. You can choose to allow members create and manage user accounts, or your enterprise can create and manage accounts for members. If you allow members to manage their own accounts, you can also configure SAML authentication to both increase security and centralize identity and access for the web applications that your team uses. If you choose to manage your members' user accounts, you must configure SAML authentication.
|
||||
|
||||
## Authentication methods for {% data variables.product.product_name %}
|
||||
|
||||
The following options are available for account management and authentication on {% data variables.product.product_name %}.
|
||||
|
||||
- [Authentication through {% data variables.product.product_location %}](#authentication-through-githubcom)
|
||||
- [Authentication through {% data variables.product.product_location %} with additional SAML access restriction](#authentication-through-githubcom-with-additional-saml-access-restriction)
|
||||
- [Authentication with {% data variables.product.prodname_emus %} and SAML SSO](#authentication-with-enterprise-managed-users-and-saml-sso)
|
||||
|
||||
### Authentication through {% data variables.product.product_location %}
|
||||
|
||||
By default, each member must create a personal account on {% data variables.product.product_location %}. You grant access to your enterprise, and the member can access your enterprise's resources after signing into the account on {% data variables.product.product_location %}. The member manages the account, and can contribute to other enterprises, organizations, and repositories on {% data variables.product.product_location %}.
|
||||
|
||||
### Authentication through {% data variables.product.product_location %} with additional SAML access restriction
|
||||
|
||||
If you configure additional SAML access restriction, each member must create and manage a personal account on {% data variables.product.product_location %}. You grant access to your enterprise, and the member can access your enterprise's resources after both signing into the account on {% data variables.product.product_location %} and successfully authenticating with your SAML identity provider (IdP). The member can contribute to other enterprises, organizations, and repositories on {% data variables.product.product_location %} using their personal account. For more information about requiring SAML authentication for all access your enterprise's resources, see "[About SAML for enterprise IAM](/admin/identity-and-access-management/using-saml-for-enterprise-iam/about-saml-for-enterprise-iam)."
|
||||
|
||||
If you use a standalone organization with {% data variables.product.product_name %}, or if you don't want to use SAML authentication for every organization in your enterprise, you can configure SAML for an individual organization. For more information, see "[About identity and access management with SAML single sign-on](/organizations/managing-saml-single-sign-on-for-your-organization/about-identity-and-access-management-with-saml-single-sign-on)."
|
||||
|
||||
### Authentication with {% data variables.product.prodname_emus %} and SAML SSO
|
||||
|
||||
If you need more control of the accounts for your enterprise members on {% data variables.product.product_location %}, you can use {% data variables.product.prodname_emus %}. With {% data variables.product.prodname_emus %}, you provision and manage accounts for your enterprise members on {% data variables.product.product_location %} using your IdP. Each member signs into an account that you create, and your enterprise manages the account. Contributions to the rest of {% data variables.product.prodname_dotcom_the_website %} are restricted. For more information, see "[About {% data variables.product.prodname_emus %}](/admin/identity-and-access-management/using-enterprise-managed-users-and-saml-for-iam/about-enterprise-managed-users)."
|
||||
|
||||
{% elsif ghes %}
|
||||
|
||||
Site administrators can decide how people authenticate to access a {% data variables.product.product_name %} instance. You can use {% data variables.product.product_name %}'s built-in authentication, or, if you want to centralize identity and access management for the web applications that your team uses, you can configure an external authentication method.
|
||||
|
||||
## Authentication methods for {% data variables.product.product_name %}
|
||||
|
||||
The following authentication methods are available for {% data variables.product.product_name %}.
|
||||
|
||||
- [Built-in authentication](#built-in-authentication)
|
||||
- [External authentication](#external-authentication)
|
||||
|
||||
### Built-in authentication
|
||||
|
||||
{% data reusables.enterprise_user_management.built-in-authentication-new-accounts %} To access your instance, people authenticate with the credentials for the account. For more information, see "[Configuring built-in authentication](/admin/identity-and-access-management/using-built-in-authentication/configuring-built-in-authentication)."
|
||||
|
||||
### External authentication
|
||||
|
||||
If you use an external directory or identity provider (IdP) to centralize access to multiple web applications, you may be able to configure external authentication for {% data variables.product.product_location %}. For more information, see the following.
|
||||
|
||||
- "[Using CAS for enterprise IAM](/admin/identity-and-access-management/using-cas-for-enterprise-iam)"
|
||||
- "[Using LDAP for enterprise IAM](/admin/identity-and-access-management/using-ldap-for-enterprise-iam)"
|
||||
- "[Using SAML for enterprise IAM](/admin/identity-and-access-management/using-saml-for-enterprise-iam)"
|
||||
|
||||
If you choose to use external authentication, you can also configure fallback authentication for people who don't have an account on your external authentication provider. For example, you may want to grant access to a contractor or machine user. For more information, see "[Allowing built-in authentication for users outside your provider](/admin/identity-and-access-management/managing-iam-for-your-enterprise/allowing-built-in-authentication-for-users-outside-your-provider)."
|
||||
|
||||
{% elsif ghae %}
|
||||
|
||||
{% data variables.product.product_name %} uses SAML SSO for authentication. Enterprise owners must configure SAML SSO with a SAML identity provider (IdP) during initialization. For more information, see "[About SAML for enterprise IAM](/admin/identity-and-access-management/using-saml-for-enterprise-iam/about-saml-for-enterprise-iam)."
|
||||
|
||||
{% endif %}
|
||||
|
||||
## About access control
|
||||
|
||||
{% ifversion ghec or ghae %}Members of your enterprise{% elsif ghes %}People with access to {% data variables.product.product_location %}{% endif %} can manage access to {% ifversion ghec %}your enterprise's resources{% elsif ghae %}your enterprise{% elsif ghes %}resources on your instance{% endif %} by using organization membership, teams, and roles. For more information, see the following.
|
||||
|
||||
{%- ifversion ghec %}
|
||||
- "[Inviting users to join your organization](/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization)"
|
||||
{%- elsif ghes or ghae %}
|
||||
- "[Adding people to your organization](/organizations/managing-membership-in-your-organization/adding-people-to-your-organization)"
|
||||
{%- endif %}
|
||||
- "[Roles in an organization](/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization)"
|
||||
- "[About teams](/organizations/organizing-members-into-teams/about-teams)"
|
||||
- "[Repository roles for an organization](/organizations/managing-access-to-your-organizations-repositories/repository-roles-for-an-organization)"
|
||||
- "[Permission levels for a user account repository](/account-and-profile/setting-up-and-managing-your-github-user-account/managing-user-account-settings/permission-levels-for-a-user-account-repository)"
|
||||
|
||||
## Further reading
|
||||
|
||||
- "[Types of {% data variables.product.company_short %} accounts](/get-started/learning-about-github/types-of-github-accounts)"
|
||||
- "[About enterprise accounts](/admin/overview/about-enterprise-accounts)"
|
||||
{%- ifversion ghec %}
|
||||
- "[Can I create accounts for people in my organization?](/organizations/managing-membership-in-your-organization/can-i-create-accounts-for-people-in-my-organization)"
|
||||
{% endif %}
|
||||
@@ -1,11 +1,12 @@
|
||||
---
|
||||
title: Allowing built-in authentication for users outside your identity provider
|
||||
intro: 'You can configure built-in authentication to authenticate users who don''t have access to your identity provider that uses LDAP, SAML, or CAS.'
|
||||
title: Allowing built-in authentication for users outside your provider
|
||||
intro: "You can configure fallback authentication to allow built-in authentication for people who don't have an account on your CAS, LDAP, or SAML authentication provider."
|
||||
redirect_from:
|
||||
- /enterprise/admin/user-management/allowing-built-in-authentication-for-users-outside-your-identity-provider
|
||||
- /enterprise/admin/authentication/allowing-built-in-authentication-for-users-outside-your-identity-provider
|
||||
- /admin/authentication/allowing-built-in-authentication-for-users-outside-your-identity-provider
|
||||
- /enterprise/admin/authentication/authenticating-users-for-your-github-enterprise-server-instance/allowing-built-in-authentication-for-users-outside-your-identity-provider
|
||||
- /admin/identity-and-access-management/authenticating-users-for-your-github-enterprise-server-instance/allowing-built-in-authentication-for-users-outside-your-identity-provider
|
||||
versions:
|
||||
ghes: '*'
|
||||
type: how_to
|
||||
@@ -14,15 +15,16 @@ topics:
|
||||
- Authentication
|
||||
- Enterprise
|
||||
- Identity
|
||||
shortTitle: Authentication outside IdP
|
||||
shortTitle: Fallback authentication
|
||||
---
|
||||
## About built-in authentication for users outside your identity provider
|
||||
|
||||
You can use built-in authentication for outside users when you are unable to add specific accounts to your identity provider (IdP), such as accounts for contractors or machine users. You can also use built-in authentication to access a fallback account if the identity provider is unavailable.
|
||||
## About built-in authentication for users outside your provider
|
||||
|
||||
After built-in authentication is configured and a user successfully authenticates with SAML or CAS, they will no longer have the option to authenticate with a username and password. If a user successfully authenticates with LDAP, the credentials are no longer considered internal.
|
||||
By default, when you enable external authentication for {% data variables.product.product_name %}, built-in authentication is disabled for your instance. For more information, see "[About authentication for your enterprise](/admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise#external-authentication)."
|
||||
|
||||
Built-in authentication for a specific IdP is disabled by default.
|
||||
If you're unable to add specific accounts to your external authentication provider, such as accounts for contractors or machine users, you can configure fallback authentication. Fallback authentication allows built-in authentication for outside users and to access a fallback account if your authentication provider is unavailable.
|
||||
|
||||
If you configure built-in authentication and a person successfully authenticates with SAML or CAS, the person will no longer have the option to authenticate with a username and password. If a user successfully authenticates with LDAP, the credentials are no longer considered internal.
|
||||
|
||||
{% warning %}
|
||||
|
||||
@@ -30,7 +32,7 @@ Built-in authentication for a specific IdP is disabled by default.
|
||||
|
||||
{% endwarning %}
|
||||
|
||||
## Configuring built-in authentication for users outside your identity provider
|
||||
## Configuring built-in authentication for users outside your provider
|
||||
|
||||
{% data reusables.enterprise_site_admin_settings.access-settings %}
|
||||
{% data reusables.enterprise_site_admin_settings.management-console %}
|
||||
@@ -44,7 +46,7 @@ Built-in authentication for a specific IdP is disabled by default.
|
||||
{% data reusables.enterprise_user_management.two_factor_auth_header %}
|
||||
{% data reusables.enterprise_user_management.2fa_is_available %}
|
||||
|
||||
## Inviting users outside your identity provider to authenticate to your instance
|
||||
## Inviting users outside your provider to authenticate to your instance
|
||||
|
||||
When a user accepts the invitation, they can use their username and password to sign in rather than signing in through the IdP.
|
||||
|
||||
@@ -55,6 +57,6 @@ When a user accepts the invitation, they can use their username and password to
|
||||
|
||||
## Further reading
|
||||
|
||||
- "[Using LDAP](/enterprise/admin/authentication/using-ldap)"
|
||||
- "[Using SAML](/enterprise/{{ currentVersion }}/admin/guides/user-management/using-saml)"
|
||||
- "[Using CAS](/enterprise/{{ currentVersion }}/admin/guides/user-management/using-cas)"
|
||||
- "[Using CAS for enterprise IAM](/admin/identity-and-access-management/using-cas-for-enterprise-iam)"
|
||||
- "[Using LDAP for enterprise IAM](/admin/identity-and-access-management/using-ldap-for-enterprise-iam)"
|
||||
- "[Using SAML for enterprise IAM](/admin/identity-and-access-management/using-saml-for-enterprise-iam)"
|
||||
@@ -6,6 +6,7 @@ redirect_from:
|
||||
- /enterprise/admin/authentication/changing-authentication-methods
|
||||
- /admin/authentication/changing-authentication-methods
|
||||
- /enterprise/admin/authentication/authenticating-users-for-your-github-enterprise-server-instance/changing-authentication-methods
|
||||
- /admin/identity-and-access-management/authenticating-users-for-your-github-enterprise-server-instance/changing-authentication-methods
|
||||
versions:
|
||||
ghes: '*'
|
||||
type: overview
|
||||
@@ -38,4 +39,4 @@ Other issues you should take into consideration include:
|
||||
|
||||
* **Two-factor authentication:** {% data reusables.enterprise_user_management.external_auth_disables_2fa %}
|
||||
|
||||
* **Built-in authentication for users outside your identity provider:** You can invite users to authenticate to {% data variables.product.product_location %} without adding them to your identity provider. For more information, see "[Allowing built-in authentication for users outside your identity provider](/enterprise/{{ currentVersion }}/admin/guides/user-management/allowing-built-in-authentication-for-users-outside-your-identity-provider)."
|
||||
* **Fallback authentication for users with no account on your external authentication provider:** You can invite users to authenticate to {% data variables.product.product_location %} without adding them to your identity provider. For more information, see "[Allowing built-in authentication for users outside your provider](/admin/identity-and-access-management/managing-iam-for-your-enterprise/allowing-built-in-authentication-for-users-outside-your-provider)."
|
||||
@@ -1,20 +1,35 @@
|
||||
---
|
||||
title: Managing IAM for your enterprise
|
||||
shortTitle: IAM for your enterprise
|
||||
intro: 'You can centrally manage {% ifversion ghae %}accounts and {% endif %}access to your {% ifversion ghae %}enterprise{% elsif ghec %}enterprise''s resources{% endif %} on {% data variables.product.product_name %} with SAML single sign-on (SSO) and System for Cross-domain Identity Management (SCIM).'
|
||||
intro: |
|
||||
{%- ifversion ghec %}
|
||||
You can invite existing personal accounts on {% data variables.product.product_location %} to be members of your enterprise, and you can optionally enable SAML single sign-on (SSO) to centrally manage access. Alternatively, you can use {% data variables.product.prodname_emus %} with SAML SSO to create and control the accounts of your enterprise members.
|
||||
{%- elsif ghes %}
|
||||
You can use {% data variables.product.product_name %}'s built-in authentication, or you can centrally manage authentication and access to your instance with CAS, LDAP, or SAML.
|
||||
{%- elsif ghae %}
|
||||
You must use SAML single sign-on (SSO) to centrally manage authentication and access to your enterprise on {% data variables.product.product_name %}. Optionally, you can use System for Cross-domain Identity Management (SCIM) to automatically provision accounts and access on {% data variables.product.product_name %} when you make changes on your identity provider (IdP).
|
||||
{%- endif %}
|
||||
redirect_from:
|
||||
- /enterprise/admin/categories/authentication
|
||||
- /enterprise/admin/guides/installation/user-authentication
|
||||
- /enterprise/admin/articles/inviting-users
|
||||
- /enterprise/admin/guides/migrations/authenticating-users-for-your-github-enterprise-instance
|
||||
- /enterprise/admin/user-management/authenticating-users-for-your-github-enterprise-server-instance
|
||||
- /enterprise/admin/authentication/authenticating-users-for-your-github-enterprise-server-instance
|
||||
- /admin/identity-and-access-management/authenticating-users-for-your-github-enterprise-server-instance
|
||||
versions:
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
ghae: '*'
|
||||
redirect_from:
|
||||
- /github/setting-up-and-managing-your-enterprise/configuring-identity-and-access-management-for-your-enterprise-account
|
||||
- /admin/authentication/managing-identity-and-access-for-your-enterprise
|
||||
topics:
|
||||
- Accounts
|
||||
- Authentication
|
||||
- Enterprise
|
||||
- Identity
|
||||
children:
|
||||
- /about-identity-and-access-management-for-your-enterprise
|
||||
- /configuring-saml-single-sign-on-for-your-enterprise
|
||||
- /configuring-user-provisioning-for-your-enterprise
|
||||
- /managing-team-synchronization-for-organizations-in-your-enterprise
|
||||
- /configuring-saml-single-sign-on-for-your-enterprise-using-okta
|
||||
- /switching-your-saml-configuration-from-an-organization-to-an-enterprise-account
|
||||
- /about-authentication-for-your-enterprise
|
||||
- /username-considerations-for-external-authentication
|
||||
- /changing-authentication-methods
|
||||
- /allowing-built-in-authentication-for-users-outside-your-provider
|
||||
shortTitle: Manage IAM for your enterprise
|
||||
---
|
||||
|
||||
{% data reusables.enterprise-accounts.emu-saml-note %}
|
||||
|
||||
@@ -0,0 +1,81 @@
|
||||
---
|
||||
title: Username considerations for external authentication
|
||||
shortTitle: Username considerations
|
||||
intro: "{% ifversion ghes or ghec %}When you use {% ifversion ghes %}CAS, LDAP, or SAML for authentication{% elsif ghec %}{% data variables.product.prodname_emus %}{% endif %}, {% endif %}{% data variables.product.product_name %} follows certain rules to determine the username for each user account {% ifversion ghec or ghae %}in your enterprise{% elsif ghes %}on your instance{% endif %}."
|
||||
miniTocMaxHeadingLevel: 3
|
||||
versions:
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
ghae: '*'
|
||||
type: reference
|
||||
topics:
|
||||
- Accounts
|
||||
- Authentication
|
||||
- Enterprise
|
||||
- Identity
|
||||
- SSO
|
||||
---
|
||||
|
||||
## About usernames with external authentication
|
||||
|
||||
{% ifversion ghes %}
|
||||
|
||||
You can configure external authentication for {% data variables.product.product_name %} using CAS, LDAP, or SAML. For more information, see "[About authentication for your enterprise](/admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise#authentication-methods-for-github-enterprise-server)."
|
||||
|
||||
When you use external authentication, {% data variables.product.product_location %} automatically creates a username for each person when the person signs into {% data variables.product.product_location %} through your external authentication system for the first time.
|
||||
|
||||
{% elsif ghec %}
|
||||
|
||||
If you use an enterprise with {% data variables.product.prodname_emus %}, members of your enterprise authenticate to access {% data variables.product.prodname_dotcom %} through your SAML identity provider (IdP). For more information, see "[About authentication for your enterprise](/admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise#authentication-methods-for-github-enterprise-server)."
|
||||
|
||||
{% data variables.product.product_name %} automatically creates a username for each person when the person signs in through your IdP for the first time.
|
||||
|
||||
{% elsif ghae %}
|
||||
|
||||
{% data variables.product.product_name %} uses SAML SSO for authentication, and automatically creates a username for each person when the person signs in through your identity provider (IdP) for the first time.
|
||||
|
||||
{% endif %}
|
||||
|
||||
## About username normalization
|
||||
|
||||
Usernames for user accounts on {% ifversion ghes or ghae %}{% data variables.product.product_name %}{% elsif ghec %}{% data variables.product.prodname_dotcom_the_website %}{% endif %} can only contain alphanumeric characters and dashes (`-`).
|
||||
|
||||
{% ifversion ghec or ghes %}When you configure {% ifversion ghes %}CAS, LDAP, or {% endif %}SAML authentication, {% endif %}{% data variables.product.product_name %} uses an identifier from the user account on your {% ifversion ghes %}external authentication provider{% elsif ghec or ghae %}IdP{% endif %} to determine the username for the corresponding user account on {% ifversion ghes or ghae %}{% data variables.product.product_name %}{% elsif ghec %}{% data variables.product.prodname_dotcom_the_website %}{% endif %}. If the identifier for the account on your provider includes unsupported characters, {% data variables.product.product_name %} will normalize the username per the following rules.
|
||||
|
||||
1. {% data variables.product.product_name %} will normalize any non-alphanumeric character in your account's username into a dash. For example, a username of `mona.the.octocat` will be normalized to `mona-the-octocat`. Note that normalized usernames also can't start or end with a dash. They also can't contain two consecutive dashes.
|
||||
|
||||
1. Usernames created from email addresses are created from the normalized characters that precede the `@` character.
|
||||
|
||||
1. If multiple accounts are normalized into the same {% data variables.product.product_name %} username, only the first user account is created. Subsequent users with the same username won't be able to sign in.
|
||||
|
||||
### Examples of username normalization
|
||||
|
||||
| Identifier on provider | Normalized username for {% data variables.product.product_location %} | Result |
|
||||
| :- | :- | :- |
|
||||
| The.Octocat | `the-octocat` | This username is created successfully. |
|
||||
| !The.Octocat | `-the-octocat` | This username is not created, because it starts with a dash. |
|
||||
| The.Octocat! | `the-octocat-` | This username is not created, because it ends with a dash. |
|
||||
| The!!Octocat | `the--octocat` | This username is not created, because it contains two consecutive dashes. |
|
||||
| The!Octocat | `the-octocat` | This username is not created. Although the normalized username is valid, it already exists. |
|
||||
| The.Octocat@example.com | `the-octocat` | This username is not created. Although the normalized username is valid, it already exists. |
|
||||
|
||||
### About username normalization with SAML
|
||||
|
||||
{% ifversion ghec or ghes %}If you {% ifversion ghec %}use an enterprise with {% data variables.product.prodname_emus %}, you must use SAML authentication. {% else %}configure SAML authentication for {% data variables.product.product_location %}, {% endif %}{% endif %}{% data variables.product.product_name %} determines each person's username by one of the following assertions in the SAML response, ordered by priority.
|
||||
|
||||
1. The custom `username` attribute, if defined and present
|
||||
1. An `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` assertion, if present
|
||||
1. An `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` assertion, if present
|
||||
1. The `NameID` element
|
||||
|
||||
{% data variables.product.product_name %} requires the `NameID` element even if other attributes are present. For more information, see "[SAML configuration reference](/admin/identity-and-access-management/using-saml-for-enterprise-iam/saml-configuration-reference#saml-attributes)."
|
||||
|
||||
{% data variables.product.product_name %} creates a mapping between the `NameID` from the IdP and the username {% ifversion ghec or ghae %}in{% elsif ghes %}on{% endif %} {% data variables.product.product_location %}, so the `NameID` should be persistent, unique, and not subject to change for the lifecycle of the user.
|
||||
|
||||
{% ifversion ghes %}
|
||||
{% note %}
|
||||
|
||||
**Note**: If the `NameID` for a user does change on the IdP, the person will see an error message when {% ifversion ghec %}authenticating through your IdP to access your resources on{% else %}signing into{% endif} {% data variables.product.product_location %}. To restore the person's access, you'll need to update the user account's `NameID` mapping. For more information, see "[Updating a user's SAML `NameID`](/admin/identity-and-access-management/using-saml-for-enterprise-iam/updating-a-users-saml-nameid)."
|
||||
|
||||
{% endnote %}
|
||||
{% endif %}
|
||||
@@ -1,11 +1,13 @@
|
||||
---
|
||||
title: Using built-in authentication
|
||||
intro: 'When you use the default authentication method, all authentication details are stored within {% data variables.product.product_location %}. Built-in authentication is the default method if you don’t already have an established authentication provider, such as LDAP, SAML, or CAS.'
|
||||
title: Configuring built-in authentication
|
||||
intro: 'When you use the default authentication method, all authentication details are stored on {% data variables.product.product_location %}.'
|
||||
permissions: Site administrators can configure authentication for a {% data variables.product.product_name %} instance.
|
||||
redirect_from:
|
||||
- /enterprise/admin/user-management/using-built-in-authentication
|
||||
- /enterprise/admin/authentication/using-built-in-authentication
|
||||
- /admin/authentication/using-built-in-authentication
|
||||
- /enterprise/admin/authentication/authenticating-users-for-your-github-enterprise-server-instance/using-built-in-authentication
|
||||
- /admin/identity-and-access-management/authenticating-users-for-your-github-enterprise-server-instance/using-built-in-authentication
|
||||
versions:
|
||||
ghes: '*'
|
||||
type: how_to
|
||||
@@ -14,9 +16,16 @@ topics:
|
||||
- Authentication
|
||||
- Enterprise
|
||||
- Identity
|
||||
shortTitle: Use built-in authentication
|
||||
shortTitle: Configure built-in authentication
|
||||
---
|
||||
You can create custom messages that users will see on the sign in and sign out pages. For more information, see "[Customizing user messages on your instance](/enterprise/admin/user-management/customizing-user-messages-on-your-instance)."
|
||||
|
||||
## About built-in authentication
|
||||
|
||||
By default, {% data variables.product.product_name %} uses built-in authentication. Each person creates a user account on {% data variables.product.product_location %} from an invitation or by signing up, and then authenticates with the credentials for the account to access your instance. Your {% data variables.product.product_name %} instance stores the authentication information for the account.
|
||||
|
||||
You can prevent unauthenticated people from creating new user accounts on your instance. For more information, see "[Disabling unauthenticated sign-ups](/admin/identity-and-access-management/using-built-in-authentication/disabling-unauthenticated-sign-ups)."
|
||||
|
||||
{% data reusables.enterprise_user_management.alternatively-enable-external-authentication %}
|
||||
|
||||
## Configuring built-in authentication
|
||||
|
||||
@@ -37,17 +46,11 @@ Once your instance has been created, you'll need to create your own admin accoun
|
||||
|
||||
{% data reusables.enterprise_site_admin_settings.sign-in %}
|
||||
|
||||
## Inviting users
|
||||
## Next steps
|
||||
|
||||
{% data reusables.enterprise_site_admin_settings.access-settings %}
|
||||
{% data reusables.enterprise_site_admin_settings.invite-user-sidebar-tab %}
|
||||
{% data reusables.enterprise_site_admin_settings.invite-user-reset-link %}
|
||||
<a name="inviting-users"></a>
|
||||
|
||||
{% tip %}
|
||||
|
||||
**Tip:** If email for notifications is configured on the appliance, an invite will also be sent to the provided email address.
|
||||
|
||||
{% endtip %}
|
||||
After you configure built-in authentication and create your administrative account, you can invite people to create accounts and use your instance. For more information, see "[Inviting people to use your instance](/admin/identity-and-access-management/using-built-in-authentication/inviting-people-to-use-your-instance)."
|
||||
|
||||
## Further reading
|
||||
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: Disabling unauthenticated sign-ups
|
||||
redirect_from:
|
||||
- /enterprise/admin/articles/disabling-sign-ups
|
||||
- /enterprise/admin/user-management/disabling-unauthenticated-sign-ups
|
||||
- /enterprise/admin/authentication/disabling-unauthenticated-sign-ups
|
||||
- /admin/authentication/disabling-unauthenticated-sign-ups
|
||||
- /enterprise/admin/authentication/authenticating-users-for-your-github-enterprise-server-instance/disabling-unauthenticated-sign-ups
|
||||
- /admin/identity-and-access-management/authenticating-users-for-your-github-enterprise-server-instance/disabling-unauthenticated-sign-ups
|
||||
intro: "If you're using built-in authentication for {% data variables.product.product_location %}, you can block unauthenticated people from creating new user accounts on your instance."
|
||||
permissions: Site administrators can disable unauthenticated sign-ups on a {% data variables.product.product_name %} instance.
|
||||
versions:
|
||||
ghes: '*'
|
||||
type: how_to
|
||||
topics:
|
||||
- Accounts
|
||||
- Authentication
|
||||
- Enterprise
|
||||
- Identity
|
||||
shortTitle: Block unauthenticated sign-up
|
||||
---
|
||||
|
||||
## About unauthenticated sign-ups
|
||||
|
||||
{% data reusables.enterprise_user_management.built-in-authentication-new-accounts %} {% data reusables.enterprise_user_management.unauthenticated-sign-ups %} You can disable unauthenticated sign-ups and require an invitation to create a new user account on your instance.
|
||||
|
||||
{% data reusables.enterprise_user_management.alternatively-enable-external-authentication %}
|
||||
|
||||
## Disabling unauthenticated sign-ups
|
||||
|
||||
{% data reusables.enterprise_site_admin_settings.access-settings %}
|
||||
{% data reusables.enterprise_site_admin_settings.management-console %}
|
||||
{% data reusables.enterprise_management_console.privacy %}
|
||||
3. Unselect **Enable sign-up**.
|
||||
|
||||
{% data reusables.enterprise_management_console.save-settings %}
|
||||
@@ -0,0 +1,16 @@
|
||||
---
|
||||
title: Using built-in authentication
|
||||
shortTitle: Built-in authentication
|
||||
intro: "If you don't use a centralized, external system for your users' identity, you can use built-in authentication to allow {% data variables.product.prodname_ghe_server %} to manage accounts and perform local authentication."
|
||||
versions:
|
||||
ghes: '*'
|
||||
topics:
|
||||
- Accounts
|
||||
- Authentication
|
||||
- Enterprise
|
||||
children:
|
||||
- /configuring-built-in-authentication
|
||||
- /inviting-people-to-use-your-instance
|
||||
- /disabling-unauthenticated-sign-ups
|
||||
---
|
||||
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: Inviting people to use your instance
|
||||
intro: When you use built-in authentication for {% data variables.product.product_name %}, you can invite people by email address to create a user account on your instance.
|
||||
versions:
|
||||
ghes: '*'
|
||||
permissions: Enterprise owners can invite people to create a user account on a {% data variables.product.product_name %} instance.
|
||||
type: how_to
|
||||
topics:
|
||||
- Accounts
|
||||
- Authentication
|
||||
- Enterprise
|
||||
- Identity
|
||||
shortTitle: Invite people
|
||||
---
|
||||
|
||||
## About invitations for new users
|
||||
|
||||
{% data reusables.enterprise_user_management.built-in-authentication-new-accounts %} {% data reusables.enterprise_user_management.unauthenticated-sign-ups %}
|
||||
|
||||
You can disable unauthenticated sign-ups and require an invitation to create a new user account on your instance. For more information, see "[Disabling unauthenticated sign-ups](/admin/identity-and-access-management/using-built-in-authentication/disabling-unauthenticated-sign-ups)."
|
||||
|
||||
{% data reusables.enterprise_user_management.alternatively-enable-external-authentication %}
|
||||
|
||||
## Inviting people to create a user account
|
||||
|
||||
{% data reusables.enterprise_site_admin_settings.access-settings %}
|
||||
{% data reusables.enterprise_site_admin_settings.invite-user-sidebar-tab %}
|
||||
{% data reusables.enterprise_site_admin_settings.invite-user-reset-link %}
|
||||
|
||||
If you've configured email for notifications on {% data variables.product.product_location %}, your instance will send the invitation to the provided email address. For more information, see "[Configuring email for notifications](/admin/configuration/configuring-your-enterprise/configuring-email-for-notifications)."
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
title: Using CAS for enterprise IAM
|
||||
shortTitle: CAS for enterprise IAM
|
||||
intro: 'You can centrally manage accounts and access to {% data variables.product.product_location %} by integrating with your existing CAS identity provider (IdP).'
|
||||
versions:
|
||||
ghes: '*'
|
||||
children:
|
||||
- /using-cas
|
||||
---
|
||||
|
||||
@@ -0,0 +1,56 @@
|
||||
---
|
||||
title: Using CAS
|
||||
redirect_from:
|
||||
- /enterprise/admin/articles/configuring-cas-authentication
|
||||
- /enterprise/admin/articles/about-cas-authentication
|
||||
- /enterprise/admin/user-management/using-cas
|
||||
- /enterprise/admin/authentication/using-cas
|
||||
- /admin/authentication/using-cas
|
||||
- /enterprise/admin/authentication/authenticating-users-for-your-github-enterprise-server-instance/using-cas
|
||||
- /admin/identity-and-access-management/authenticating-users-for-your-github-enterprise-server-instance/using-cas
|
||||
intro: 'If you use Central Authentication Service (CAS) to centralize access to multiple web applications, you can integrate {% data variables.product.product_name %} by configuring CAS authentication for your instance.'
|
||||
versions:
|
||||
ghes: '*'
|
||||
type: how_to
|
||||
topics:
|
||||
- Accounts
|
||||
- Authentication
|
||||
- Enterprise
|
||||
- Identity
|
||||
- SSO
|
||||
---
|
||||
|
||||
## About CAS authentication for {% data variables.product.product_name %}
|
||||
|
||||
CAS is a single sign-on (SSO) protocol that centralizes authentication to multiple web applications. For more information, see "[Central Authentication Service](https://en.wikipedia.org/wiki/Central_Authentication_Service)" on Wikipedia.
|
||||
|
||||
After you configure CAS, people who use {% data variables.product.product_location %} must use a personal access token to authenticate API or Git requests over HTTP(S). CAS credentials cannot be used to authenticate these requests. For more information, see "[Creating a personal access token](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)."
|
||||
|
||||
If you configure CAS, people with accounts on your identity provider (IdP) do not consume a user license until the person signs into {% data variables.product.product_location %}.
|
||||
|
||||
{% data reusables.enterprise_user_management.built-in-authentication %}
|
||||
|
||||
## Username considerations with CAS
|
||||
|
||||
{% data reusables.enterprise_user_management.consider-usernames-for-external-authentication %} For more information, see "[Username considerations for external authentication](/admin/identity-and-access-management/managing-iam-for-your-enterprise/username-considerations-for-external-authentication)."
|
||||
|
||||
## CAS attributes
|
||||
|
||||
The following attributes are available.
|
||||
|
||||
| Attribute name | Type | Description |
|
||||
|--------------------------|----------|-------------|
|
||||
| `username` | Required | The {% data variables.product.prodname_ghe_server %} username. |
|
||||
|
||||
## Configuring CAS
|
||||
|
||||
{% data reusables.enterprise_site_admin_settings.access-settings %}
|
||||
{% data reusables.enterprise_site_admin_settings.management-console %}
|
||||
{% data reusables.enterprise_management_console.authentication %}
|
||||
3. Select **CAS**.
|
||||
|
||||
|
||||
4. {% data reusables.enterprise_user_management.built-in-authentication-option %}
|
||||
|
||||
|
||||
5. In the **Server URL** field, type the full URL of your CAS server. If your CAS server uses a certificate that can't be validated by {% data variables.product.prodname_ghe_server %}, you can use the `ghe-ssl-ca-certificate-install` command to install it as a trusted certificate. For more information, see "[Command-line utilities](/admin/configuration/configuring-your-enterprise/command-line-utilities#ghe-ssl-ca-certificate-install)."
|
||||
@@ -7,6 +7,7 @@ redirect_from:
|
||||
- /early-access/github/articles/get-started-with-managed-users-for-your-enterprise
|
||||
- /github/setting-up-and-managing-your-enterprise/managing-your-enterprise-users-with-your-identity-provider/about-enterprise-managed-users
|
||||
- /admin/authentication/managing-your-enterprise-users-with-your-identity-provider/about-enterprise-managed-users
|
||||
- /admin/identity-and-access-management/managing-iam-with-enterprise-managed-users/about-enterprise-managed-users
|
||||
versions:
|
||||
ghec: '*'
|
||||
type: overview
|
||||
@@ -6,6 +6,7 @@ product: '{% data reusables.gated-features.emus %}'
|
||||
redirect_from:
|
||||
- /github/setting-up-and-managing-your-enterprise/managing-your-enterprise-users-with-your-identity-provider/configuring-saml-single-sign-on-for-enterprise-managed-users
|
||||
- /admin/authentication/managing-your-enterprise-users-with-your-identity-provider/configuring-saml-single-sign-on-for-enterprise-managed-users
|
||||
- /admin/identity-and-access-management/managing-iam-with-enterprise-managed-users/configuring-saml-single-sign-on-for-enterprise-managed-users
|
||||
versions:
|
||||
ghec: '*'
|
||||
type: tutorial
|
||||
@@ -9,6 +9,7 @@ redirect_from:
|
||||
- /early-access/github/articles/configuring-provisioning-for-managed-users-with-okta
|
||||
- /github/setting-up-and-managing-your-enterprise/managing-your-enterprise-users-with-your-identity-provider/configuring-scim-provisioning-for-enterprise-managed-users-with-okta
|
||||
- /admin/authentication/managing-your-enterprise-users-with-your-identity-provider/configuring-scim-provisioning-for-enterprise-managed-users-with-okta
|
||||
- /admin/identity-and-access-management/managing-iam-with-enterprise-managed-users/configuring-scim-provisioning-for-enterprise-managed-users-with-okta
|
||||
type: tutorial
|
||||
topics:
|
||||
- Accounts
|
||||
@@ -6,6 +6,7 @@ product: '{% data reusables.gated-features.emus %}'
|
||||
redirect_from:
|
||||
- /github/setting-up-and-managing-your-enterprise/managing-your-enterprise-users-with-your-identity-provider/configuring-scim-provisioning-for-enterprise-managed-users
|
||||
- /admin/authentication/managing-your-enterprise-users-with-your-identity-provider/configuring-scim-provisioning-for-enterprise-managed-users
|
||||
- /admin/identity-and-access-management/managing-iam-with-enterprise-managed-users/configuring-scim-provisioning-for-enterprise-managed-users
|
||||
versions:
|
||||
ghec: '*'
|
||||
topics:
|
||||
@@ -1,11 +1,12 @@
|
||||
---
|
||||
title: Managing IAM with Enterprise Managed Users
|
||||
title: Using Enterprise Managed Users and SAML for IAM
|
||||
shortTitle: Enterprise Managed Users
|
||||
product: '{% data reusables.gated-features.emus %}'
|
||||
intro: You can manage identity and access with your identity provider and provision accounts that can only contribute to your enterprise.
|
||||
redirect_from:
|
||||
- /github/setting-up-and-managing-your-enterprise/managing-your-enterprise-users-with-your-identity-provider
|
||||
- /admin/authentication/managing-your-enterprise-users-with-your-identity-provider
|
||||
- /admin/identity-and-access-management/managing-iam-with-enterprise-managed-users
|
||||
versions:
|
||||
ghec: '*'
|
||||
topics:
|
||||
@@ -6,6 +6,7 @@ product: '{% data reusables.gated-features.emus %}'
|
||||
redirect_from:
|
||||
- /github/setting-up-and-managing-your-enterprise/managing-your-enterprise-users-with-your-identity-provider/managing-team-memberships-with-identity-provider-groups
|
||||
- /admin/authentication/managing-your-enterprise-users-with-your-identity-provider/managing-team-memberships-with-identity-provider-groups
|
||||
- /admin/identity-and-access-management/managing-iam-with-enterprise-managed-users/managing-team-memberships-with-identity-provider-groups
|
||||
versions:
|
||||
ghec: '*'
|
||||
type: how_to
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
title: Using LDAP for enterprise IAM
|
||||
shortTitle: LDAP for enterprise IAM
|
||||
intro: You can centrally manage accounts and access to {% data variables.product.product_location %} by integrating with your existing LDAP directory.
|
||||
versions:
|
||||
ghes: '*'
|
||||
children:
|
||||
- /using-ldap
|
||||
---
|
||||
|
||||
@@ -10,7 +10,8 @@ redirect_from:
|
||||
- /enterprise/admin/authentication/using-ldap
|
||||
- /admin/authentication/using-ldap
|
||||
- /enterprise/admin/authentication/authenticating-users-for-your-github-enterprise-server-instance/using-ldap
|
||||
intro: 'LDAP lets you authenticate {% data variables.product.prodname_ghe_server %} against your existing accounts and centrally manage repository access. LDAP is a popular application protocol for accessing and maintaining directory information services, and is one of the most common protocols used to integrate third-party software with large company user directories.'
|
||||
- /admin/identity-and-access-management/authenticating-users-for-your-github-enterprise-server-instance/using-ldap
|
||||
intro: If you use Lightweight Directory Access Protocol (LDAP) to centralize access across applications, you can integrate {% data variables.product.product_name %} by configuring LDAP authentication for your instance.
|
||||
versions:
|
||||
ghes: '*'
|
||||
type: how_to
|
||||
@@ -20,6 +21,13 @@ topics:
|
||||
- Enterprise
|
||||
- Identity
|
||||
---
|
||||
|
||||
## About LDAP authentication for {% data variables.product.product_name %}
|
||||
|
||||
LDAP is a popular application protocol for access and maintenance of directory information services, and is one of the most common protocols for integration of third-party software with large company user directories. For more information, see "[Lightweight Directory Access Protocol](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol)" on Wikipedia.
|
||||
|
||||
If you use an LDAP directory for centralized authentication, you can configure LDAP authentication for the people who use {% data variables.product.product_location %}.
|
||||
|
||||
{% data reusables.enterprise_user_management.built-in-authentication %}
|
||||
|
||||
## Supported LDAP services
|
||||
@@ -35,12 +43,7 @@ topics:
|
||||
|
||||
## Username considerations with LDAP
|
||||
|
||||
{% data reusables.enterprise_management_console.username_normalization %}
|
||||
|
||||
{% data reusables.enterprise_management_console.username_normalization_sample %}
|
||||
|
||||
{% data reusables.enterprise_user_management.two_factor_auth_header %}
|
||||
{% data reusables.enterprise_user_management.2fa_is_available %}
|
||||
{% data reusables.enterprise_user_management.consider-usernames-for-external-authentication %} For more information, see "[Username considerations for external authentication](/admin/identity-and-access-management/managing-iam-for-your-enterprise/username-considerations-for-external-authentication)."
|
||||
|
||||
## Configuring LDAP with {% data variables.product.product_location %}
|
||||
|
||||
@@ -1,9 +1,10 @@
|
||||
---
|
||||
title: About identity and access management for your enterprise
|
||||
shortTitle: About identity and access management
|
||||
intro: 'You can use SAML single sign-on (SSO) and System for Cross-domain Identity Management (SCIM) to centrally manage access {% ifversion ghec %}to organizations owned by your enterprise on {% data variables.product.prodname_dotcom_the_website %}{% endif %}{% ifversion ghae %}to {% data variables.product.product_location %}{% endif %}.'
|
||||
title: About SAML for enterprise IAM
|
||||
shortTitle: About SAML for IAM
|
||||
intro: 'You can use SAML single sign-on (SSO) {% ifversion ghec or ghae %}and System for Cross-domain Identity Management (SCIM) {% endif %}to centrally manage access {% ifversion ghec %}to organizations owned by your enterprise on {% data variables.product.prodname_dotcom_the_website %}{% elsif ghes %}to {% data variables.product.product_location %}{% elsif ghae %}to {% data variables.product.product_location %}{% endif %}.'
|
||||
versions:
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
ghae: '*'
|
||||
type: overview
|
||||
topics:
|
||||
@@ -19,13 +20,18 @@ redirect_from:
|
||||
- /github/setting-up-and-managing-your-enterprise/about-user-provisioning-for-organizations-in-your-enterprise-account
|
||||
- /github/setting-up-and-managing-your-enterprise/configuring-saml-single-sign-on-and-scim-for-your-enterprise-account-using-okta
|
||||
- /admin/authentication/managing-identity-and-access-for-your-enterprise/about-identity-and-access-management-for-your-enterprise
|
||||
- /admin/identity-and-access-management/managing-iam-for-your-enterprise/about-identity-and-access-management-for-your-enterprise
|
||||
- /admin/identity-and-access-management/using-saml-for-enterprise-iam/about-identity-and-access-management-for-your-enterprise
|
||||
---
|
||||
## About identity and access management for your enterprise
|
||||
|
||||
## About SAML SSO for {% ifversion ghec or ghae %}your enterprise on {% endif %}{% ifversion ghec or ghes %}{% data variables.product.product_location %}{% elsif ghae %}{% data variables.product.product_name %}{% endif %}
|
||||
|
||||
{% ifversion ghec %}
|
||||
|
||||
{% data reusables.saml.dotcom-saml-explanation %} {% data reusables.saml.about-saml-enterprise-accounts %} For more information, see "[Configuring SAML single sign-on for your enterprise](/admin/authentication/managing-identity-and-access-for-your-enterprise/configuring-saml-single-sign-on-for-your-enterprise)."
|
||||
|
||||
If your enterprise members manage their own personal accounts on {% data variables.product.product_location %}, you can configure SAML authentication as an additional access restriction for your enterprise or organization. Alternatively, you can provision and manage the accounts of your enterprise members on {% data variables.product.product_location %} by using an enterprise account with {% data variables.product.prodname_emus %} enabled. For more information, see "[About authentication for your enterprise](/admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise#authentication-methods-for-github-enterprise-cloud)."
|
||||
|
||||
{% data reusables.enterprise-accounts.about-recovery-codes %} For more information, see "[Managing recovery codes for your enterprise](/admin/identity-and-access-management/managing-recovery-codes-for-your-enterprise)."
|
||||
|
||||
After you enable SAML SSO, depending on the IdP you use, you may be able to enable additional identity and access management features. {% data reusables.scim.enterprise-account-scim %}
|
||||
@@ -40,18 +46,19 @@ If you use Azure AD as your IDP, you can use team synchronization to manage team
|
||||
|
||||
Configuring {% data variables.product.prodname_emus %} for SAML single-sign on and user provisioning involves following a different process than you would for an enterprise that isn't using {% data variables.product.prodname_managed_users %}. If your enterprise uses {% data variables.product.prodname_emus %}, see "[Configuring SAML single sign-on for Enterprise Managed Users](/github/setting-up-and-managing-your-enterprise/managing-your-enterprise-users-with-your-identity-provider/configuring-saml-single-sign-on-for-enterprise-managed-users)."
|
||||
|
||||
## Supported IdPs
|
||||
{% elsif ghes %}
|
||||
|
||||
We test and officially support the following IdPs. For SAML SSO, we offer limited support for all identity providers that implement the SAML 2.0 standard. For more information, see the [SAML Wiki](https://wiki.oasis-open.org/security) on the OASIS website.
|
||||
SAML SSO allows people to authenticate and access {% data variables.product.product_location %} through an external system for identity management.
|
||||
|
||||
IdP | SAML | Team synchronization |
|
||||
--- | :--: | :-------: |
|
||||
Active Directory Federation Services (AD FS) | {% octicon "check-circle-fill" aria-label= "The check icon" %} | |
|
||||
Azure Active Directory (Azure AD) | {% octicon "check-circle-fill" aria-label="The check icon" %} | {% octicon "check-circle-fill" aria-label="The check icon" %} |
|
||||
Okta | {% octicon "check-circle-fill" aria-label="The check icon" %} | |
|
||||
OneLogin | {% octicon "check-circle-fill" aria-label="The check icon" %} | |
|
||||
PingOne | {% octicon "check-circle-fill" aria-label="The check icon" %} | |
|
||||
Shibboleth | {% octicon "check-circle-fill" aria-label="The check icon" %} | |
|
||||
SAML is an XML-based standard for authentication and authorization. When you configure SAML for {% data variables.product.product_location %}, the external system for authentication is called an identity provider (IdP). Your instance acts as a SAML service provider (SP). For more information about the SAML standard, see [Security Assertion Markup Language](https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language) on Wikipedia.
|
||||
|
||||
For more information about the configuration of SAML SSO on {% data variables.product.product_name %}, see "[Configuring SAML single sign-on for your enterprise](/admin/identity-and-access-management/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise)."
|
||||
|
||||
{% data reusables.saml.saml-ghes-account-revocation %}
|
||||
|
||||
{% data reusables.enterprise_user_management.external_auth_disables_2fa %}
|
||||
|
||||
{% data reusables.enterprise_user_management.built-in-authentication %}
|
||||
|
||||
{% elsif ghae %}
|
||||
|
||||
@@ -63,17 +70,50 @@ After you configure the application for {% data variables.product.product_name %
|
||||
|
||||
To learn how to configure both authentication and user provisioning for {% data variables.product.product_location %} with your specific IdP, see "[Configuring authentication and provisioning with your identity provider](/admin/authentication/configuring-authentication-and-provisioning-with-your-identity-provider)."
|
||||
|
||||
{% endif %}
|
||||
|
||||
## Supported IdPs
|
||||
|
||||
{% ifversion ghec %}
|
||||
|
||||
We test and officially support the following IdPs. For SAML SSO, we offer limited support for all identity providers that implement the SAML 2.0 standard. For more information, see the [SAML Wiki](https://wiki.oasis-open.org/security) on the OASIS website.
|
||||
|
||||
IdP | SAML | Team synchronization |
|
||||
--- | :--: | :-------: |
|
||||
Active Directory Federation Services (AD FS) | {% octicon "check-circle-fill" aria-label= "The check icon" %} | |
|
||||
Azure Active Directory (Azure AD) | {% octicon "check-circle-fill" aria-label="The check icon" %} | {% octicon "check-circle-fill" aria-label="The check icon" %} |
|
||||
Okta | {% octicon "check-circle-fill" aria-label="The check icon" %} | |
|
||||
OneLogin | {% octicon "check-circle-fill" aria-label="The check icon" %} | |
|
||||
PingOne | {% octicon "check-circle-fill" aria-label="The check icon" %} | |
|
||||
Shibboleth | {% octicon "check-circle-fill" aria-label="The check icon" %} | |
|
||||
|
||||
{% elsif ghes %}
|
||||
|
||||
{% data reusables.saml.saml-supported-idps %}
|
||||
|
||||
{% ifversion ghes > 3.3 %}
|
||||
|
||||
If your IdP supports encrypted assertions, you can configure encrypted assertions on {% data variables.product.product_name %} for increased security during the authentication process.
|
||||
|
||||
{% endif %}
|
||||
|
||||
{% data reusables.saml.saml-single-logout-not-supported %}
|
||||
|
||||
{% elsif ghae %}
|
||||
|
||||
The following IdPs are officially supported for integration with {% data variables.product.prodname_ghe_managed %}.
|
||||
|
||||
{% data reusables.saml.okta-ae-sso-beta %}
|
||||
|
||||
{% data reusables.github-ae.saml-idp-table %}
|
||||
|
||||
{% endif %}
|
||||
|
||||
{% ifversion ghae %}
|
||||
|
||||
## Mapping {% data variables.product.prodname_ghe_managed %} teams to Okta groups
|
||||
|
||||
If you use Okta as your IdP, you can map your Okta groups to teams on {% data variables.product.prodname_ghe_managed %}. For more information, see "[Mapping Okta groups to teams](/admin/authentication/configuring-authentication-and-provisioning-with-your-identity-provider/mapping-okta-groups-to-teams)."
|
||||
If you use Okta as your IdP, you can map your Okta groups to teams on {% data variables.product.product_name %}. For more information, see "[Mapping Okta groups to teams](/admin/authentication/configuring-authentication-and-provisioning-with-your-identity-provider/mapping-okta-groups-to-teams)."
|
||||
|
||||
{% endif %}
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Configuring authentication and provisioning for your enterprise using Azure AD
|
||||
shortTitle: Configuring with Azure AD
|
||||
shortTitle: Configure with Azure AD
|
||||
intro: 'You can use a tenant in Azure Active Directory (Azure AD) as an identity provider (IdP) to centrally manage authentication and user provisioning for {% data variables.product.product_location %}.'
|
||||
permissions: 'Enterprise owners can configure authentication and provisioning for an enterprise on {% data variables.product.product_name %}.'
|
||||
versions:
|
||||
@@ -15,6 +15,7 @@ topics:
|
||||
redirect_from:
|
||||
- /admin/authentication/configuring-authentication-and-provisioning-for-your-enterprise-using-azure-ad
|
||||
- /admin/authentication/configuring-authentication-and-provisioning-with-your-identity-provider/configuring-authentication-and-provisioning-for-your-enterprise-using-azure-ad
|
||||
- /admin/identity-and-access-management/configuring-authentication-and-provisioning-with-your-identity-provider/configuring-authentication-and-provisioning-for-your-enterprise-using-azure-ad
|
||||
---
|
||||
## About authentication and user provisioning with Azure AD
|
||||
|
||||
@@ -1,12 +1,13 @@
|
||||
---
|
||||
title: Configuring authentication and provisioning for your enterprise using Okta
|
||||
shortTitle: Configuring with Okta
|
||||
shortTitle: Configure with Okta
|
||||
intro: 'You can use Okta as an identity provider (IdP) to centrally manage authentication and user provisioning for {% data variables.product.prodname_ghe_managed %}.'
|
||||
permissions: 'Enterprise owners can configure authentication and provisioning for {% data variables.product.prodname_ghe_managed %}.'
|
||||
versions:
|
||||
ghae: '*'
|
||||
redirect_from:
|
||||
- /admin/authentication/configuring-authentication-and-provisioning-with-your-identity-provider/configuring-authentication-and-provisioning-for-your-enterprise-using-okta
|
||||
- /admin/identity-and-access-management/configuring-authentication-and-provisioning-with-your-identity-provider/configuring-authentication-and-provisioning-for-your-enterprise-using-okta
|
||||
type: how_to
|
||||
topics:
|
||||
- Accounts
|
||||
@@ -7,13 +7,14 @@ redirect_from:
|
||||
- /github/setting-up-and-managing-your-enterprise/configuring-saml-single-sign-on-for-your-enterprise-account-using-okta
|
||||
- /github/setting-up-and-managing-your-enterprise/configuring-identity-and-access-management-for-your-enterprise-account/configuring-saml-single-sign-on-for-your-enterprise-account-using-okta
|
||||
- /admin/authentication/managing-identity-and-access-for-your-enterprise/configuring-saml-single-sign-on-for-your-enterprise-using-okta
|
||||
- /admin/identity-and-access-management/managing-iam-for-your-enterprise/configuring-saml-single-sign-on-for-your-enterprise-using-okta
|
||||
versions:
|
||||
ghec: '*'
|
||||
topics:
|
||||
- Authentication
|
||||
- Enterprise
|
||||
type: how_to
|
||||
shortTitle: Configure SAML with Okta
|
||||
shortTitle: Configure SAML SSO with Okta
|
||||
---
|
||||
|
||||
{% data reusables.enterprise-accounts.emu-saml-note %}
|
||||
@@ -1,10 +1,11 @@
|
||||
---
|
||||
title: Configuring SAML single sign-on for your enterprise
|
||||
shortTitle: Configure SAML SSO
|
||||
intro: 'You can control and secure access to {% ifversion ghec %}resources like repositories, issues, and pull requests within your enterprise''s organizations{% elsif ghae %}your enterprise on {% data variables.product.prodname_ghe_managed %}{% endif %} by {% ifversion ghec %}enforcing{% elsif ghae %}configuring{% endif %} SAML single sign-on (SSO) through your identity provider (IdP).'
|
||||
permissions: 'Enterprise owners can configure SAML SSO for an enterprise on {% data variables.product.product_name %}.'
|
||||
intro: 'You can control and secure access to {% ifversion ghec %}resources like repositories, issues, and pull requests within your enterprise''s organizations{% elsif ghes %}{% data variables.product.product_location %}{% elsif ghae %}your enterprise on {% data variables.product.prodname_ghe_managed %}{% endif %} by {% ifversion ghec %}enforcing{% elsif ghes or ghae %}configuring{% endif %} SAML single sign-on (SSO) through your identity provider (IdP).'
|
||||
permissions: '{% ifversion ghes %}Site administrators{% elsif ghec or ghae %}Enterprise owners{% endif %} can configure SAML SSO for {% ifversion ghec or ghae %}an enterprise on {% data variables.product.product_name %}{% elsif ghes %}a {% data variables.product.product_name %} instance{% endif %}.'
|
||||
versions:
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
ghae: '*'
|
||||
type: how_to
|
||||
topics:
|
||||
@@ -19,11 +20,12 @@ redirect_from:
|
||||
- /github/setting-up-and-managing-your-enterprise/configuring-identity-and-access-management-for-your-enterprise-account/enabling-saml-single-sign-on-for-organizations-in-your-enterprise-account
|
||||
- /github/setting-up-and-managing-your-enterprise/configuring-identity-and-access-management-for-your-enterprise-account/enforcing-saml-single-sign-on-for-organizations-in-your-enterprise-account
|
||||
- /admin/authentication/managing-identity-and-access-for-your-enterprise/configuring-saml-single-sign-on-for-your-enterprise
|
||||
- /admin/identity-and-access-management/managing-iam-for-your-enterprise/configuring-saml-single-sign-on-for-your-enterprise
|
||||
---
|
||||
|
||||
{% data reusables.enterprise-accounts.emu-saml-note %}
|
||||
|
||||
## About SAML SSO for enterprise accounts
|
||||
## About SAML SSO
|
||||
|
||||
{% ifversion ghec %}
|
||||
|
||||
@@ -37,24 +39,34 @@ redirect_from:
|
||||
|
||||
{% data reusables.scim.enterprise-account-scim %}
|
||||
|
||||
{% elsif ghae %}
|
||||
{% elsif ghes or ghae %}
|
||||
|
||||
SAML SSO allows you to centrally control and secure access to {% data variables.product.product_location %} from your SAML IdP. When an unauthenticated user visits {% data variables.product.product_location %} in a browser, {% data variables.product.product_name %} will redirect the user to your SAML IdP to authenticate. After the user successfully authenticates with an account on the IdP, the IdP redirects the user back to {% data variables.product.product_location %}. {% data variables.product.product_name %} validates the response from your IdP, then grants access to the user.
|
||||
|
||||
After a user successfully authenticates on your IdP, the user's SAML session for {% data variables.product.product_location %} is active in the browser for 24 hours. After 24 hours, the user must authenticate again with your IdP.
|
||||
|
||||
{% data reusables.saml.saml-ghes-account-revocation %}
|
||||
|
||||
{% ifversion ghae %}
|
||||
|
||||
{% data reusables.saml.assert-the-administrator-attribute %}
|
||||
|
||||
{% data reusables.scim.after-you-configure-saml %} For more information, see "[Configuring user provisioning for your enterprise](/admin/authentication/configuring-user-provisioning-for-your-enterprise)."
|
||||
|
||||
{% endif %}
|
||||
|
||||
{% endif %}
|
||||
|
||||
## Supported identity providers
|
||||
|
||||
{% data reusables.saml.saml-supported-idps %}
|
||||
|
||||
{% ifversion ghec %}
|
||||
|
||||
## Username considerations with SAML
|
||||
|
||||
{% ifversion ghec %}If you use {% data variables.product.prodname_emus %}, {% endif %}{% data reusables.enterprise_user_management.consider-usernames-for-external-authentication %} For more information, see "[Username considerations for external authentication](/admin/identity-and-access-management/managing-iam-for-your-enterprise/username-considerations-for-external-authentication)."
|
||||
|
||||
## Enforcing SAML single-sign on for organizations in your enterprise account
|
||||
|
||||
{% note %}
|
||||
@@ -86,6 +98,61 @@ For more detailed information about how to enable SAML using Okta, see "[Configu
|
||||
11. Click **Save**.
|
||||
{% data reusables.enterprise-accounts.download-recovery-codes %}
|
||||
|
||||
{% elsif ghes %}
|
||||
|
||||
## Configuring SAML SSO
|
||||
|
||||
You can enable or disable SAML authentication for {% data variables.product.product_location %}, or you can edit an existing configuration. You can view and edit authentication settings for {% data variables.product.product_name %} in the management console. For more information, see "[Accessing the management console](/admin/configuration/configuring-your-enterprise/accessing-the-management-console)."
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note**: {% data reusables.enterprise.test-in-staging %}
|
||||
|
||||
{% endnote %}
|
||||
|
||||
{% data reusables.enterprise_site_admin_settings.access-settings %}
|
||||
{% data reusables.enterprise_site_admin_settings.management-console %}
|
||||
{% data reusables.enterprise_management_console.authentication %}
|
||||
1. Select **SAML**.
|
||||
|
||||
|
||||
1. {% data reusables.enterprise_user_management.built-in-authentication-option %}
|
||||
|
||||
|
||||
1. Optionally, to enable unsolicited response SSO, select **IdP initiated SSO**. By default, {% data variables.product.prodname_ghe_server %} will reply to an unsolicited Identity Provider (IdP) initiated request with an `AuthnRequest` back to the IdP.
|
||||
|
||||
|
||||
|
||||
{% tip %}
|
||||
|
||||
**Note**: We recommend keeping this value **unselected**. You should enable this feature **only** in the rare instance that your SAML implementation does not support service provider initiated SSO, and when advised by {% data variables.contact.enterprise_support %}.
|
||||
|
||||
{% endtip %}
|
||||
|
||||
1. Select **Disable administrator demotion/promotion** if you **do not** want your SAML provider to determine administrator rights for users on {% data variables.product.product_location %}.
|
||||
|
||||
|
||||
{%- ifversion ghes > 3.3 %}
|
||||
1. Optionally, to allow {% data variables.product.product_location %} to receive encrypted assertions from your SAML IdP, select **Require encrypted assertions**. You must ensure that your IdP supports encrypted assertions and that the encryption and key transport methods in the management console match the values configured on your IdP. You must also provide {% data variables.product.product_location %}'s public certificate to your IdP. For more information, see "[Enabling encrypted assertions](/admin/identity-and-access-management/using-saml-for-enterprise-iam/enabling-encrypted-assertions)."
|
||||
|
||||
|
||||
{%- endif %}
|
||||
1. In the **Single sign-on URL** field, type the HTTP or HTTPS endpoint on your IdP for single sign-on requests. This value is provided by your IdP configuration. If the host is only available from your internal network, you may need to [configure {% data variables.product.product_location %} to use internal nameservers](/enterprise/{{ currentVersion }}/admin/guides/installation/configuring-dns-nameservers/).
|
||||
|
||||
|
||||
1. Optionally, in the **Issuer** field, type your SAML issuer's name. This verifies the authenticity of messages sent to {% data variables.product.product_location %}.
|
||||
|
||||
|
||||
1. In the **Signature Method** and **Digest Method** drop-down menus, choose the hashing algorithm used by your SAML issuer to verify the integrity of the requests from {% data variables.product.product_location %}. Specify the format with the **Name Identifier Format** drop-down menu.
|
||||
|
||||
|
||||
1. Under **Verification certificate**, click **Choose File** and choose a certificate to validate SAML responses from the IdP.
|
||||
|
||||
|
||||
1. Modify the SAML attribute names to match your IdP if needed, or accept the default names.
|
||||
|
||||
|
||||
|
||||
{% elsif ghae %}
|
||||
|
||||
## Enabling SAML SSO
|
||||
@@ -96,16 +163,10 @@ The following IdPs provide documentation about configuring SAML SSO for {% data
|
||||
|
||||
| IdP | More information |
|
||||
| :- | :- |
|
||||
| Azure AD | [Tutorial: Azure Active Directory single sign-on (SSO) integration with {% data variables.product.prodname_ghe_managed %}](https://docs.microsoft.com/azure/active-directory/saas-apps/github-ae-tutorial) in the Microsoft Docs. To configure Azure AD for {% data variables.product.prodname_ghe_managed %}, see "[Configuring authentication and provisioning for your enterprise using Azure AD](/admin/authentication/configuring-authentication-and-provisioning-with-your-identity-provider/configuring-authentication-and-provisioning-for-your-enterprise-using-azure-ad)." |
|
||||
| Okta (Beta) | To configure Okta for {% data variables.product.prodname_ghe_managed %}, see "[Configuring authentication and provisioning for your enterprise using Okta](/admin/authentication/configuring-authentication-and-provisioning-with-your-identity-provider/configuring-authentication-and-provisioning-for-your-enterprise-using-okta)."|
|
||||
| Azure AD | "[Configuring authentication and provisioning for your enterprise using Azure AD](/admin/authentication/configuring-authentication-and-provisioning-with-your-identity-provider/configuring-authentication-and-provisioning-for-your-enterprise-using-azure-ad)" |
|
||||
| Okta | "[Configuring authentication and provisioning for your enterprise using Okta](/admin/authentication/configuring-authentication-and-provisioning-with-your-identity-provider/configuring-authentication-and-provisioning-for-your-enterprise-using-okta)" |
|
||||
|
||||
During initialization for {% data variables.product.product_name %}, you must configure {% data variables.product.product_name %} as a SAML Service Provider (SP) on your IdP. You must enter several unique values on your IdP to configure {% data variables.product.product_name %} as a valid SP.
|
||||
|
||||
| Value | Other names | Description | Example |
|
||||
| :- | :- | :- | :- |
|
||||
| SP Entity ID | SP URL | Your top-level URL for {% data variables.product.prodname_ghe_managed %} | <code>https://<em>YOUR-GITHUB-AE-HOSTNAME</em></code>
|
||||
| SP Assertion Consumer Service (ACS) URL | Reply URL | URL where IdP sends SAML responses | <code>https://<em>YOUR-GITHUB-AE-HOSTNAME</em>/saml/consume</code> |
|
||||
| SP Single Sign-On (SSO) URL | | URL where IdP begins SSO | <code>https://<em>YOUR-GITHUB-AE-HOSTNAME</em>/sso</code> |
|
||||
During initialization for {% data variables.product.product_name %}, you must configure {% data variables.product.product_name %} as a SAML service provider (SP) on your IdP. You must enter several unique values on your IdP to configure {% data variables.product.product_name %} as a valid SP. For more information, see "[SAML configuration reference](/admin/identity-and-access-management/using-saml-for-enterprise-iam/saml-configuration-reference#saml-metadata)."
|
||||
|
||||
## Editing the SAML SSO configuration
|
||||
|
||||
@@ -164,3 +225,16 @@ If the details for your IdP change, you'll need to edit the SAML SSO configurati
|
||||
{% endif %}
|
||||
|
||||
{% endif %}
|
||||
|
||||
{% ifversion ghec or ghes %}
|
||||
|
||||
## Further reading
|
||||
|
||||
{%- ifversion ghec %}
|
||||
- "[Managing SAML single sign-on for your organization](/organizations/managing-saml-single-sign-on-for-your-organization)"
|
||||
{%- endif %}
|
||||
{%- ifversion ghes %}
|
||||
- "[Promoting or demoting a site administrator](/admin/user-management/managing-users-in-your-enterprise/promoting-or-demoting-a-site-administrator)"
|
||||
{%- endif %}
|
||||
|
||||
{% endif %}
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Configuring user provisioning for your enterprise
|
||||
shortTitle: Configuring user provisioning
|
||||
shortTitle: Configure user provisioning
|
||||
intro: 'You can configure System for Cross-domain Identity Management (SCIM) for your enterprise, which automatically provisions user accounts on {% data variables.product.product_location %} when you assign the application for {% data variables.product.product_location %} to a user on your identity provider (IdP).'
|
||||
permissions: 'Enterprise owners can configure user provisioning for an enterprise on {% data variables.product.product_name %}.'
|
||||
versions:
|
||||
@@ -14,14 +14,15 @@ topics:
|
||||
- SSO
|
||||
redirect_from:
|
||||
- /admin/authentication/configuring-user-provisioning-for-your-enterprise
|
||||
- /admin/identity-and-access-management/managing-iam-for-your-enterprise/configuring-user-provisioning-for-your-enterprise
|
||||
---
|
||||
## About user provisioning for your enterprise
|
||||
|
||||
{% data reusables.saml.ae-uses-saml-sso %} For more information, see "[Configuring SAML single sign-on for your enterprise](/admin/authentication/configuring-saml-single-sign-on-for-your-enterprise)."
|
||||
|
||||
{% data reusables.scim.after-you-configure-saml %} For more information about SCIM, see [System for Cross-domain Identity Management: Protocol (RFC 7644)](https://tools.ietf.org/html/rfc7644) on the IETF website.
|
||||
You can configure user provisioning with SCIM to automatically create or suspend user accounts and grant access for {% data variables.product.product_name %} when you assign or unassign the application on your IdP. For more information about SCIM, see [System for Cross-domain Identity Management: Protocol (RFC 7644)](https://tools.ietf.org/html/rfc7644) on the IETF website.
|
||||
|
||||
{% ifversion ghae %}
|
||||
If you do not configure user provisioning with SCIM, your IdP will not communicate with {% data variables.product.product_name %} automatically when you assign or unassign the application to a user. Without SCIM, {% data variables.product.product_name %} creates a user account using SAML Just-in-Time (JIT) provisioning the first time someone navigates to {% data variables.product.product_name %} and signs in by authenticating through your IdP.
|
||||
|
||||
Configuring provisioning allows your IdP to communicate with {% data variables.product.product_location %} when you assign or unassign the application for {% data variables.product.product_name %} to a user on your IdP. When you assign the application, your IdP will prompt {% data variables.product.product_location %} to create an account and send an onboarding email to the user. When you unassign the application, your IdP will communicate with {% data variables.product.product_name %} to invalidate any SAML sessions and disable the member's account.
|
||||
|
||||
@@ -29,8 +30,6 @@ To configure provisioning for your enterprise, you must enable provisioning on {
|
||||
|
||||
The provisioning application on your IdP communicates with {% data variables.product.product_name %} via our SCIM API for enterprises. For more information, see "[GitHub Enterprise administration](/rest/reference/enterprise-admin#scim)" in the {% data variables.product.prodname_dotcom %} REST API documentation.
|
||||
|
||||
{% endif %}
|
||||
|
||||
## Supported identity providers
|
||||
|
||||
The following IdPs are supported for SSO with {% data variables.product.prodname_ghe_managed %}:
|
||||
@@ -43,18 +42,12 @@ For IdPs that support team mapping, you can assign or unassign the application f
|
||||
|
||||
## Prerequisites
|
||||
|
||||
{% ifversion ghae %}
|
||||
|
||||
To automatically provision and deprovision access to {% data variables.product.product_location %} from your IdP, you must first configure SAML SSO when you initialize {% data variables.product.product_name %}. For more information, see "[Initializing {% data variables.product.prodname_ghe_managed %}](/admin/configuration/initializing-github-ae)."
|
||||
|
||||
You must have administrative access on your IdP to configure the application for user provisioning for {% data variables.product.product_name %}.
|
||||
|
||||
{% endif %}
|
||||
|
||||
## Enabling user provisioning for your enterprise
|
||||
|
||||
{% ifversion ghae %}
|
||||
|
||||
1. While signed into {% data variables.product.product_location %} as an enterprise owner, create a personal access token with **admin:enterprise** scope. For more information, see "[Creating a personal access token](/github/authenticating-to-github/creating-a-personal-access-token)."
|
||||
{% note %}
|
||||
|
||||
@@ -90,5 +83,3 @@ You must have administrative access on your IdP to configure the application for
|
||||
| :- | :- | :- | :- |
|
||||
| URL | Tenant URL | URL to the SCIM provisioning API for your enterprise on {% data variables.product.prodname_ghe_managed %} | <nobr><code>{% data variables.product.api_url_pre %}/scim/v2</nobr></code> |
|
||||
| Shared secret | Personal access token, secret token | Token for application on your IdP to perform provisioning tasks on behalf of an enterprise owner | Personal access token you created in step 1 |
|
||||
|
||||
{% endif %}
|
||||
@@ -0,0 +1,60 @@
|
||||
---
|
||||
title: Enabling encrypted assertions
|
||||
shortTitle: Enable encrypted assertions
|
||||
intro: You can improve {% data variables.product.product_location %}'s security with SAML single sign-on (SSO) by encrypting the messages that your SAML identity provider (IdP) sends.
|
||||
permissions: Site administrators can configure encrypted assertions for a {% data variables.product.product_name %} instance.
|
||||
versions:
|
||||
ghes: '> 3.3'
|
||||
type: how_to
|
||||
topics:
|
||||
- Accounts
|
||||
- Authentication
|
||||
- Enterprise
|
||||
- Identity
|
||||
- Security
|
||||
- SSO
|
||||
---
|
||||
|
||||
## About encrypted assertions
|
||||
|
||||
If your IdP support encryption of assertions, you can configure encrypted assertions on {% data variables.product.product_name %} for increased security during the authentication process.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
To enable encrypted assertions for authentication to {% data variables.product.product_name %}, you must configure SAML authentication, and your IdP must support encrypted assertions.
|
||||
|
||||
## Enabling encrypted assertions
|
||||
|
||||
To enable encrypted assertions, you must provide {% data variables.product.product_location %}'s public certificate to your IdP, and configure encryption settings that match your IdP.
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note**: {% data reusables.enterprise.test-in-staging %}
|
||||
|
||||
{% endnote %}
|
||||
|
||||
1. Optionally, enable SAML debugging. SAML debugging records verbose entries in {% data variables.product.product_name %}'s authentication log, and may help you troubleshoot failed authentication attempts. For more information, see "[Troubleshooting SAML authentication](/admin/identity-and-access-management/using-saml-for-enterprise-iam/troubleshooting-saml-authentication#configuring-saml-debugging)."
|
||||
{% data reusables.enterprise_site_admin_settings.access-settings %}
|
||||
{% data reusables.enterprise_site_admin_settings.management-console %}
|
||||
{% data reusables.enterprise_management_console.authentication %}
|
||||
1. Select **Require encrypted assertions**.
|
||||
|
||||
|
||||
1. To the right of "Encryption Certificate", click **Download** to save a copy of {% data variables.product.product_location %}'s public certificate on your local machine.
|
||||
|
||||
|
||||
1. Sign into your SAML IdP as an administrator.
|
||||
1. In the application for {% data variables.product.product_location %}, enable encrypted assertions.
|
||||
- Note the encryption method and key transport method.
|
||||
- Provide the public certificate you downloaded in step 7.
|
||||
1. Return to the management console on {% data variables.product.product_location %}.
|
||||
1. To the right of "Encryption Method", select the encryption method for your IdP from step 9.
|
||||
|
||||
|
||||
1. To the right of "Key Transport Method", select the key transport method for your IdP from step 9.
|
||||
|
||||
|
||||
1. Click **Save settings**.
|
||||
{% data reusables.enterprise_site_admin_settings.wait-for-configuration-run %}
|
||||
|
||||
If you enabled SAML debugging to test authentication with encrypted assertions, disable SAML debugging when you're done testing. For more information, see "[Troubleshooting SAML authentication](/admin/identity-and-access-management/using-saml-for-enterprise-iam/troubleshooting-saml-authentication#configuring-saml-debugging)."
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: Using SAML for enterprise IAM
|
||||
shortTitle: SAML for enterprise IAM
|
||||
intro: 'You can centrally manage {% ifversion ghes or ghae %}accounts and {% endif %}access to {% ifversion ghes %}{% data variables.product.product_location %}{% elsif ghae %}your enterprise{% elsif ghec %}your enterprise''s resources{% endif %} with SAML single sign-on (SSO){% ifversion ghec or ghae %} and System for Cross-domain Identity Management (SCIM){% endif %}.'
|
||||
versions:
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
ghae: '*'
|
||||
redirect_from:
|
||||
- /github/setting-up-and-managing-your-enterprise/configuring-identity-and-access-management-for-your-enterprise-account
|
||||
- /admin/authentication/managing-identity-and-access-for-your-enterprise
|
||||
- /admin/identity-and-access-management/managing-iam-for-your-enterprise
|
||||
- /admin/authentication/configuring-authentication-and-provisioning-with-your-identity-provider
|
||||
- /enterprise/admin/articles/configuring-saml-authentication
|
||||
- /enterprise/admin/articles/about-saml-authentication
|
||||
- /enterprise/admin/user-management/using-saml
|
||||
- /enterprise/admin/authentication/using-saml
|
||||
- /admin/authentication/using-saml
|
||||
- /enterprise/admin/authentication/authenticating-users-for-your-github-enterprise-server-instance/using-saml
|
||||
- /admin/identity-and-access-management/authenticating-users-for-your-github-enterprise-server-instance/using-saml
|
||||
children:
|
||||
- /about-saml-for-enterprise-iam
|
||||
- /saml-configuration-reference
|
||||
- /configuring-saml-single-sign-on-for-your-enterprise
|
||||
- /configuring-user-provisioning-for-your-enterprise
|
||||
- /managing-team-synchronization-for-organizations-in-your-enterprise
|
||||
- /configuring-saml-single-sign-on-for-your-enterprise-using-okta
|
||||
- /configuring-authentication-and-provisioning-for-your-enterprise-using-azure-ad
|
||||
- /configuring-authentication-and-provisioning-for-your-enterprise-using-okta
|
||||
- /mapping-okta-groups-to-teams
|
||||
- /enabling-encrypted-assertions
|
||||
- /updating-a-users-saml-nameid
|
||||
- /switching-your-saml-configuration-from-an-organization-to-an-enterprise-account
|
||||
- /troubleshooting-saml-authentication
|
||||
---
|
||||
|
||||
{% data reusables.enterprise-accounts.emu-saml-note %}
|
||||
@@ -14,6 +14,7 @@ redirect_from:
|
||||
- /github/setting-up-and-managing-your-enterprise/managing-team-synchronization-for-organizations-in-your-enterprise-account
|
||||
- /github/setting-up-and-managing-your-enterprise/configuring-identity-and-access-management-for-your-enterprise-account/managing-team-synchronization-for-organizations-in-your-enterprise-account
|
||||
- /admin/authentication/managing-identity-and-access-for-your-enterprise/managing-team-synchronization-for-organizations-in-your-enterprise
|
||||
- /admin/identity-and-access-management/managing-iam-for-your-enterprise/managing-team-synchronization-for-organizations-in-your-enterprise
|
||||
shortTitle: Manage team synchronization
|
||||
---
|
||||
|
||||
@@ -1,11 +1,13 @@
|
||||
---
|
||||
title: Mapping Okta groups to teams
|
||||
shortTitle: Map Okta groups to teams
|
||||
intro: 'You can map your Okta groups to teams on {% data variables.product.prodname_ghe_managed %} to automatically add and remove team members.'
|
||||
permissions: 'Enterprise owners can configure authentication and provisioning for {% data variables.product.prodname_ghe_managed %}.'
|
||||
versions:
|
||||
ghae: '*'
|
||||
redirect_from:
|
||||
- /admin/authentication/configuring-authentication-and-provisioning-with-your-identity-provider/mapping-okta-groups-to-teams
|
||||
- /admin/identity-and-access-management/configuring-authentication-and-provisioning-with-your-identity-provider/mapping-okta-groups-to-teams
|
||||
type: how_to
|
||||
topics:
|
||||
- Accounts
|
||||
@@ -0,0 +1,146 @@
|
||||
---
|
||||
title: 'SAML configuration reference'
|
||||
shortTitle: SAML reference
|
||||
intro: 'You can see SAML metadata for {% ifversion ghec %}your organization or enterprise on {% data variables.product.product_name %}{% elsif ghes %}{% data variables.product.product_location %}{% elsif ghae %}your enterprise on {% data variables.product.product_name %}{% endif %}, and you can learn more about available SAML attributes and response requirements.'
|
||||
versions:
|
||||
ghec: '*'
|
||||
ghes: '*'
|
||||
ghae: '*'
|
||||
type: reference
|
||||
topics:
|
||||
- Accounts
|
||||
- Authentication
|
||||
- Enterprise
|
||||
- Identity
|
||||
- SSO
|
||||
---
|
||||
|
||||
## About SAML configuration
|
||||
|
||||
To use SAML single sign-on (SSO) for authentication to {% data variables.product.product_name %}, you must configure both your external SAML identity provider (IdP) and {% ifversion ghes %}{% data variables.product.product_location %}{% elsif ghec %}your enterprise or organization on {% data variables.product.product_location %}{% elsif ghae %}your enterprise on {% data variables.product.product_name %}{% endif %}. In a SAML configuration, {% data variables.product.product_name %} functions as a SAML service provider (SP).
|
||||
|
||||
You must enter unique values from your SAML IdP when configuring SAML SSO for {% data variables.product.product_name %}, and you must also enter unique values from {% data variables.product.product_name %} on your IdP. For more information about the configuration of SAML SSO for {% data variables.product.product_name %}, see "[Configuring SAML single sign-on for your enterprise](/admin/identity-and-access-management/managing-iam-for-your-enterprise/configuring-saml-single-sign-on-for-your-enterprise){% ifversion ghes or ghae %}{% elsif ghec %}" or "[Enabling and testing SAML single sign-on for your organization](/organizations/managing-saml-single-sign-on-for-your-organization/enabling-and-testing-saml-single-sign-on-for-your-organization){% endif %}."
|
||||
|
||||
## SAML metadata
|
||||
|
||||
{% ifversion ghec %}
|
||||
|
||||
The SP metadata for {% data variables.product.product_name %} is available for either organizations or enterprises with SAML SSO. {% data variables.product.product_name %} uses the `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST` binding.
|
||||
|
||||
### Organizations
|
||||
|
||||
You can configure SAML SSO for an individual organization in your enterprise. You can also configure SAML SSO for an organization if you use an individual organization on {% data variables.product.product_name %} and do not use an enterprise account. For more information, see "[Managing SAML single sign-on for your organization](/organizations/managing-saml-single-sign-on-for-your-organization)."
|
||||
|
||||
The SP metadata for an organization on {% data variables.product.product_location %} is available at `https://github.com/orgs/ORGANIZATION/saml/metadata`, where **ORGANIZATION** is the name of your organization on {% data variables.product.product_location %}.
|
||||
|
||||
| Value | Other names | Description | Example |
|
||||
| :- | :- | :- | :- |
|
||||
| SP Entity ID | SP URL, audience restriction | The top-level URL for your organization on {% data variables.product.product_location %} | `https://github.com/orgs/ORGANIZATION` |
|
||||
| SP Assertion Consumer Service (ACS) URL | Reply, recipient, or destination URL | URL where IdP sends SAML responses | `https://github.com/orgs/ORGANIZATION/saml/consume` |
|
||||
| SP Single Sign-On (SSO) URL | | URL where IdP begins SSO | `https://github.com/orgs/ORGANIZATION/saml/sso` |
|
||||
|
||||
### Enterprises
|
||||
|
||||
The SP metadata for an enterprise on {% data variables.product.product_location %} is available at `https://github.com/enterprises/ENTERPRISE/saml/metadata`, where **ENTERPRISE** is the name of your enterprise on {% data variables.product.product_location %}.
|
||||
|
||||
| Value | Other names | Description | Example |
|
||||
| :- | :- | :- | :- |
|
||||
| SP Entity ID | SP URL, audience restriction | The top-level URL for your enterprise on {% data variables.product.product_location %} | `https://github.com/enterprises/ENTERPRISE` |
|
||||
| SP Assertion Consumer Service (ACS) URL | Reply, recipient, or destination URL | URL where IdP sends SAML responses | `https://github.com/enterprises/ENTERPRISE/saml/consume` |
|
||||
| SP Single Sign-On (SSO) URL | | URL where IdP begins SSO | `https://github.com/enterprises/ENTERPRISE/saml/sso` |
|
||||
|
||||
{% elsif ghes %}
|
||||
|
||||
The SP metadata for {% data variables.product.product_location %} is available at `http(s)://HOSTNAME/saml/metadata`, where **HOSTNAME** is the hostname for your instance. {% data variables.product.product_name %} uses the `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST` binding.
|
||||
|
||||
| Value | Other names | Description | Example |
|
||||
| :- | :- | :- | :- |
|
||||
| SP Entity ID | SP URL, audience restriction | Your top-level URL for {% data variables.product.product_name %} | `http(s)://HOSTNAME`
|
||||
| SP Assertion Consumer Service (ACS) URL | Reply, recipient, or destination URL | URL where IdP sends SAML responses | `http(s)://HOSTNAME/saml/consume` |
|
||||
| SP Single Sign-On (SSO) URL | | URL where IdP begins SSO | `http(s)://HOSTNAME/sso` |
|
||||
|
||||
{% elsif ghae %}
|
||||
|
||||
The SP metadata for your enterprise on {% data variables.product.product_name %} is available at `https://HOSTNAME/saml/metadata`, where **HOSTNAME** is the hostname for your enterprise on {% data variables.product.product_name %}. {% data variables.product.product_name %} uses the `urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST` binding.
|
||||
|
||||
| Value | Other names | Description | Example |
|
||||
| :- | :- | :- | :- |
|
||||
| SP Entity ID | SP URL, audience restriction | Your top-level URL for {% data variables.product.product_name %} | `https://HOSTNAME` |
|
||||
| SP Assertion Consumer Service (ACS) URL | Reply, recipient, or destination URL | URL where IdP sends SAML responses | `https://HOSTNAME/saml/consume` |
|
||||
| SP Single Sign-On (SSO) URL | | URL where IdP begins SSO | `https://HOSTNAME/sso` |
|
||||
|
||||
{% endif %}
|
||||
|
||||
## SAML attributes
|
||||
|
||||
The following SAML attributes are available for {% data variables.product.product_name %}.{% ifversion ghes %} You can change the attribute names in the management console, with the exception of the `administrator` attribute. For more information, see "[Accessing the management console](/admin/configuration/configuring-your-enterprise/accessing-the-management-console)."{% endif %}
|
||||
|
||||
| Name | Required? | Description |
|
||||
| :- | :- | :- |
|
||||
| `NameID` | Yes | A persistent user identifier. Any persistent name identifier format may be used. {% ifversion ghec %}If you use an enterprise with {% data variables.product.prodname_emus %}, {% endif %}{% data variables.product.product_name %} will normalize the `NameID` element to use as a username unless one of the alternative assertions is provided. For more information, see "[Username considerations for external authentication](/admin/identity-and-access-management/managing-iam-for-your-enterprise/username-considerations-for-external-authentication)." |
|
||||
| `SessionNotOnOrAfter` | No | The date that {% data variables.product.product_name %} invalidates the associated session. After invalidation, the person must authenticate once again to access {% ifversion ghec or ghae %}your enterprise's resources{% elsif ghes %}{% data variables.product.product_location %}{% endif %}. For more information, see "[Session duration and timeout](#session-duration-and-timeout)." |
|
||||
{%- ifversion ghes or ghae %}
|
||||
| `administrator` | No | When the value is `true`, {% data variables.product.product_name %} will automatically promote the user to be a {% ifversion ghes %}site administrator{% elsif ghae %}enterprise owner{% endif %}. Any other value or a non-existent value will demote the account and remove administrative access. |
|
||||
| `username` | No | The username for {% data variables.product.product_location %}. |
|
||||
{%- endif %}
|
||||
| `full_name` | No | {% ifversion ghec %}If you configure SAML SSO for an enterprise and you use {% data variables.product.prodname_emus %}, the{% else %}The{% endif %} full name of the user to display on the user's profile page. |
|
||||
| `emails` | No | The email addresses for the user.{% ifversion ghes or ghae %} You can specify more than one address.{% endif %}{% ifversion ghec or ghes %} If you sync license usage between {% data variables.product.prodname_ghe_server %} and {% data variables.product.prodname_ghe_cloud %}, {% data variables.product.prodname_github_connect %} uses `emails` to identify unique users across products. For more information, see "[Syncing license usage between {% data variables.product.prodname_ghe_server %} and {% data variables.product.prodname_ghe_cloud %}](/billing/managing-your-license-for-github-enterprise/syncing-license-usage-between-github-enterprise-server-and-github-enterprise-cloud)."{% endif %} |
|
||||
| `public_keys` | No | {% ifversion ghec %}If you configure SAML SSO for an enterprise and you use {% data variables.product.prodname_emus %}, the{% else %}The{% endif %} public SSH keys for the user. You can specify more than one key. |
|
||||
| `gpg_keys` | No | {% ifversion ghec %}If you configure SAML SSO for an enterprise and you use {% data variables.product.prodname_emus %}, the{% else %}The{% endif %} GPG keys for the user. You can specify more than one key. |
|
||||
|
||||
To specify more than one value for an attribute, use multiple `<saml2:AttributeValue>` elements.
|
||||
|
||||
```xml
|
||||
<saml2:Attribute FriendlyName="public_keys" Name="urn:oid:1.2.840.113549.1.1.1" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
|
||||
<saml2:AttributeValue>ssh-rsa LONG KEY</saml2:AttributeValue>
|
||||
<saml2:AttributeValue>ssh-rsa LONG KEY 2</saml2:AttributeValue>
|
||||
</saml2:Attribute>
|
||||
```
|
||||
|
||||
## SAML response requirements
|
||||
|
||||
{% data variables.product.product_name %} requires that the response message from your IdP fulfill the following requirements.
|
||||
|
||||
- Your IdP must provide the `<Destination>` element on the root response document and match the ACS URL only when the root response document is signed. If your IdP signs the assertion, {% data variables.product.product_name %} will ignore the assertion.
|
||||
- Your IdP must always provide the `<Audience>` element as part of the `<AudienceRestriction>` element. The value must match your `EntityId` for {% data variables.product.product_name %}.{% ifversion ghes or ghae %} This value is the URL where you access {% data variables.product.product_location %}, such as {% ifversion ghes %}`http(s)://HOSTNAME`{% elsif ghae %}`https://SUBDOMAIN.githubenterprise.com`, `https://SUBDOMAIN.github.us`, or `https://SUBDOMAIN.ghe.com`{% endif %}.{% endif %}
|
||||
|
||||
{%- ifversion ghec %}
|
||||
- If you configure SAML for an organization, this value is `https://github.com/orgs/ORGANIZATION`.
|
||||
- If you configure SAML for an enterprise, this URL is `https://github.com/enterprises/ENTERPRISE`.
|
||||
{%- endif %}
|
||||
- Your IdP must protect each assertion in the response with a digital signature. You can accomplish this by signing each individual `<Assertion>` element or by signing the `<Response>` element.
|
||||
- Your IdP must provide a `<NameID>` element as part of the `<Subject>` element. You may use any persistent name identifier format.
|
||||
- Your IdP must include the `Recipient` attribute, which must be set to the ACS URL. The following example demonstrates the attribute.
|
||||
|
||||
```xml
|
||||
<samlp:Response ...>
|
||||
<saml:Assertion ...>
|
||||
<saml:Subject>
|
||||
<saml:NameID ...>...</saml:NameID>
|
||||
<saml:SubjectConfirmation ...>
|
||||
<saml:SubjectConfirmationData Recipient="https://{% ifversion ghec %}github.com/enterprises/ENTERPRISE{% elsif ghes %}HOSTNAME{% elsif ghae %}SUBDOMAIN.ghe.com{% endif %}/saml/consume" .../>
|
||||
</saml:SubjectConfirmation>
|
||||
</saml:Subject>
|
||||
<saml:AttributeStatement>
|
||||
<saml:Attribute FriendlyName="USERNAME-ATTRIBUTE" ...>
|
||||
<saml:AttributeValue>monalisa</saml:AttributeValue>
|
||||
</saml:Attribute>
|
||||
</saml:AttributeStatement>
|
||||
</saml:Assertion>
|
||||
</samlp:Response>
|
||||
```
|
||||
|
||||
## Session duration and timeout
|
||||
|
||||
To prevent a person from authenticating with your IdP and staying authorized indefinitely, {% data variables.product.product_name %} periodically invalidates the session for each user account with access to {% ifversion ghec or ghae %}your enterprise's resources{% elsif ghes %}{% data variables.product.product_location %}{% endif %}. After invalidation, the person must authenticate with your IdP once again. By default, if your IdP does not assert a value for the `SessionNotOnOrAfter` attribute, {% data variables.product.product_name %} invalidates a session {% ifversion ghec %}24 hours{% elsif ghes or ghae %}one week{% endif %} after successful authentication with your IdP.
|
||||
|
||||
To customize the session duration, you may be able to define the value of the `SessionNotOnOrAfter` attribute on your IdP. If you define a value less than 24 hours, {% data variables.product.product_name %} may prompt people to authenticate every time {% data variables.product.product_name %} initiates a redirect.
|
||||
|
||||
{% note %}
|
||||
|
||||
**Notes**:
|
||||
|
||||
- For Azure AD, the configurable lifetime policy for SAML tokens does not control session timeout for {% data variables.product.product_name %}.
|
||||
- Okta does not currently send the `SessionNotOnOrAfter` attribute during SAML authentication with {% data variables.product.product_name %}. For more information, contact Okta.
|
||||
|
||||
{% endnote %}
|
||||
@@ -9,10 +9,11 @@ topics:
|
||||
- Enterprise
|
||||
- Organizations
|
||||
type: how_to
|
||||
shortTitle: Switching from organization
|
||||
shortTitle: From organization to enterprise
|
||||
redirect_from:
|
||||
- /github/setting-up-and-managing-your-enterprise/configuring-identity-and-access-management-for-your-enterprise-account/switching-your-saml-configuration-from-an-organization-to-an-enterprise-account
|
||||
- /admin/authentication/managing-identity-and-access-for-your-enterprise/switching-your-saml-configuration-from-an-organization-to-an-enterprise-account
|
||||
- /admin/identity-and-access-management/managing-iam-for-your-enterprise/switching-your-saml-configuration-from-an-organization-to-an-enterprise-account
|
||||
---
|
||||
|
||||
## About SAML single sign-on for enterprise accounts
|
||||
@@ -0,0 +1,102 @@
|
||||
---
|
||||
title: Troubleshooting SAML authentication
|
||||
shortTitle: Troubleshoot SAML SSO
|
||||
intro: If you use SAML single sign-on (SSO) and people are unable to authenticate to access {% data variables.product.product_location %}, you can troubleshoot the problem.
|
||||
versions:
|
||||
ghes: '*'
|
||||
type: how_to
|
||||
topics:
|
||||
- Accounts
|
||||
- Authentication
|
||||
- Enterprise
|
||||
- Identity
|
||||
- Security
|
||||
- SSO
|
||||
- Troubleshooting
|
||||
---
|
||||
|
||||
## About problems with SAML authentication
|
||||
|
||||
{% data variables.product.product_name %} logs error messages for failed SAML authentication in the authentication log at _/var/log/github/auth.log_. You can review responses in this log file, and you can also configure more verbose logging.
|
||||
|
||||
For more information about SAML response requirements, see "[SAML configuration reference](/admin/identity-and-access-management/using-saml-for-enterprise-iam/saml-configuration-reference#saml-response-requirements)."
|
||||
|
||||
## Configuring SAML debugging
|
||||
|
||||
You can configure {% data variables.product.product_name %} to write verbose debug logs to _/var/log/github/auth.log_ for every SAML authentication attempt. You may be able to troubleshoot failed authentication attempts with this extra output.
|
||||
|
||||
{% warning %}
|
||||
|
||||
**Warnings**:
|
||||
|
||||
- Only enable SAML debugging temporarily, and disable debugging immediately after you finish troubleshooting. If you leave debugging enabled, the size of your log may increase much faster than usual, which can negatively impact the performance of {% data variables.product.product_name %}.
|
||||
- Test new authentication settings for {% data variables.product.product_location %} in a staging environment before you apply the settings in your production environment. For more information, see "[Setting up a staging instance](/admin/installation/setting-up-a-github-enterprise-server-instance/setting-up-a-staging-instance)."
|
||||
|
||||
{% endwarning %}
|
||||
|
||||
{% data reusables.enterprise-accounts.access-enterprise %}
|
||||
{% data reusables.enterprise-accounts.policies-tab %}
|
||||
{% data reusables.enterprise-accounts.options-tab %}
|
||||
1. Under "SAML debugging", select the drop-down and click **Enabled**.
|
||||
|
||||
|
||||
|
||||
1. Attempt to sign into {% data variables.product.product_location %} through your SAML IdP.
|
||||
|
||||
1. Review the debug output in _/var/log/github/auth.log_ on {% data variables.product.product_location %}.
|
||||
|
||||
1. When you're done troubleshooting, select the drop-down and click **Disabled**.
|
||||
|
||||
|
||||
|
||||
## Decoding responses in _auth.log_
|
||||
|
||||
Some output in _auth.log_ may be Base64-encoded. You can access the administrative shell and use the `base64` utility on {% data variables.product.product_location %} to decode these responses. For more information, see "[Accessing the administrative shell (SSH)](/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh)."
|
||||
|
||||
```shell
|
||||
$ base64 --decode <em>ENCODED OUTPUT</em>
|
||||
```
|
||||
|
||||
## Error: "Another user already owns the account"
|
||||
|
||||
When a user signs into {% data variables.product.product_location %} for the first time with SAML authentication, {% data variables.product.product_name %} creates a user account on the instance and maps the SAML `NameID` to the account.
|
||||
|
||||
When the user signs in again, {% data variables.product.prodname_ghe_server %} compares the account's `NameID` mapping to the IdP's response. If the `NameID` in the IdP's response no longer matches the `NameID` that {% data variables.product.product_name %} expects for the user, the sign-in will fail. The user will see the following message.
|
||||
|
||||
> Another user already owns the account. Please have your administrator check the authentication log.
|
||||
|
||||
The message typically indicates that the person's username or email address has changed on the IdP. Ensure that the `NameID` mapping for the user account on {% data variables.product.prodname_ghe_server %} matches the user's `NameID` on your IdP. For more information, see "[Updating a user's SAML `NameID`](/admin/identity-and-access-management/using-saml-for-enterprise-iam/updating-a-users-saml-nameid)."
|
||||
|
||||
## Error: Recipient in SAML response was blank or not valid
|
||||
|
||||
If the `Recipient` does not match the ACS URL for {% data variables.product.product_location %}, one of the following two error messages will appear in the authentication log when a user attempts to authenticate.
|
||||
|
||||
```
|
||||
Recipient in the SAML response must not be blank.
|
||||
```
|
||||
|
||||
```
|
||||
Recipient in the SAML response was not valid.
|
||||
```
|
||||
|
||||
Ensure that you set the value for `Recipient` on your IdP to the full ACS URL for {% data variables.product.product_location %}. For example, `https://ghe.corp.example.com/saml/consume`.
|
||||
|
||||
## Error: "SAML Response is not signed or has been modified"
|
||||
|
||||
If your IdP does not sign the SAML response, or the signature does not match the contents, the following error message will appear in the authentication log.
|
||||
|
||||
```
|
||||
SAML Response is not signed or has been modified.
|
||||
```
|
||||
|
||||
Ensure that you configure signed assertions for the {% data variables.product.product_name %} application on your IdP.
|
||||
|
||||
## Error: "Audience is invalid" or "No assertion found"
|
||||
|
||||
If the IdP's response has a missing or incorrect value for `Audience`, the following error message will appear in the authentication log.
|
||||
|
||||
```
|
||||
Audience is invalid. Audience attribute does not match https://<em>YOUR-INSTANCE-URL</em>
|
||||
```
|
||||
|
||||
Ensure that you set the value for `Audience` on your IdP to the `EntityId` for {% data variables.product.product_location %}, which is the full URL to your instance. For example, `https://ghe.corp.example.com`.
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: Updating a user's SAML NameID
|
||||
shortTitle: Update SAML NameID
|
||||
intro: When an account's `NameID` changes on your identity provider (IdP) and the person can no longer {% ifversion ghes or ghae %}sign into {% data variables.product.product_location %}{% elsif ghec %}authenticate to access your enterprise's resources{% endif %}, you must {% ifversion ghec %}either contact {% data variables.product.company_short %} Support or revoke the person's linked identity{% elsif ghes %}update the `NameID` mapping on {% data variables.product.product_location %}{% elsif ghae %}contact {% data variables.product.company_short %} Support{% endif %}.
|
||||
versions:
|
||||
ghes: '*'
|
||||
type: how_to
|
||||
topics:
|
||||
- Accounts
|
||||
- Authentication
|
||||
- Enterprise
|
||||
- Identity
|
||||
- SSO
|
||||
---
|
||||
|
||||
## About updates to users' SAML `NameID`
|
||||
|
||||
In some situations, you may need to update values associated with a person's account on your SAML IdP. If that identifier is also the `NameID` that you use for authentication on {% data variables.product.product_name %}, you must update the `NameID` mapping on your instance so the person can continue to authenticate successfully. For more information, see "[Username considerations for external authentication](/admin/identity-and-access-management/managing-iam-for-your-enterprise/username-considerations-for-external-authentication)."
|
||||
|
||||
## Updating a user's SAML `NameID`
|
||||
|
||||
Enterprise owners can update a user's SAML `NameID` on a {% data variables.product.product_name %} instance.
|
||||
|
||||
{% data reusables.enterprise_site_admin_settings.access-settings %}
|
||||
2. In the left sidebar, click **All users**.
|
||||
|
||||
3. In the list of users, click the username you'd like to update the `NameID` mapping for.
|
||||
|
||||
{% data reusables.enterprise_site_admin_settings.security-tab %}
|
||||
5. To the right of "Update SAML NameID", click **Edit** .
|
||||
|
||||
6. In the "NameID" field, type the new `NameID` for the user.
|
||||
|
||||
7. Click **Update NameID**.
|
||||
|
||||
@@ -65,6 +65,7 @@ redirect_from:
|
||||
- /admin/configuration/configuring-your-enterprise/configuring-data-encryption-for-your-enterprise
|
||||
introLinks:
|
||||
overview: '{% ifversion ghes %}/admin/overview/system-overview{% elsif ghae %}/admin/overview/about-github-ae{% elsif ghec %}/admin/overview/about-enterprise-accounts{% endif %}'
|
||||
Releases: '{% ifversion ghes %}/admin/all-releases{% endif %}'
|
||||
changelog:
|
||||
label: enterprise
|
||||
featuredLinks:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Setting up a staging instance
|
||||
intro: 'You can use a *staging instance* to test modifications before they are applied to {% data variables.product.product_location %}. For example, you could use a staging instance to test new {% data variables.product.prodname_ghe_server %} updates or to practice importing migration data.'
|
||||
intro: You can set up a {% data variables.product.product_name %} instance in a separate, isolated environment, and use the instance to validate and test changes.
|
||||
redirect_from:
|
||||
- /enterprise/admin/installation/setting-up-a-staging-instance
|
||||
- /admin/installation/setting-up-a-staging-instance
|
||||
@@ -13,26 +13,36 @@ topics:
|
||||
- Upgrades
|
||||
shortTitle: Set up a staging instance
|
||||
---
|
||||
|
||||
## About staging instances
|
||||
|
||||
{% data variables.product.company_short %} recommends that you set up a separate environment to test backups, updates, or changes to the configuration for {% data variables.product.product_location %}. This environment, which you should isolate from your production systems, is called a staging environment.
|
||||
|
||||
For example, to protect against loss of data, you can regularly validate the backup of your production instance. You can regularly restore the backup of your production data to a separate {% data variables.product.product_name %} instance in a staging environment. On this staging instance, you could also test the upgrade to the latest feature release of {% data variables.product.product_name %}.
|
||||
|
||||
{% tip %}
|
||||
|
||||
**Tip:** You may reuse your existing {% data variables.product.prodname_enterprise %} license file as long as the staging instance is not used for production.
|
||||
**Tip:** You may reuse your existing {% data variables.product.prodname_enterprise %} license file as long as the staging instance is not used in a production capacity.
|
||||
|
||||
{% endtip %}
|
||||
|
||||
To thoroughly test a {% data variables.product.prodname_ghe_server %} appliance you will need to consider external systems that interact with it. Some factors to consider testing are:
|
||||
## Considerations for a staging environment
|
||||
|
||||
- Authentication, especially if are using an external authentication provider
|
||||
- Integration with an external ticketing system
|
||||
- Integration with a continuous integration server
|
||||
- External scripts or software that use {% data variables.product.prodname_enterprise_api %}
|
||||
- External SMTP server for email notifications
|
||||
To thoroughly test {% data variables.product.product_name %} and recreate an environment that's as similar to your production environment as possible, consider the external systems that interact with your instance. For example, you may want to test the following in your staging environment.
|
||||
|
||||
- Authentication, especially if you use an external authentication provider like SAML
|
||||
- Integration with an external ticketing system
|
||||
- Integration with a continuous integration server
|
||||
- External scripts or software that use {% data variables.product.prodname_enterprise_api %}
|
||||
- External SMTP server for email notifications
|
||||
|
||||
## Setting up a staging instance
|
||||
|
||||
1. Perform a backup of your production instance using {% data variables.product.prodname_enterprise_backup_utilities %}. For more information, see the "About {% data variables.product.prodname_enterprise_backup_utilities %}" section of "[Configuring backups on your appliance](/enterprise/admin/guides/installation/configuring-backups-on-your-appliance#about-github-enterprise-server-backup-utilities)."
|
||||
2. Set up a new instance to act as your staging environment. You can use the same guides for provisioning and installing your staging instance as you did for your production instance. For more information, see "[Setting up a {% data variables.product.prodname_ghe_server %} instance](/enterprise/admin/guides/installation/setting-up-a-github-enterprise-server-instance/)."
|
||||
3. Restore your backup onto your staging instance. For more information, see the "Restoring a backup" section of "[Configuring backups on your appliance](/enterprise/admin/guides/installation/configuring-backups-on-your-appliance#restoring-a-backup)."
|
||||
3. Optionally, if you plan to test {% data variables.product.prodname_actions %} functionality in your test environment, review the considerations for your logs and storage. For more information, see "[Using a staging environment](/admin/github-actions/advanced-configuration-and-troubleshooting/using-a-staging-environment)."
|
||||
4. Restore your backup onto your staging instance. For more information, see the "Restoring a backup" section of "[Configuring backups on your appliance](/enterprise/admin/guides/installation/configuring-backups-on-your-appliance#restoring-a-backup)."
|
||||
|
||||
{% ifversion ghes %}
|
||||
## Further reading
|
||||
|
||||
- "[About upgrades to new releases](/admin/overview/about-upgrades-to-new-releases)"
|
||||
{% endif %}
|
||||
|
||||
@@ -24,7 +24,7 @@ topics:
|
||||
|
||||
{% ifversion ghec %}
|
||||
|
||||
Your enterprise account on {% data variables.product.prodname_dotcom_the_website %} allows you to manage multiple organizations. Your enterprise account must have a handle, like an organization or personal account on {% data variables.product.prodname_dotcom %}.
|
||||
Your enterprise account on {% data variables.product.prodname_dotcom_the_website %} allows you to manage multiple organizations. Your enterprise account must have a handle, like an organization or user account on {% data variables.product.prodname_dotcom %}.
|
||||
|
||||
{% elsif ghes or ghae %}
|
||||
|
||||
|
||||
@@ -12,7 +12,7 @@ topics:
|
||||
---
|
||||
{% ifversion ghes < 3.3 %}{% data reusables.enterprise.upgrade-ghes-for-features %}{% endif %}
|
||||
|
||||
{% data variables.product.product_name %} is constantly improving, with new functionality and bug fixes introduced through feature and patch releases. {% ifversion ghae %}{% data variables.product.prodname_ghe_managed %} is a fully managed service, so {% data variables.product.company_short %} completes the upgrade process for your enterprise.{% endif %}
|
||||
{% data reusables.enterprise.constantly-improving %}{% ifversion ghae %}{% data variables.product.prodname_ghe_managed %} is a fully managed service, so {% data variables.product.company_short %} completes the upgrade process for your enterprise.{% endif %}
|
||||
|
||||
Feature releases include new functionality and feature upgrades and typically occur quarterly. {% ifversion ghae %}{% data variables.product.company_short %} will upgrade your enterprise to the latest feature release. You will be given advance notice of any planned downtime for your enterprise.{% endif %}
|
||||
|
||||
|
||||
@@ -124,7 +124,7 @@ For more information about {% data variables.product.prodname_ghe_server %}'s us
|
||||
|
||||
- SSH public key authentication provides both repository access using Git and administrative shell access. For more information, see "[About SSH](/authentication/connecting-to-github-with-ssh/about-ssh)" and "[Accessing the administrative shell (SSH)](/admin/configuration/configuring-your-enterprise/accessing-the-administrative-shell-ssh)."
|
||||
- Username and password authentication with HTTP cookies provides web application access and session management, with optional two-factor authentication (2FA). For more information, see "[Using built-in authentication](/admin/identity-and-access-management/authenticating-users-for-your-github-enterprise-server-instance/using-built-in-authentication)."
|
||||
- External LDAP, SAML, or CAS authentication using an LDAP service, SAML Identity Provider (IdP), or other compatible service provides access to the web application. For more information, see "[Authenticating users for your GitHub Enterprise Server instance](/admin/identity-and-access-management/authenticating-users-for-your-github-enterprise-server-instance)."
|
||||
- External LDAP, SAML, or CAS authentication using an LDAP service, SAML Identity Provider (IdP), or other compatible service provides access to the web application. For more information, see "[Managing IAM for your enterprise](/admin/identity-and-access-management/managing-iam-for-your-enterprise)."
|
||||
- OAuth and Personal Access Tokens provide access to Git repository data and APIs for both external clients and services. For more information, see "[Creating a personal access token](/github/authenticating-to-github/creating-a-personal-access-token)."
|
||||
|
||||
### Audit and access logging
|
||||
|
||||
@@ -31,7 +31,7 @@ You can enforce policies to control the security settings for organizations owne
|
||||
|
||||
## Requiring two-factor authentication for organizations in your enterprise
|
||||
|
||||
Enterprise owners can require that organization members, billing managers, and outside collaborators in all organizations owned by an enterprise use two-factor authentication to secure their personal accounts.
|
||||
Enterprise owners can require that organization members, billing managers, and outside collaborators in all organizations owned by an enterprise use two-factor authentication to secure their user accounts.
|
||||
|
||||
Before you can require 2FA for all organizations owned by your enterprise, you must enable two-factor authentication for your own account. For more information, see "[Securing your account with two-factor authentication (2FA)](/articles/securing-your-account-with-two-factor-authentication-2fa/)."
|
||||
|
||||
@@ -39,9 +39,9 @@ Before you can require 2FA for all organizations owned by your enterprise, you m
|
||||
|
||||
**Warnings:**
|
||||
|
||||
- When you require two-factor authentication for your enterprise, members, outside collaborators, and billing managers (including bot accounts) in all organizations owned by your enterprise who do not use 2FA will be removed from the organization and lose access to its repositories. They will also lose access to their forks of the organization's private repositories. You can reinstate their access privileges and settings if they enable two-factor authentication for their personal account within three months of their removal from your organization. For more information, see "[Reinstating a former member of your organization](/articles/reinstating-a-former-member-of-your-organization)."
|
||||
- Any organization owner, member, billing manager, or outside collaborator in any of the organizations owned by your enterprise who disables 2FA for their personal account after you've enabled required two-factor authentication will automatically be removed from the organization.
|
||||
- If you're the sole owner of a enterprise that requires two-factor authentication, you won't be able to disable 2FA for your personal account without disabling required two-factor authentication for the enterprise.
|
||||
- When you require two-factor authentication for your enterprise, members, outside collaborators, and billing managers (including bot accounts) in all organizations owned by your enterprise who do not use 2FA will be removed from the organization and lose access to its repositories. They will also lose access to their forks of the organization's private repositories. You can reinstate their access privileges and settings if they enable two-factor authentication for their account within three months of their removal from your organization. For more information, see "[Reinstating a former member of your organization](/articles/reinstating-a-former-member-of-your-organization)."
|
||||
- Any organization owner, member, billing manager, or outside collaborator in any of the organizations owned by your enterprise who disables 2FA for their account after you've enabled required two-factor authentication will automatically be removed from the organization.
|
||||
- If you're the sole owner of a enterprise that requires two-factor authentication, you won't be able to disable 2FA for your user account without disabling required two-factor authentication for the enterprise.
|
||||
|
||||
{% endwarning %}
|
||||
|
||||
|
||||
@@ -60,10 +60,10 @@ shortTitle: Project management with Jira
|
||||
|
||||
5. In the **Add New Account** modal, fill in your {% data variables.product.prodname_enterprise %} settings:
|
||||
- From the **Host** dropdown menu, choose **{% data variables.product.prodname_enterprise %}**.
|
||||
- In the **Team or User Account** field, type the name of your {% data variables.product.prodname_enterprise %} organization or personal account.
|
||||
- In the **Team or User Account** field, type the name of your {% data variables.product.prodname_enterprise %} organization or user account.
|
||||
- In the **OAuth Key** field, type the Client ID of your {% data variables.product.prodname_enterprise %} developer application.
|
||||
- In the **OAuth Secret** field, type the Client Secret for your {% data variables.product.prodname_enterprise %} developer application.
|
||||
- If you don't want to link new repositories owned by your {% data variables.product.prodname_enterprise %} organization or personal account, deselect **Auto Link New Repositories**.
|
||||
- If you don't want to link new repositories owned by your {% data variables.product.prodname_enterprise %} organization or user account, deselect **Auto Link New Repositories**.
|
||||
- If you don't want to enable smart commits, deselect **Enable Smart Commits**.
|
||||
- Click **Add**.
|
||||
6. Review the permissions you are granting to your {% data variables.product.prodname_enterprise %} account and click **Authorize application**.
|
||||
|
||||
@@ -30,7 +30,7 @@ Account security is fundamental to the security of your supply chain. If an atta
|
||||
{% ifversion ghec %}
|
||||
If you're an enterprise or organization owner, you can configure centralized authentication with SAML. While you can add or remove members manually, it's simpler and more secure to set up single sign-on (SSO) and SCIM between {% data variables.product.product_name %} and your SAML identity provider (IdP). This also simplifies the authentication process for all members of your enterprise.
|
||||
|
||||
You can configure SAML authentication for an enterprise or organization account. With SAML, you can grant access to the personal accounts of members of your enterprise or organization on {% data variables.product.product_location %} through your IdP, or you can create and control the accounts that belong to your enterprise by using {% data variables.product.prodname_emus %}. For more information, see "[About identity and access management with SAML single sign-on](/organizations/managing-saml-single-sign-on-for-your-organization/about-identity-and-access-management-with-saml-single-sign-on)".
|
||||
You can configure SAML authentication for an enterprise or organization account. With SAML, you can grant access to the personal accounts of members of your enterprise or organization on {% data variables.product.product_location %} through your IdP, or you can create and control the accounts that belong to your enterprise by using {% data variables.product.prodname_emus %}. For more information, see "[About authentication for your enterprise](/admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise)."
|
||||
|
||||
After you configure SAML authentication, when members request access to your resources, they'll be directed to your SSO flow to ensure they are still recognized by your IdP. If they are unrecognized, their request is declined.
|
||||
|
||||
@@ -42,7 +42,7 @@ If you're the site administrator for {% data variables.product.product_location
|
||||
|
||||
Some authentication methods also support communicating additional information to {% data variables.product.product_name %}, for example, what groups the user is a member of, or synchronizing cryptographic keys for the user. This is a great way to simplify your administration as your organization grows.
|
||||
|
||||
For more information on these authentication methods, see "[Using CAS](/admin/identity-and-access-management/authenticating-users-for-your-github-enterprise-server-instance/using-cas)," "[Using SAML](/admin/identity-and-access-management/authenticating-users-for-your-github-enterprise-server-instance/using-saml)," and "[Using LDAP](/admin/identity-and-access-management/authenticating-users-for-your-github-enterprise-server-instance/using-ldap)."
|
||||
For more information about the authentication methods available for {% data variables.product.product_name %}, see "[About authentication for your enterprise](/admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise)."
|
||||
{% endif %}
|
||||
|
||||
## Configure two-factor authentication
|
||||
|
||||
@@ -67,7 +67,7 @@ As an enterprise owner or administrator, you can manage settings on user, reposi
|
||||
## Part 3: Building securely
|
||||
To increase the security of {% data variables.product.product_location %}, you can configure authentication for enterprise members, use tools and audit logging to stay in compliance, configure security and analysis features for your organizations, and optionally enable {% data variables.product.prodname_GH_advanced_security %}.
|
||||
### 1. Authenticating enterprise members
|
||||
You can use {% data variables.product.product_name %}'s built-in authentication method, or you can choose between an established authentication provider, such as CAS, LDAP, or SAML, to integrate your existing accounts and centrally manage user access to {% data variables.product.product_location %}. For more information, see "[Authenticating users for {% data variables.product.product_location %}](/admin/authentication/authenticating-users-for-your-github-enterprise-server-instance)."
|
||||
You can use {% data variables.product.product_name %}'s built-in authentication method, or you can choose between an external authentication provider, such as CAS, LDAP, or SAML, to integrate your existing accounts and centrally manage user access to {% data variables.product.product_location %}. For more information, see "[About authentication for your enterprise](/admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise)."
|
||||
|
||||
You can also require two-factor authentication for each of your organizations. For more information, see "[Requiring two factor authentication for an organization](/admin/user-management/managing-organizations-in-your-enterprise/requiring-two-factor-authentication-for-an-organization)."
|
||||
|
||||
|
||||
@@ -29,7 +29,7 @@ An organization owner can restrict the ability to invite collaborators. For more
|
||||
{% endif %}
|
||||
|
||||
{% ifversion ghes %}
|
||||
Before you can add someone as an outside collaborator on a repository, the person must have a personal account on {% data variables.product.product_location %}. If your enterprise uses an external authentication system such as SAML or LDAP, the person you want to add must sign in through that system to create an account. If the person does not have access to the authentication system and built-in authentication is enabled for your enterprise, a site admin can create a personal account for the person. For more information, see "[Using built-in authentication](/admin/authentication/authenticating-users-for-your-github-enterprise-server-instance/using-built-in-authentication#inviting-users)."
|
||||
Before you can add someone as an outside collaborator on a repository, the person must have a personal account on {% data variables.product.product_location %}. If your enterprise uses an external authentication system such as SAML or LDAP, the person you want to add must sign in through that system to create an account. If the person does not have access to the authentication system and built-in authentication is enabled for your enterprise, a site administrator can create an account for the person. For more information, see "[Configuring built-in authentication](/admin/identity-and-access-management/using-built-in-authentication/configuring-built-in-authentication)."
|
||||
{% endif %}
|
||||
|
||||
{% ifversion not ghae %}
|
||||
|
||||
@@ -62,5 +62,6 @@ If your IdP supports SCIM, {% data variables.product.prodname_dotcom %} can auto
|
||||
|
||||
## Further reading
|
||||
|
||||
- "[SAML configuration reference](/admin/identity-and-access-management/using-saml-for-enterprise-iam/saml-configuration-reference)"
|
||||
- "[About two-factor authentication and SAML single sign-on ](/articles/about-two-factor-authentication-and-saml-single-sign-on)"
|
||||
- "[About authentication with SAML single sign-on](/github/authenticating-to-github/about-authentication-with-saml-single-sign-on)"
|
||||
|
||||
@@ -1,17 +1,20 @@
|
||||
---
|
||||
title: Connecting your identity provider to your organization
|
||||
intro: 'To use SAML single sign-on and SCIM, you must connect your identity provider to your {% data variables.product.product_name %} organization.'
|
||||
intro: 'To use SAML single sign-on and SCIM, you must connect your identity provider (IdP) to your organization on {% data variables.product.product_name %}.'
|
||||
redirect_from:
|
||||
- /articles/connecting-your-identity-provider-to-your-organization
|
||||
- /github/setting-up-and-managing-organizations-and-teams/connecting-your-identity-provider-to-your-organization
|
||||
versions:
|
||||
ghec: '*'
|
||||
topics:
|
||||
- Authentication
|
||||
- Organizations
|
||||
- Teams
|
||||
shortTitle: Connect an IdP
|
||||
---
|
||||
|
||||
## About connection of your IdP to your organization
|
||||
|
||||
When you enable SAML SSO for your {% data variables.product.product_name %} organization, you connect your identity provider (IdP) to your organization. For more information, see "[Enabling and testing SAML single sign-on for your organization](/organizations/managing-saml-single-sign-on-for-your-organization/enabling-and-testing-saml-single-sign-on-for-your-organization)."
|
||||
|
||||
{% data reusables.saml.ghec-only %}
|
||||
@@ -24,14 +27,12 @@ You can find the SAML and SCIM implementation details for your IdP in the IdP's
|
||||
- PingOne [SAML](https://support.pingidentity.com/s/marketplace-integration/a7i1W0000004ID3QAM/github-connector)
|
||||
- Shibboleth [SAML](https://wiki.shibboleth.net/confluence/display/IDP30/Home)
|
||||
|
||||
You can access your organization's service provider metadata at the following URL, replacing ORGANIZATION with your organization's username.
|
||||
|
||||
```
|
||||
http(s)://github.com/orgs/ORGANIZATION/saml/metadata.xml
|
||||
```
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note:** {% data variables.product.product_name %} supported identity providers for SCIM are Azure AD, Okta, and OneLogin. {% data reusables.scim.enterprise-account-scim %} For more information about SCIM, see "[About SCIM](/organizations/managing-saml-single-sign-on-for-your-organization/about-scim)."
|
||||
|
||||
{% endnote %}
|
||||
|
||||
## SAML metadata
|
||||
|
||||
For more information about SAML metadata for your organization, see "[SAML configuration reference](/admin/identity-and-access-management/using-saml-for-enterprise-iam/saml-configuration-reference)."
|
||||
|
||||
@@ -65,3 +65,4 @@ For more information about the identity providers (IdPs) that {% data variables.
|
||||
## Further reading
|
||||
|
||||
- "[About identity and access management with SAML single sign-on](/articles/about-identity-and-access-management-with-saml-single-sign-on)"
|
||||
- "[SAML configuration reference](/admin/identity-and-access-management/using-saml-for-enterprise-iam/saml-configuration-reference)"
|
||||
|
||||
@@ -3,3 +3,5 @@
|
||||
versions:
|
||||
fpt: '*'
|
||||
ghec: '*'
|
||||
ghes: '>3.4'
|
||||
ghae: 'issue-5169'
|
||||
|
||||
8
data/reusables/actions/about-triggers.md
Normal file
8
data/reusables/actions/about-triggers.md
Normal file
@@ -0,0 +1,8 @@
|
||||
Workflow triggers are events that cause a workflow to run. These events can be:
|
||||
|
||||
- Events that occur in your workflow's repository
|
||||
- Events that occur outside of {% data variables.product.product_name %} and trigger a `repository_dispatch` event on {% data variables.product.product_name %}
|
||||
- Scheduled times
|
||||
- Manual
|
||||
|
||||
For example, you can configure your workflow to run when a push is made to the default branch of your repository, when a release is created, or when an issue is opened.
|
||||
3
data/reusables/actions/about-workflows-long.md
Normal file
3
data/reusables/actions/about-workflows-long.md
Normal file
@@ -0,0 +1,3 @@
|
||||
A workflow is a configurable automated process that will run one or more jobs. Workflows are defined by a YAML file checked in to your repository and will run when triggered by an event in your repository, or they can be triggered manually, or at a defined schedule.
|
||||
|
||||
Workflows are defined in the `.github/workflows` directory in a repository, and a repository can have multiple workflows, each of which can perform a different set of tasks. For example, you can have one workflow to build and test pull requests, another workflow to deploy your application every time a release is created, and still another workflow that adds a label every time someone opens a new issue.
|
||||
172
data/reusables/actions/workflow-basic-example-and-explanation.md
Normal file
172
data/reusables/actions/workflow-basic-example-and-explanation.md
Normal file
@@ -0,0 +1,172 @@
|
||||
## Create an example workflow
|
||||
|
||||
{% data variables.product.prodname_actions %} uses YAML syntax to define the workflow. Each workflow is stored as a separate YAML file in your code repository, in a directory named `.github/workflows`.
|
||||
|
||||
You can create an example workflow in your repository that automatically triggers a series of commands whenever code is pushed. In this workflow, {% data variables.product.prodname_actions %} checks out the pushed code, installs the [bats](https://www.npmjs.com/package/bats) testing framework, and runs a basic command to output the bats version: `bats -v`.
|
||||
|
||||
1. In your repository, create the `.github/workflows/` directory to store your workflow files.
|
||||
1. In the `.github/workflows/` directory, create a new file called `learn-github-actions.yml` and add the following code.
|
||||
|
||||
```yaml
|
||||
name: learn-github-actions
|
||||
on: [push]
|
||||
jobs:
|
||||
check-bats-version:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: {% data reusables.actions.action-checkout %}
|
||||
- uses: {% data reusables.actions.action-setup-node %}
|
||||
with:
|
||||
node-version: '14'
|
||||
- run: npm install -g bats
|
||||
- run: bats -v
|
||||
```
|
||||
1. Commit these changes and push them to your {% data variables.product.prodname_dotcom %} repository.
|
||||
|
||||
Your new {% data variables.product.prodname_actions %} workflow file is now installed in your repository and will run automatically each time someone pushes a change to the repository. To see the details about a workflow's execution history, see "[Viewing the activity for a workflow run](#viewing-the-activity-for-a-workflow-run)."
|
||||
|
||||
## Understanding the workflow file
|
||||
|
||||
To help you understand how YAML syntax is used to create a workflow file, this section explains each line of the introduction's example:
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
```yaml
|
||||
name: learn-github-actions
|
||||
```
|
||||
</td>
|
||||
<td>
|
||||
<em>Optional</em> - The name of the workflow as it will appear in the Actions tab of the {% data variables.product.prodname_dotcom %} repository.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
```yaml
|
||||
on: [push]
|
||||
```
|
||||
</td>
|
||||
<td>
|
||||
Specifies the trigger for this workflow. This example uses the <code>push</code> event, so a workflow run is triggered every time someone pushes a change to the repository or merges a pull request. This is triggered by a push to every branch; for examples of syntax that runs only on pushes to specific branches, paths, or tags, see "<a href="/actions/reference/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore">Workflow syntax for {% data variables.product.prodname_actions %}</a>."
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
```yaml
|
||||
jobs:
|
||||
```
|
||||
</td>
|
||||
<td>
|
||||
Groups together all the jobs that run in the <code>learn-github-actions</code> workflow.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
```yaml
|
||||
check-bats-version:
|
||||
```
|
||||
</td>
|
||||
<td>
|
||||
Defines a job named <code>check-bats-version</code>. The child keys will define properties of the job.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
```yaml
|
||||
runs-on: ubuntu-latest
|
||||
```
|
||||
</td>
|
||||
<td>
|
||||
Configures the job to run on the latest version of an Ubuntu Linux runner. This means that the job will execute on a fresh virtual machine hosted by GitHub. For syntax examples using other runners, see "<a href="/actions/reference/workflow-syntax-for-github-actions#jobsjob_idruns-on">Workflow syntax for {% data variables.product.prodname_actions %}</a>."
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
```
|
||||
</td>
|
||||
<td>
|
||||
Groups together all the steps that run in the <code>check-bats-version</code> job. Each item nested under this section is a separate action or shell script.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
```yaml
|
||||
- uses: {% data reusables.actions.action-checkout %}
|
||||
```
|
||||
</td>
|
||||
<td>
|
||||
The <code>uses</code> keyword specifies that this step will run <code>v3</code> of the <code>actions/checkout</code> action. This is an action that checks out your repository onto the runner, allowing you to run scripts or other actions against your code (such as build and test tools). You should use the checkout action any time your workflow will run against the repository's code.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
```yaml
|
||||
- uses: {% data reusables.actions.action-setup-node %}
|
||||
with:
|
||||
node-version: '14'
|
||||
```
|
||||
</td>
|
||||
<td>
|
||||
This step uses the <code>{% data reusables.actions.action-setup-node %}</code> action to install the specified version of the Node.js (this example uses v14). This puts both the <code>node</code> and <code>npm</code> commands in your <code>PATH</code>.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
```yaml
|
||||
- run: npm install -g bats
|
||||
```
|
||||
</td>
|
||||
<td>
|
||||
The <code>run</code> keyword tells the job to execute a command on the runner. In this case, you are using <code>npm</code> to install the <code>bats</code> software testing package.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
|
||||
```yaml
|
||||
- run: bats -v
|
||||
```
|
||||
</td>
|
||||
<td>
|
||||
Finally, you'll run the <code>bats</code> command with a parameter that outputs the software version.
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
### Visualizing the workflow file
|
||||
|
||||
In this diagram, you can see the workflow file you just created and how the {% data variables.product.prodname_actions %} components are organized in a hierarchy. Each step executes a single action or shell script. Steps 1 and 2 run actions, while steps 3 and 4 run shell scripts. To find more prebuilt actions for your workflows, see "[Finding and customizing actions](/actions/learn-github-actions/finding-and-customizing-actions)."
|
||||
|
||||
|
||||
|
||||
## Viewing the activity for a workflow run
|
||||
|
||||
When your workflow is triggered, a _workflow run_ is created that executes the workflow. After a workflow run has started, you can see a visualization graph of the run's progress and view each step's activity on {% data variables.product.prodname_dotcom %}.
|
||||
|
||||
{% data reusables.repositories.navigate-to-repo %}
|
||||
1. Under your repository name, click **Actions**.
|
||||
|
||||
|
||||
1. In the left sidebar, click the workflow you want to see.
|
||||
|
||||
|
||||
1. Under "Workflow runs", click the name of the run you want to see.
|
||||
|
||||
|
||||
1. Under **Jobs** or in the visualization graph, click the job you want to see.
|
||||
|
||||
|
||||
1. View the results of each step.
|
||||
|
||||
|
||||
1
data/reusables/enterprise/constantly-improving.md
Normal file
1
data/reusables/enterprise/constantly-improving.md
Normal file
@@ -0,0 +1 @@
|
||||
{% data variables.product.product_name %} is constantly improving, with new functionality and bug fixes introduced through {% ifversion ghes %}feature and patch releases{% elsif ghae %}regular updates{% endif %}.
|
||||
@@ -1,5 +0,0 @@
|
||||
{% data variables.product.prodname_ghe_server %} usernames can only contain alphanumeric characters and dashes (`-`). {% data variables.product.prodname_ghe_server %} will normalize any non-alphanumeric character in your account's username into a dash. For example, a username of `gregory.st.john` will be normalized to `gregory-st-john`. Note that normalized usernames also can't start or end with a dash. They also can't contain two consecutive dashes.
|
||||
|
||||
Usernames created from email addresses are created from the normalized characters that precede the `@` character.
|
||||
|
||||
If multiple accounts are normalized into the same {% data variables.product.prodname_ghe_server %} username, only the first user account is created. Subsequent users with the same username won't be able to sign in.
|
||||
@@ -1,10 +0,0 @@
|
||||
This table gives examples of how usernames are normalized in {% data variables.product.prodname_ghe_server %}:
|
||||
|
||||
| Username | Normalized username | Result
|
||||
|----------|---------------------|-------
|
||||
| Ms.Bubbles | `ms-bubbles` | This username is created successfully.
|
||||
| !Ms.Bubbles | `-ms-bubbles` | This username is not created, because it starts with a dash.
|
||||
| Ms.Bubbles! | `ms-bubbles-` | This username is not created, because it ends with a dash.
|
||||
| Ms!!Bubbles | `ms--bubbles` | This username is not created, because it contains two consecutive dashes.
|
||||
| Ms!Bubbles | `ms-bubbles` | This username is not created. Although the normalized username is valid, it already exists.
|
||||
| Ms.Bubbles@example.com | `ms-bubbles` | This username is not created. Although the normalized username is valid, it already exists.
|
||||
@@ -0,0 +1 @@
|
||||
Alternatively, you can configure external authentication for {% data variables.product.product_location %}. If you use external authentication, you must invite people to use your instance through your authentication provider. For more information, see "[About authentication for your enterprise](/admin/identity-and-access-management/managing-iam-for-your-enterprise/about-authentication-for-your-enterprise#external-authentication)."
|
||||
@@ -0,0 +1 @@
|
||||
When you use built-in authentication for {% data variables.product.product_location %}, each person creates a personal account from an invitation or by signing up.
|
||||
@@ -1 +1 @@
|
||||
Optionally, to allow people to use built-in authentication if they don't have an account on your IdP, select **Allow built-in authentication**. For more information, see "[Allowing built-in authentication for users outside your identity provider](/admin/identity-and-access-management/authenticating-users-for-your-github-enterprise-server-instance/allowing-built-in-authentication-for-users-outside-your-identity-provider)."
|
||||
Optionally, to allow people without an account on your external authentication system to sign in with built-in authentication, select **Allow built-in authentication**. For more information, see "[Allowing built-in authentication for users outside your provider](/admin/identity-and-access-management/managing-iam-for-your-enterprise/allowing-built-in-authentication-for-users-outside-your-provider)."
|
||||
|
||||
@@ -1 +1 @@
|
||||
If you want to authenticate some users without adding them to your identity provider, you can configure built-in authentication in addition to SAML SSO. For more information, see "[Allowing built-in authentication for users outside your identity provider](/admin/identity-and-access-management/authenticating-users-for-your-github-enterprise-server-instance/allowing-built-in-authentication-for-users-outside-your-identity-provider)."
|
||||
If you want to allow authentication for some people who don't have an account on your external authentication provider, you can allow fallback authentication to local accounts on {% data variables.product.product_location %}. For more information, see "[Allowing built-in authentication for users outside your provider](/admin/identity-and-access-management/managing-iam-for-your-enterprise/allowing-built-in-authentication-for-users-outside-your-provider)."
|
||||
|
||||
@@ -0,0 +1 @@
|
||||
{% data variables.product.product_name %} normalizes a value from your {% ifversion ghec or ghae %}IdP{% elsif ghes %}external authentication provider{% endif %} to determine the username for each new personal account {% ifversion ghae %}on {% data variables.product.product_name %}{% elsif ghec %}in your enterprise on {% data variables.product.product_location %}{% elsif ghes %}on {% data variables.product.product_location %}{% endif %}.
|
||||
@@ -0,0 +1 @@
|
||||
By default, people who can access your instance while unauthenticated can create a new personal account on your instance.
|
||||
5
data/reusables/saml/saml-ghes-account-revocation.md
Normal file
5
data/reusables/saml/saml-ghes-account-revocation.md
Normal file
@@ -0,0 +1,5 @@
|
||||
{% ifversion ghes %}
|
||||
|
||||
If you remove a user from your IdP, you must also manually suspend them. Otherwise, the account's owner can continue to authenticate using access tokens or SSH keys. For more information, see "[Suspending and unsuspending users](/enterprise/admin/guides/user-management/suspending-and-unsuspending-users)".
|
||||
|
||||
{% endif %}
|
||||
@@ -1 +1 @@
|
||||
By default, your IdP does not communicate with {% data variables.product.product_name %} automatically when you assign or unassign the application. {% data variables.product.product_name %} {% ifversion fpt or ghec %}provisions access to your resources on {% else %}creates a user account {% endif %}using SAML Just-in-Time (JIT) provisioning the first time someone navigates to {% ifversion fpt or ghec %}your resources on {% endif %} {% data variables.product.product_name %} and signs in by authenticating through your IdP. You may need to manually notify users when you grant access to {% data variables.product.product_name %}, and you must manually {% ifversion fpt or ghec %}deprovision access {% else %}deactivate the user account on {% endif %}{% data variables.product.product_name %} during offboarding. You can use SCIM to provision and deprovision {% ifversion fpt or ghec %}access to organizations owned by your enterprise on {% data variables.product.prodname_dotcom_the_website %} {% else %}user accounts and access for {% data variables.product.product_name %} {% endif %}automatically when you assign or unassign the application on your IdP.
|
||||
By default, your IdP does not communicate with {% data variables.product.product_name %} automatically when you assign or unassign the application. {% data variables.product.product_name %} {% ifversion fpt or ghec %}provisions access to your resources on {% else %}creates a user account {% endif %}using SAML Just-in-Time (JIT) provisioning the first time someone navigates to {% ifversion fpt or ghec %}your resources on {% endif %} {% data variables.product.product_name %} and signs in by authenticating through your IdP. You may need to manually notify users when you grant access to {% data variables.product.product_name %}, and you must manually {% ifversion fpt or ghec %}deprovision access {% else %}deactivate the user account on {% endif %}{% data variables.product.product_name %} during offboarding. You can use SCIM to {% ifversion ghec %}provision or deprovision{% elsif ghae %}create or suspend{% endif %} {% ifversion fpt or ghec %}access to organizations owned by your enterprise on {% data variables.product.prodname_dotcom_the_website %} {% else %}user accounts and access for {% data variables.product.product_name %} {% endif %}automatically when you assign or unassign the application on your IdP.
|
||||
|
||||
Reference in New Issue
Block a user