Skip to content

Cap user authorize access #243

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Nov 2, 2022
Merged

Cap user authorize access #243

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
7ac7ac6
Update git token processes
NimRegev Sep 29, 2022
625a7cd
Update token topics
NimRegev Oct 2, 2022
86e162e
Update content
NimRegev Nov 2, 2022
d389874
Update git-tokens.md
NimRegev Nov 2, 2022
a604250
Update git-tokens.md
NimRegev Nov 2, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
122 changes: 67 additions & 55 deletions _docs/administration/user-settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,18 +5,20 @@ group: administration
toc: true
---

As a user in Codefresh, you can manage the access tokens defined in your account, and optionally, enable access for Codefresh support.
As a user in Codefresh, you can manage your account by authorizing access to your Git provider accounts, and optionally, enabling access for Codefresh support.

* Enable access for Codefresh support

Optional. Enable access to your account for troubleshooting purposes.

* Manage Git tokens for authentication
* Authorize Git providers
The Git personal token is a user-specific access token, required to authenticate Git-based actions from Codefresh clients, per provisioned runtime.

The Git personal token is a user-specific access token per provisioned runtime, and is required to authenticate Git-based actions per runtime in Codefresh.
If your admin has set up authentication with OAuth2, you can authorize access to GitHub using OAuth2.
Or, you can always generate a personal access token from GitHub and then add the same to Codefresh to authorize access.
The authorization method depends on the Git provider and on what authorization has been set up by ypur adin.
If your admin has set up authentication with OAuth2, you can authorize access using OAuth2.
Or, you can always generate a personal access token from your Git provider and then add the same to Codefresh to authorize access.

> If you have access to more than one runtime, you can use the same token for multiple runtimes.
You must however authorize access individually for each runtime.

### Enable access for Codefresh support
Enable Codefresh support personnel to access your user account. Access to your account is useful for visibility during troubleshooting.
Expand All @@ -38,77 +40,87 @@ You can disable this security setting at any time.
max-width="50%"
%}

### Authorize Git access with OAuth or personal access tokens
Authorize Git access with OAuth2 if your account admin has set up Codefresh as an OAuth application, or alternatively through personal access tokens from your Git provider.
* For OAuth2: The adminstrator pre-configures the permissions and expiry date. Once you supply your credentials for authorization, you are automatically directed to the Git Personal Tokens page.

#### Generate personal access token for GitHub

### Update/delete Git personal access tokens
Update your Git personal access token for hosted and hybrid runtimes when needed from the User Settings page.
To authorize with OAuth2, you have to supply your credentials. When authorized, you are automatically directed to the Git Personal Tokens page.
#### Authorize access for Bitbucket
Bitbucket requires your Bitbucket account name and a personal access token to authorize access.

* For OAuth2, the permissions and expiry date are pre-configured by the administrator.
* For Git personal access tokens, when generating a new token, make sure you select `repo` scope for commits and other actions.
**Generate personal access token**

1. Log in to your Bitbucket Cloud or Server account.
1. Select **Manage account > Account settings > Personal access tokens**.
1. Select these scopes: `repository write`,`Project read`.
1. Copy the personal access token generated as you will need it to authorize access.

