|
| 1 | +--- |
| 2 | +title:"Set up OAuth2 authentication" |
| 3 | +description:"" |
| 4 | +group:administration |
| 5 | +toc:true |
| 6 | +--- |
| 7 | + |
| 8 | +Easily Connect Codefresh to your Git provider using OAuth2. |
| 9 | +Codefresh integrates with Git to sync repositories to your clusters, implementing Git-based operations when creating resources such as Delivery Pipelines, and to enrich Images with valuable information. |
| 10 | + |
| 11 | + |
| 12 | +Codefresh supports OAuth2 or Personal Access Tokens (PATs) for authentication: |
| 13 | + |
| 14 | +* OAuth2 with Codefresh OAuth Application or custom OAuth2 Application |
| 15 | + |
| 16 | + OAuth2 is the preferred authentication mechanism, currently supported for GitHub. You have the option to use the default pre-defined Codefresh OAuth Application, or your own Oauth2 Application in your Git account. |
| 17 | + To use your own Oauth2 GitHub Application, create a secret on your K8s cluster and configure it in Authentication > Settings. See[Create a custom OAuth2 provider account](#create-a-custom-oauth2-provider-account) in this article. |
| 18 | + |
| 19 | + |
| 20 | +>A runtime can have only one active account for authentication. |
| 21 | +
|
| 22 | +* Token-based authentication using PAT |
| 23 | + With token-based authentication, users must enter their personal access tokens when prompted to authorize access. Token-based authentication for users is described in[Managing Git personal access tokens]({{site.baseurl}}/docs/administration/user-settings/). |
| 24 | + |
| 25 | + |
| 26 | +###Authentication provider accounts |
| 27 | +The authentication accounts created for a provider are displayed in the[Authentication](https://g.codefresh.io/2.0/account-settings/authentication?providerName=github){:target="\_blank"}. |
| 28 | + |
| 29 | +{% include |
| 30 | + image.html |
| 31 | + lightbox="true" |
| 32 | + file="/images/authentication/authentication-list.png" |
| 33 | + url="/images/authentication/authentication-list.png" |
| 34 | + alt="Git provider authentication accounts" |
| 35 | + caption="Git provider authentication accounts" |
| 36 | + max-width="60%" |
| 37 | + %} |
| 38 | +The authentication accounts are organized by Runtimes. Every runtime can have a single authentication account. |
| 39 | +The Type column identifies the provider account type as either Codefresh or Custom. You can change the provider type to Codefresh or Custom or select manual token entry as the authentication. |
| 40 | + |
| 41 | + |
| 42 | +###Create a custom OAuth2 provider account |
| 43 | +Codefresh account administrators can create an OAuth2 Application in GitHub, and set up authentication within Codefresh. Users in Codefresh can then authorize access to GitHub using OAuth2, instead of generating a personal access token to perform Git-based actions. |
| 44 | + |
| 45 | +To set up OAuth2 authorization for GitHub in Codefresh, you must: |
| 46 | +* Create a GitHub OAuth2 Application for Codefresh |
| 47 | +* Create a K8s`secret` in the runtime cluster with OAuth2 Application credentials |
| 48 | +* Configure OAuth2 settings in Codefresh to create a K8s`ConfigMap` that references the secret |
| 49 | + |
| 50 | +####Step 1: Create GitHub OAuth2 Application |
| 51 | +Create and register an OAuth App under your organization to authorize Codefresh. |
| 52 | + |
| 53 | +>Make sure your OAuth app has`repo` scope with write access to code. For more information, see[Scopes for OAuth apps](https://docs.github.com/en/developers/apps/building-oauth-apps/scopes-for-oauth-apps){:target="\_blank"}. |
| 54 | +
|
| 55 | +1. Follow the step-by-step instructions in[GitHub](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app){:target="\_blank"}. |
| 56 | + For the`Authorization callback URL`, enter this value: |
| 57 | +`<ingressHost>/app-proxy/api/git-auth/github/callback` |
| 58 | + where: |
| 59 | +`<ingressHost>` is the IP address or URL of the ingress host in the runtime cluster. |
| 60 | +1. Make sure**Enable Device Flow** is_not_ selected. |
| 61 | +1. Select**Register application**. |
| 62 | + The client ID is automatically generated, and you are prompted to generate the client secret. |
| 63 | +1. Select**Generate a new client secret**, and copy the generated secret. |
| 64 | +1. Note down the following: |
| 65 | +* Application ID from the URL |
| 66 | +* Client ID and the client secret |
| 67 | + |
| 68 | +You need them to create the K8s secret for the GitHub OAuth2 application. |
| 69 | + |
| 70 | +####Step 2: Create a K8s secret resource in the runtime cluster |
| 71 | +Create a K8s secret in the runtime cluster, using the example below as a guideline. You must define the application ID (`appId`), client ID (`clientId`) and the client secret (`clientSecret`) from the GitHub OAuth2 Application you created, and the GitHub URL (`url`). |
| 72 | + |
| 73 | +>All fields in the secret_must be_ encoded in`base64`. |
| 74 | + To encode, use this command:`echo -n VALUE | base64`. |
| 75 | + |
| 76 | + |
| 77 | +**Before you begin** |
| 78 | + |
| 79 | +Make sure you have the following handy: |
| 80 | +* Application ID from the application's URL |
| 81 | +* Client ID |
| 82 | +* Client secret |
| 83 | +* GitHub URL |
| 84 | + |
| 85 | +**How to** |
| 86 | + |
| 87 | +1. Create the manifest for the K8s secret resource. |
| 88 | + |
| 89 | +```yaml |
| 90 | +apiVersion:v1 |
| 91 | +kind:Secret |
| 92 | +type:Opaque |
| 93 | +metadata: |
| 94 | +name:github-oauth2 |
| 95 | +namespace:<RUNTIME_NAME># replace with the name of the runtime |
| 96 | +labels: |
| 97 | +codefresh_io_entity:git-pat-obtainer-sec |
| 98 | +data: |
| 99 | +appId:# application ID of your OAuth app from GitHub |
| 100 | +clientId:# client ID of your OAuth app from GitHub |
| 101 | +clientSecret:# client secret of your OAuth app from GitHub |
| 102 | +url:https://github.com# GitHub provider URL which by default is github.com, unless self-hosted provider |
| 103 | +``` |
| 104 | +
|
| 105 | +{:start="2"} |
| 106 | +1. Apply the secret to the runtime cluster: |
| 107 | +`kubectl apply -f <filename>` |
| 108 | + |
| 109 | + |
| 110 | +#### Step 3: Configure OAuth2 settings in Codefresh |
| 111 | + |
| 112 | +To complete custom provider authentication, configure the settings for the OAuth2 GitHub application in Codefresh. Configuring the settings creates a K8s ConfigMap that references the OAuth secret credentials. When configuring the settings, you can work in Form mode, or directly in the YAML manifest. |
| 113 | + |
| 114 | +>Important: |
| 115 | +> The values for all the settings in the ConfigMap are the `keys` in the secret file. |
| 116 | + |
| 117 | +1. In the Codefresh UI, go to [Authentication](https://g.codefresh.io/2.0/account-settings/authentication?providerName=github){:target="\_blank"}. |
| 118 | +The list always shows the default predefined Codefresh provider account and custom provider accounts created, organized by Runtime, Type (Codefresh or Custom) and Status. |
| 119 | +1. From the list, select the runtime to which to apply the current configuration. The runtime must be identical to the runtime to which you saved the K8s secret. |
| 120 | +1. Click **Edit** and then select **Use custom provider**. |
| 121 | +> If you have managed clusters registered to the selected runtime, the authentication account is available to all the clusters. |
| 122 | +The settings page is opened in **Form** mode. |
| 123 | + |
| 124 | +{% include |
| 125 | +image.html |
| 126 | +lightbox="true" |
| 127 | +file="/images/authentication/oauth-custom-settings.png" |
| 128 | +url="/images/authentication/oauth-custom-settings.png" |
| 129 | +alt="OAuth settings for custom provider in Codefresh" |
| 130 | +caption="OAuth settings for custom provider in Codefresh" |
| 131 | +max-width="50%" |
| 132 | +%} |
| 133 | + |
| 134 | +{:start="4"} |
| 135 | +1. Configure the settings for the **GitHub OAuth2 Application**, either in **Form** or in **YAML** modes: |
| 136 | +* **Secret Name**: The name of the K8s secret file you created in the runtime cluster. |
| 137 | +* **Secret Namespace**: The namespace in the runtime cluster where you created the K8s secret. |
| 138 | +* **Application ID**: The `key` representing the OAuth application ID in the K8s secret. For example, `appId`. |
| 139 | +* **Client ID**: The `key` representing the client ID in the K8s secret. For example, `clientId`. |
| 140 | +* **Client Secret**: The `key` representing the client secret in the K8s secret. For example, `clientSecret`. |
| 141 | +* **URL**: The `key` representing the provider URL in the K8s secret. For example, `url`. |
| 142 | + |
| 143 | +{:start="5"} |
| 144 | +1. Click **Commit**. |
| 145 | +The Commit Changes panel shows a summary of the settings and the final version of the YAML manifest in read-only mode. |
| 146 | + |
| 147 | +{% include |
| 148 | +image.html |
| 149 | +lightbox="true" |
| 150 | +file="/images/authentication/oauth-custom-commit-settings.png" |
| 151 | +url="/images/authentication/oauth-custom-commit-settings.png" |
| 152 | +alt="OAuth settings for custom provider in Codefresh" |
| 153 | +caption="OAuth settings for custom provider in Codefresh" |
| 154 | +max-width="50%" |
| 155 | +%} |
| 156 | + |
| 157 | +{:start="6"} |
| 158 | +1. From the **Select Git Source** list, select the Git Source in which to store the manifest for the `ConfigMap` you are creating. |
| 159 | +The list displays all the Git Sources created for the selected runtime. |
| 160 | +1. Optional. Enter a commit message. |
| 161 | +1. At the bottom-right, click **Commit** once again. |
| 162 | + |
| 163 | +You have completed the setup to authorize Codefresh as an OAuth App in GitHub. |
| 164 | + |
| 165 | +### Select authentication account for runtime |
| 166 | +For a Git provider and a runtime account, switch between the Codefresh, Custom provider account if one exists, or enforce token-based authentication. |
| 167 | + |
| 168 | +1. In the Codefresh UI, go to [Authentication](https://g.codefresh.io/2.0/account-settings/authentication?providerName=github){:target="\_blank"}. |
| 169 | +1. Select the runtime, and click  **Edit**. |
| 170 | +1. Select the OAuth authentication provider account. |