diff --git a/modules/sysadmin_guide/nav.adoc b/modules/sysadmin_guide/nav.adoc index 96f341d..30428c6 100644 --- a/modules/sysadmin_guide/nav.adoc +++ b/modules/sysadmin_guide/nav.adoc @@ -53,7 +53,7 @@ ** xref:infra-raidmismatch.adoc[Infrastructure Raid Mismatch Count - SOP] ** xref:infra-repo.adoc[Infrastructure Yum Repo - SOP] ** xref:infra-retiremachine.adoc[Infrastructure retire machine - SOP] -** xref:ipsilon.adoc[ipsilon - SOP in review ] +** xref:ipsilon.adoc[Ipsilon Infrastructure - SOP] ** xref:iscsi.adoc[iscsi - SOP in review ] ** xref:jenkins-fedmsg.adoc[jenkins-fedmsg - SOP in review ] ** xref:kerneltest-harness.adoc[kerneltest-harness - SOP in review ] diff --git a/modules/sysadmin_guide/pages/ipsilon.adoc b/modules/sysadmin_guide/pages/ipsilon.adoc index b32539e..d32ddbd 100644 --- a/modules/sysadmin_guide/pages/ipsilon.adoc +++ b/modules/sysadmin_guide/pages/ipsilon.adoc @@ -2,17 +2,15 @@ == Contents -[arabic] -. Contact Information -. Description -. Known Issues -. ReStarting -. Configuration -. {blank} -+ -Common actions:: - 6.1. Registering OpenID Connect Scopes 6.2. Generate an OpenID Connect - token 6.3. Create OpenID Connect secrets for apps +* <<_contact_information>> +* <<_description>> +* <<_known_issues>> +* <<_restarting>> +* <<_configuration>> +* <<_common_actions>> +** <<_openid_connect_scope_registration>> +** <<_generate_an_openid_connect_token>> +** <<_create_openid_connect_secrets_for_apps>> == Contact Information @@ -25,11 +23,10 @@ Primary upstream contact:: Backup upstream contact:: Simo Sorce - FAS: simo (irc: simo) Howard Johnson - FAS: merlinthp (irc: MerlinTHP) Rob Crittenden - FAS: rcritten (irc: rcrit) -Location:: - Phoenix Servers:: - ipsilon01.phx2.fedoraproject.org ipsilon02.phx2.fedoraproject.org - ipsilion01.stg.phx2.fedoraproject.org. +* ipsilon01.iad2.fedoraproject.org +* ipsilon02.iad2.fedoraproject.org +* ipsilion01.stg.iad2.fedoraproject.org Purpose:: Ipsilon is our central authentication service that is used to authenticate users agains FAS. It is seperate from FAS. @@ -51,13 +48,13 @@ replicate to the all the systems. == Restarting To restart the application you simply need to ssh to the servers for the -problematic region and issue an 'service httpd restart'. This should +problematic region and issue an `service httpd restart`. This should rarely be required. == Configuration Configuration is handled by the ipsilon.yaml playbook in Ansible. This -can also be used to reconfigure application, if that becomes nessecary. +can also be used to reconfigure application, if that becomes necessary. == Common actions @@ -68,33 +65,27 @@ This section describes some common configuration actions. As documented on https://fedoraproject.org/wiki/Infrastructure/Authentication, application developers can request their own scopes. When a request for -this comes in, look in ansible/roles/ipsilon/files/oidc_scopes/ and copy +this comes in, look in _ansible/roles/ipsilon/files/oidc_scopes/_ and copy an example module. Copy this to a new file, so we have a file per scope set. Fill in the information: -____ -* name is an Ipsilon-internal name. This should not include any spaces -* display_name is the name that is displayed to the category of scopes +* _name_ is an Ipsilon-internal name. This should not include any spaces +* _display_name_ is the name that is displayed to the category of scopes to the user -* scopes is a dictionary with the full scope identifier (with namespace) +* _scopes_ is a dictionary with the full scope identifier (with namespace) as keys. The values are dicts with the following keys: -+ -____ -** display_name: The complete display name for this scope. This is what +** _display_name_: The complete display name for this scope. This is what the user gets shown to accept/reject -** claims: A list of additional "claims" (pieces of user information) an -application will get when the user -** consents to this scope. For most scopes, this will be the empty list. -____ -____ +** _claims_: A list of additional "claims" (pieces of user information) an +application will get when the user consents to this scope. For most scopes, this will be the empty list. -In ansible/roles/ipsilon/tasks/main.yml, add the name of the new file -(without .py) to the with_items of "Copy OpenID Connect scope +In _ansible/roles/ipsilon/tasks/main.yml_, add the name of the new file +(without .py) to the _with_items_ of "Copy OpenID Connect scope registrations"). To enable, open -ansible/roles/ipsilon/templates/configuration.conf, and look for the +_ansible/roles/ipsilon/templates/configuration.conf_, and look for the lines starting with "openidc enabled extensions". Add the name of the plugin (in the "name" field of the file) to the environment this -scopeset has been requested for. Run the ansible ipsilon.yml playbook. +scopeset has been requested for. Run the ansible _ipsilon.yml_ playbook. === Generate an OpenID Connect token @@ -108,12 +99,13 @@ The `SERVICE_NAME` (the required positional argument) is the name of the application that wants to use the token to perform actions against another service. -To generate the scopes, you can visit our link:[authentication] docs and +To generate the scopes, you can visit our +https://fedoraproject.org/wiki/Infrastructure/Authentication[authentication] docs and find the service you want the token to be used for. Each service has a base namespace (a URL) and one or more scopes for that namespace. To form a scope for this script, you concatenate the namespace of the service with the scope you want to grant the service. You can provide -the script the -s flag multiple times if you want to grant more than one +the script the `-s` flag multiple times if you want to grant more than one scope to the same token. As an example, to give Bodhi access to create waivers in WaiverDB, you @@ -152,7 +144,7 @@ Ansible variable they can use to access it.) Application wanting to use OpenID Connect need to register against our OpenID Connect server (Ipsilon). Since we do not allow self-registration -(except on iddev.fedorainfracloud.org) for obvious reasons, the secrets +(except on _iddev.fedorainfracloud.org_) for obvious reasons, the secrets need to be created and configured per application and environment (production vs staging). @@ -199,16 +191,14 @@ maintained by the Fedora Infrastructure the first 11 lines (up to understanding of OpenID Connect and Ipsilon. [NOTE] -.Note ==== `client_id` in `ipsilon_internal` must match the begining of the line, and the `client_id` field must either match the begining of the line or be `null` as in the example here. ==== [NOTE] -.Note ==== -In our OpenID connect server, OIDC.user_getfield('nickname') will return +In our OpenID connect server, `OIDC.user_getfield('nickname')` will return the FAS username, which we know from FAS is unique. However, not all OpenID Connect servers enforce this constraint, so the application code may rely on the `sub` which is the only key that is sure to be unique.