Review ipsilon SOP

Signed-off-by: Michal Konečný <mkonecny@redhat.com>

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 ]

modules/sysadmin_guide/pages/ipsilon.adoc

@@ -2,17 +2,15 @@
 
 == Contents
 
-[arabic]
+* <<_contact_information>>
-. Contact Information
+* <<_description>>
-. Description
+* <<_known_issues>>
-. Known Issues
+* <<_restarting>>
-. ReStarting
+* <<_configuration>>
-. Configuration
+* <<_common_actions>>
-. {blank}
+** <<_openid_connect_scope_registration>>
-+
+** <<_generate_an_openid_connect_token>>
-Common actions::
+** <<_create_openid_connect_secrets_for_apps>>
-  6.1. Registering OpenID Connect Scopes 6.2. Generate an OpenID Connect
-  token 6.3. 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
+* ipsilon01.iad2.fedoraproject.org
-  ipsilion01.stg.phx2.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
-* 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
-* 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
+** _claims_: A list of additional "claims" (pieces of user information) an
-application will get when the user
+application will get when the user consents to this scope. For most scopes, this will be the empty list.
-** 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
+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
+(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.