> If you need access to more than one runtime, you can use the same token for multiple runtimes.
You must however authorize GitHub access or add the personal access token individually for each runtime.
**How to**
1. In the Codefresh UI, go to [User Settings](https://g.codefresh.io/2.0/user-settings){:target="\_blank"}.
1. Select the runtime, and then select one of the following:
* To add a token, select **Add Token**.
* To update an existing token by replacing it with a new token, select **Update Token**.
1. From the **Select Git provider** drop-down, select **Bitbucket**.
1. In the **Bitbucket username field**, enter the username of your Bitbucket account.
1. In the **Bitbucket Personal Access Token** field, paste the token you generated.

<!---add new screenshot> -->

{% include
image.html
lightbox="true"
file="/images/getting-started/github-pat.png"
url="/images/getting-started/github-pat.png"
alt="Permissions for Git personal token"
caption="Permissions for Git personal token"
max-width="50%"
%}

To authorize with OAuth2, you have to supply your credentials. When authorized, you are automatically directed to the Git Personal Tokens page.
{:start="6"}
1. Click **Add Token**.
In the Git Personal Access Tokens list, you can see that the new token is assigned to the runtime.

**Before you begin**
* To use a Git PAT, generate a valid personal access token from your Git provider
#### Authorize access for GitHub
**Before you begin**
Make sure you have:
* For Bitbucket only, your Bitbucket account username
* If needed, a _personal access token_ with the required scopes:
* [GitHub]({{site.baseurl}}/docs/reference/git-tokens/#github-tokens)
* [GitLab]({{site.baseurl}}/docs/reference/git-tokens/#gitlab-tokens)
* [Bitbucket]({{site.baseurl}}/docs/reference/git-tokens/#bitbucket-tokens)

**How to**
1. In the CSDP UI, go to [User Settings](https://g.codefresh.io/2.0/user-settings){:target="\_blank"}.

**How to**
1. In the Codefresh UI, go to [User Settings](https://g.codefresh.io/2.0/user-settings){:target="\_blank"}.
1. Select the runtime, and then select one of the following:
* To add a token, select **Add Token**.
* To update an existing token by replacing it with a new token, select **Update Token**.
* To delete an existing token, select **Delete Token**.
1. For OAuth2:
* In the Add Token panel, click **Authorize Access to GitHub**.
> If the application is not registered, you get an error. For example, _Git app not registered_. Contact your admin for help.
* Enter your credentials, and select **Sign In**.
* Complete the verification, for example, if you two-factor authentication is configured.
> If the application is not registered, the button is disabled. Contact your admin for help.
* Click **Authorize Access to GitHub**.
* Enter your credentials, and select **Sign In**.
* Complete the verification if required, as when two-factor authentication is configured, for example.
<!---add new screenshot> -->

{:start="4"}
1. For Git personal access tokens:
* Expand **Advanced authorization options**.
<!---* For Bitbucket, enter your **Bitbucket username**. -->
* In the **Git Personal Access Token** field, paste the token you generated.

{% include
image.html
lightbox="true"
file="/images/administration/user-settings/oauth-user-authentication.png"
url="/images/administration/user-settings/oauth-user-authentication.png"
alt="Authorizing access with OAuth2"
caption="Authorizing access with OAuth2"
max-width="30%"
%}

<!---add new screenshot> -->


{:start="4"}
1. For Git personal access tokens:
Paste the generated token in the **Token** field, and select **+Add Token**.
{:start="5"}
1. Click **Add Token**.
In the Git Personal Access Tokens list, you can see that the new token is assigned to the runtime.





{::nomarkdown}
<br>
{:/}


{% include
image.html
lightbox="true"
file="/images/administration/user-settings/user-settings-pat.png"
url="/images/administration/user-settings/user-settings-pat.png"
alt="Adding a Git personal access token"
caption="Adding a Git personal access token"
max-width="30%"
%}



The token is generated and you are redirected to the User Settings page where you can see the new Git token assigned to the runtime.



### Related articles
[Git tokens in Codefresh]({{site.baseurl}}/docs/reference/git-tokens/)
105 changes: 71 additions & 34 deletions _docs/reference/git-tokens.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,61 +10,98 @@ toc: true


Codefresh requires two types of Git tokens for authentication:
* A token per runtime (Git runtime token)
* A personal access token for each runtime, unique to every user (Git user token)
* Git runtime token for runtime installation
Used by:
* Argo CD clone repositories and pull changes to sync the desired state in Git to the live state on the cluster.
* Argo Events to create webhooks in Git repositories for Event Sources in Delivery Pipelines

The Git runtime token is runtime-specific but not user-specific.


* Git user token, a user-specific personal access token for each runtime, unique to every user
Unique to every user, the Git user token is used to authenticate the user for client-based actions, such as Git clone and push operations on specific repositories.
Git user token requirements translate to permission scopes which differ for the different Git providers.

After installation, you need to authorize Git access for every provisioned runtime either through OAuth2 or through a personal access token from your Git provider.
Every user can view the list of runtimes and tokens assigned to each runtime in [User Settings](https://g.codefresh.io/2.0/user-settings){:target="\_blank"}. Codefresh flags and notifies you of invalid, revoked, or expired tokens.



You can update expired, revoked, or invalid Git runtime and personal user tokens.

### Git runtime tokens
The Git runtime token is required to provision Codefresh runtimes. The Git runtime token is specific to a runtime, and is mandatory for runtime installation.
An expired, revoked, or invalid Git runtime token is flagged by a notification in the UI. You can then generate a new Git runtime token from your Git provider, and update it in Codefresh.
The Git runtime token is mandatory for runtime installation.

#### Git runtime token permissions
Git runtime tokens need both repo and admim repo access to create webhooks for Git events.
{::nomarkdown}
</br>
{:/}

{% include
image.html
lightbox="true"
file="/images/getting-started/quick-start/quick-start-git-event-permissions.png"
url="/images/getting-started/quick-start/quick-start-git-event-permissions.png"
alt="Permissions for Git runtime token"
caption="Permissions for Git runtime token"
max-width="60%"
%}
#### GitHub and GitHub Enterprise runtime token scopes

* `repo`
* `admin:repo_hook`

{::nomarkdown}
</br>
{:/}

#### How to update a Git runtime token
Update Git runtime tokens when needed.
#### GitLab Cloud and GitLab Server runtime token scopes

**Before you begin**
* Generate a new runtime token with the correct permissions
* `api`
* `read_repository`

**How to**
{::nomarkdown}
</br>
{:/}

1. In the Codefresh UI, when you see a notification, select **[Update Token]**.
In the **Runtimes** page, runtimes with invalid tokens are prefixed by the key icon. Mouse over shows invalid token.
1. Select the runtime, and then on the top-right of the page, select and then **+Add Token**.
1. Paste the generated personal access token.
1. If there are no validation errors, select **Add**.
#### Bitbucket Cloud & Bitbucket Server runtime token scopes

* `Project admin`
* `Repository write`
* `Project read`

{::nomarkdown}
</br></br>
{:/}

### Git personal tokens
The Git personal token is a user-specific personal access token per provisioned runtime. Unique to each user, it is required to authenticate Git-based actions per runtime in Codefresh.
If not provided during runtime installation, user can add personal access tokens (PATs) after installation through [User Settings](https://g.codefresh.io/2.0/user-settings){:target="\_blank"} in the UI, using either OAuth to authorize access or generate one from GitHub.
The Git personal token is a user-specific personal access token per provisioned runtime. Unique to each user, it is required after installation to authenticate Git-based actions per runtime in Codefresh.

If users have access to multiple runtimes, they can use the same personal access token for all the runtimes.
> Users must configure the token for each runtime.
> If you have access to multiple runtimes, you can use the same personal access token for all the runtimes.
You must configure the token for each runtime.

#### Git personal token permissions
Git personal tokens need repo access for commits and other actions.
{::nomarkdown}
</br>
{:/}

{% include
#### GitHub & GitHub Enterprise personal user token scopes
* `repo`

<!---{% include
image.html
lightbox="true"
file="/images/getting-started/github-pat.png"
url="/images/getting-started/github-pat.png"
alt="Permissions for Git personal token"
caption="Permissions for Git personal token"
max-width="60%"
%}
%}-->
{::nomarkdown}
</br>
{:/}

#### GitLab Cloud & GitLab Server personal user token scopes

* `write_repository` (includes `read-repository`)
* `api-read`

{::nomarkdown}
</br>
{:/}

#### Bitbucket Cloud & Bitbucket Server personal user token scopes

* `Project read`
* `Repository write`

### Related articles
[User settings]({{site.baseurl}}/docs/administration/user-settings/)
Loading