pingou / centos / sig-guide

Forked from centos/sig-guide 2 years ago
Clone

Blame docs/auth.md

f8825f
# Authentication
80c633
8a162e
!!! note
8a162e
    CentOS and Fedora are using the same authentication platform so if you already have a Fedora account (aka FAS) that means that you already have a CentOS account and you just need to be added in specific CentOS groups there !
8a162e
991dca
## Creating your account
991dca
991dca
You can create your account on our community portal running on [https://accounts.centos.org](https://accounts.centos.org).
991dca
f8825f
To register/create an account, just click on "Register" on the portal and follow the process.
991dca
More information and user documentation is available on consolidated [online documentation](https://docs.fedoraproject.org/en-US/fedora-accounts/) for the portal
991dca
991dca
## Modifying your account
991dca
991dca
Once logged into the portal (still on https://accounts.centos.org) you can modify/edit your profile and see your group membership.
991dca
991dca
Some settings you can modify directly:
991dca
991dca
 * First/Last Name
991dca
 * Locale
991dca
 * Timezone
991dca
 *  email address (attention that it needs to be a valid email address)
991dca
 *  other personal details
991dca
 *  your password
991dca
 *  adding/removing OTP tokens (see below for 2FA)
f8825f
 *  ssh and gpg public keys
991dca
991dca
### Enabling 2FA on your account (optional)
991dca
It's adviced (but not mandatory) to implement 2 Factor Authentication on your account (for some critical accounts, that's though required).
991dca
991dca
You can add one (or more, adviced) OTP tokens on your profile. Known to work solutions so far :
991dca
991dca
 * Yubikey (4 and above, that supports OTP) : through rpm pkg yubioath-desktop
991dca
 * FreeOTP (available on Google Play Store)
991dca
 * OTPClient (available as rpm pkg and flatpak/flathub)
f8825f
 * others (list is non exhaustive)
991dca
991dca
More informations about 2FA is available on specific [portal documentation](https://docs.fedoraproject.org/en-US/fedora-accounts/user/#twofactor)
991dca
991dca
80c633
## SIG group membership
991dca
991dca
There is no current form that you can use to be added in a SIG group but you have to reach out to a SIG chair (having delegated rights to add/remove people in the SIG group you want to join) and he can then add you, after having confirmed that you can be onboarded in the SIG
991dca
74ae2b
To know people who can "sponsors" you in a SIG/group, you can , once authenticated, search for a group on the portal and then see people listed under the "Sponsors" area (for example, consider the [Automotive SIG](https://accounts.centos.org/group/sig-automotive/) )
991dca
991dca
991dca
## Retrieving your TLS certificate
991dca
991dca
To be able to request a signed TLS certificate, you need first to install the cli tool that will use kerberos auth first to request a locally generated (automatic) CSR to be sent to IPA for signing operation and you'll then get your certificate back.
991dca
463be8
Supported Linux distributions: CentOS Stream 8/9 (or el8/el9 variant) , Fedora 33 and beyond
991dca
991dca
```
463be8
sudo dnf install -y epel-release # only if you are using CentOS Stream or an EL variant
991dca
sudo dnf install -y centos-packager
991dca
```
991dca
991dca
Your user certificate bundle comes in the form of 1 file:
991dca
991dca
~/.centos.cert : PEM file with your X509 Client Certificate and Key
991dca
991dca
To generate your certificate you can use the 'centos-cert' tool included in the centos-packager package:
991dca
991dca
```
f8825f
 centos-cert
991dca
991dca
You need to call the script like this : /usr/bin/centos-cert -arguments
991dca
 -u : username ([REQUIRED] : your existing ACO/FAS username)
991dca
 -v : just validates the existing TLS certificate ([OPTIONAL])
991dca
 -r : REALM to use for kerberos ([OPTIONAL] : defaults to FEDORAPROJECT.ORG)
991dca
 -f : fasjson url ([OPTIONAL]: defaults to https://fasjson.fedoraproject.org)
991dca
 -h : display this help
991dca
```
991dca
991dca
If you've signed up with the account name `tuser`, you can generate your new certificate like this:
991dca
991dca
```
f8825f
    [tuser@myworkstation]$ centos-cert -u tuser
991dca
```
991dca
f8825f
!!! note
991dca
    Attention that centos-cert -u tuser will request a new certificate, so that will automatically revoke any other certificate you had in the past. If you need to use cbs/koji on multiple machines, just copy the files mentioned above on the other machine.
991dca
991dca
!!! warning
991dca
    Important note WRT OTP: If you have enabled Two Factor auth, you absolutely need to get a valid kerberos ticket through other step *before* using centos-cert. See details on the [Fedora Accounts Documentation](https://docs.fedoraproject.org/en-US/fedora-accounts/user/#twofactor) for this
991dca
74ae2b
### TLS part for Staging env
74ae2b
74ae2b
In case you'd need to interact with .stg. services (like [https://cbs.stg.centos.org](https://cbs.stg.centos.org)) that are relying on TLS auth, it's worth knowing that you'd need to get a different TLS cert.
74ae2b
74ae2b
That means that you need an account from [https://accounts.stg.centos.org](https://accounts.stg.centos.org) , which isn't linked to production accounts.centos.org IPA backend.
74ae2b
74ae2b
It's adviced to use a different container or home directory to retrieve your STG cert, and you can just point to [https://fasjson.stg.fedoraproject.org](https://fasjson.stg.fedoraproject.org) url (option `-f` for centos-cert)
74ae2b
74ae2b
You can manually create (nothing -yet- in `centos-packager` for it) a ~/.koji/cbs-stg.conf that looks like this : 
74ae2b
74ae2b
```
74ae2b
[cbs-stg]
74ae2b
74ae2b
;url of XMLRPC server
74ae2b
server = https://cbs.stg.centos.org/kojihub/
74ae2b
74ae2b
;url of web interface
74ae2b
weburl = https://cbs.stg.centos.org/koji
74ae2b
74ae2b
;url of package download site
74ae2b
topurl = http://cbs.stg.centos.org/kojifiles
74ae2b
74ae2b
;path to the koji top directory
74ae2b
topdir = /mnt/koji
74ae2b
74ae2b
;client certificate
74ae2b
cert = ~/.centos-stg.cert
74ae2b
74ae2b
;certificate of the CA that issued the HTTP server certificate
74ae2b
serverca = /etc/pki/tls/certs/ca-bundle.trust.crt
74ae2b
74ae2b
```
74ae2b
74ae2b
!!! warning
74ae2b
    You have to also ensure that your TLS file is renamed to correct filename !
74ae2b
74ae2b
And you can then call koji like this : 
74ae2b
74ae2b
```
74ae2b
koji -c ~/.koji/cbs-stg.conf -p cbs-stg
74ae2b
```
991dca
03562e
## Linking your CentOS account to gitlab
03562e
03562e
The first thing to understand is that gitlab will "link" an existing account
03562e
with third party authentication system. In other words, you need to have a
03562e
gitlab account and be logged in onto gitlab.com before you can associate your
03562e
account with the CentOS Account System (ACO).
03562e
03562e
So if you do not have a gitlab account, create one and log with it into [
03562e
https://gitlab.com](https://gitlab.com). Then visit the following link [
03562e
https://id.centos.org/gitlab](https://id.centos.org/gitlab) to associate your
03562e
account with CentOS' Account System.
03562e
03562e
From there on, everytime you visit this link, your group membership defined in
03562e
ACO, will be refreshed on gitlab.
541244
541244
## Authenticating to CentOS services with your accounts 
541244
Some infra services (but not all) are using the new authentication platform to give you access.
541244
541244
### IdP for CentOS service 
541244
541244
As IPA backend itself doesn't provide IdP features, we have the service https://id.centos.org that is registered in IPA, and so that can be used as IdP, to support OpenID, OpenIDC, SAML2 authentication for applications/services that can recognize and use such protocol/standards
541244
541244
### Authenticating with your username and password 
541244
Once you'll try to login to a service that requires auth, you'll be automatically redirected to https://id.centos.org.
541244
You can then provide your username and password combination to proceed with authentication and be then redirected to the initial service you wanted to auth with.
541244
541244
!!! warning
541244
    If you have enabled 2FA (see above), your password field is a combination of '''both''' your real password and the OTP token
541244
541244
541244
### Enabling kerberos for IdP
541244
If you want to instead use your kerberos ticket to auth against services (and so transparently) and not having to type your user/password (+OTP if enabled) combination each time, you can just configure your workstation to transparently use gssapi authentication against https://id.centos.org
541244
541244
For this you need to first install a mandatory package, that has the needed configuration for kerberos :
541244
541244
```
463be8
sudo dnf install -y epel-release # Only on EL , not needed on Fedora
541244
sudo dnf install -y fedora-packager
541244
```
541244
541244
!!! important
541244
    You need to have fedora-packager >= 0.6.0.5-2 installed on your system for this to work !
541244
541244
541244
After that, you can kinit as usual (see [[https://docs.fedoraproject.org/en-US/fedora-accounts/user/#pkinit|upstream doc]] and you should have your kerberos ticket ready to be used for authentication
541244
541244
You still need to configure your browser :
541244
541244
### Firefox settings 
541244
While in Firefox, type '''about:config''' in the location/url bar and press enter.
541244
You can then edit the following key/value : 
541244
541244
```
541244
network.negotiate-auth.trusted-uris: .fedoraproject.org,.centos.org
541244
```
541244
541244
Close and then firefox will allow kerberos/GSSAPI transaction to proceed, meaning that next time one service will redirect you to https://id.centos.org, you'll be automatically logged on through kerberos (no need to specify again user/password)
541244
541244
### Chrome/Chromium
541244
Depending on Chrome or Chromium, the path of the json file to create is different :
541244
541244
 * Chrome : /etc/opt/chrome/policies/managed/fedora-centos.json
541244
 * Chromium : /etc/chromium/policies/managed/fedora-centos.json
541244
541244
You should have there something like this : 
541244
541244
```
541244
{
541244
  "AuthServerAllowlist": "*.fedoraproject.org,*.centos.org",
541244
  "AuthNegotiateDelegateAllowlist": "*.fedoraproject.org,*.centos.org"
541244
}
541244
```
541244
541244
!!! warning
541244
    Chrome/Chromium browsers with version < '100' were using different names like ''AuthServerWhitelist'' and ''AuthNegotiateDelegateWhitelist'' so check version and adapt accordingly
541244
541244